Contributing to Bufrnix

Bufrnix is an open-source project, and contributions are welcome! This guide explains how to contribute to Bufrnix, whether you’re adding new features, fixing bugs, or improving documentation.

Getting Started

Fork the repository: Start by forking the Bufrnix repository on GitHub.
Clone your fork: Clone your fork to your local machine:
Terminal window
```
git clone https://github.com/your-username/bufrnix.git
cd bufrnix
```
Set up the development environment:
Terminal window
```
# Enter the Nix development shell
nix develop
```

Project Structure

Understanding the project structure will help you navigate and modify the codebase:

bufrnix/
├── doc/                    # Documentation site
├── examples/               # Example projects
├── flake.nix               # Main Nix flake file
├── src/
│   ├── languages/          # Language-specific modules
│   │   ├── dart/
│   │   ├── go/
│   │   ├── js/
│   │   ├── php/
│   │   └── ...
│   └── lib/                # Core library code
│       ├── bufrnix-options.nix  # Configuration schema
│       ├── mkBufrnix.nix        # Main implementation
│       └── utils/
└── README.md

Adding a New Language Module

To add support for a new programming language to Bufrnix:

Create a language directory: Create a new directory under src/languages/ with the name of your language (e.g., src/languages/rust/).

Implement the language module: Create a default.nix file in your language directory that follows the language module interface:

{ pkgs, lib, config, ... }:

let
  cfg = config.bufrnix.rust;
in {
  # Runtime inputs required for code generation
  runtimeInputs = with pkgs; [
    # Required packages for Rust code generation
    protobuf
    rustPackages.prost-build
  ];

  # Protoc plugin configuration
  protocPlugins = [
    {
      name = "rust";
      package = pkgs.rustPackages.protoc-gen-prost;
      out = cfg.out;
      opt = cfg.opt;
    }
  ];

  # Command options for protoc
  commandOptions = [
    # Additional command line options
  ];

  # Initialization hooks
  initHooks = ''
    echo "Initializing Rust code generation..."
    mkdir -p ${cfg.out}
  '';

  # Code generation hooks
  generateHooks = ''
    echo "Generating Rust code..."
    # Additional shell code for Rust-specific tasks
  '';
}

Add gRPC or other plugin support: Create additional files for plugin-specific functionality (e.g., grpc.nix):
src/languages/rust/grpc.nix
```
{ pkgs, lib, config, ... }:

let
  cfg = config.bufrnix.rust.grpc;
in {
  # Implementation for gRPC support
  # ...
}
```

Update configuration schema: Add your language’s configuration options to src/lib/bufrnix-options.nix:

# Add to the language options
rust = {
  enable = mkEnableOption "Rust code generation";

  out = mkOption {
    type = types.str;
    default = "gen/rust";
    description = "Output directory for Rust code";
  };

  opt = mkOption {
    type = types.attrsOf types.nullOr;
    default = {};
    description = "Options for Rust code generation";
  };

  # Additional plugin-specific options
  grpc = {
    enable = mkEnableOption "gRPC support for Rust";
    # ...
  };
};

Test your implementation: Create an example project that uses your new language module and test that code generation works correctly.
Update documentation: Add documentation for your new language module in the appropriate places, including:
- Update the language support reference
- Add an example project if possible
- Update the README.md with the new supported language

Pull Request Process

Create a branch:

git checkout -b feature/new-language-support

Make your changes: Implement your feature or fix following the guidelines above.

Commit your changes:

git commit -m "Add Rust language support"

Push to your fork:

git push origin feature/new-language-support

Create a pull request: Go to the Bufrnix repository on GitHub and create a pull request from your branch.
Address review feedback: Respond to any feedback from maintainers and update your pull request as needed.

Code Style and Guidelines

Follow the existing code style in the project.
Keep language modules modular and consistent with the existing ones.
Ensure all options have proper documentation.
Add appropriate error handling and validation.
Consider compatibility with existing tools like buf.build.

Testing

Before submitting a pull request, test your changes:

Test with an example project: Create or modify an example project that uses your changes.
Verify code generation: Ensure that the generated code compiles and works correctly.
Run existing tests: If there are existing automated tests, make sure they pass with your changes.

Documentation

Good documentation is crucial for the project:

Update the reference docs: Ensure that your feature is properly documented in the reference section.
Add example code: Provide example code that demonstrates how to use your feature.
Update the main README: If your change adds significant functionality, update the main README.md file.

Questions and Help

If you have questions or need help with your contribution:

Open an issue on GitHub
Reach out to the maintainers
Check the existing documentation and code for guidance

Thank you for contributing to Bufrnix! Your efforts help make Protocol Buffer development with Nix better for everyone.