From 7324e249ac665c83ba82fc39468e3a1e80e963f8 Mon Sep 17 00:00:00 2001 From: Kris Coleman Date: Mon, 10 Mar 2025 12:18:09 -0400 Subject: [PATCH] feat: add contributing guide and generator readme Added a new CONTRIBUTING.md file with detailed instructions on how to contribute new generators to the project. This includes steps from forking the repository, implementing the generator logic, writing tests, registering the generator in CLI, updating documentation, and creating a pull request. Also added a README.md in the internal/generators directory explaining how each generator works. It details about `language.go` and `language.tmpl` files that are essential parts of each generator along with an example workflow of how these components interact to generate code based on OpenFeature flag manifest. Signed-off-by: Kris Coleman --- CONTRIBUTING.md | 34 +++++++++++++++++++- internal/generators/README.md | 58 +++++++++++++++++++++++++++++++++++ 2 files changed, 91 insertions(+), 1 deletion(-) create mode 100644 internal/generators/README.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8b19c1c..586808e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,4 +1,36 @@ -TODO: Add contributing guidelines +## Contributing New Generators + +We welcome contributions for new generators to extend the functionality of the OpenFeature CLI. Below are the steps to contribute a new generator: + +1. **Fork the Repository**: Start by forking the repository to your GitHub account. + +2. **Clone the Repository**: Clone the forked repository to your local machine. + +3. **Create a New Branch**: Create a new branch for your generator. Use a descriptive name for the branch, such as `feature/add-new-generator`. + +4. **Add Your Generator**: Add your generator in the appropriate directory under `/internal/generate/generators/`. For example, if you are adding a generator for Python, you might create a new directory `/internal/generate/generators/python/` and add your files there. + +5. **Implement the Generator**: Implement the generator logic. Ensure that your generator follows the existing patterns and conventions used in the project. Refer to the existing generators like `/internal/generate/generators/golang` or `/internal/generate/generators/react` for examples. + +6. **Write Tests**: Write tests for your generator to ensure it works as expected. Add your tests in the appropriate test directory, such as `/internal/generate/generators/python/`. + +7. **Register the Generator**: After implementing your generator, you need to register it in the CLI under the `generate` command. Follow these steps to register your generator: + + - **Create a New Command Directory**: Create a new directory under `cmd/generate` with the name of your target language. For example, if you are adding a generator for Python, create a new directory `cmd/generate/python/`. + + - **Add Command File**: In the new directory, create a file named `python.go` (replace `python` with the name of your target language). This file will define the CLI command for your generator. + + - **Implement Command**: Implement the command logic in the `python.go` file. Refer to the existing commands like `cmd/generate/golang/golang.go` or `cmd/generate/react/react.go` for examples. + + - **Register Command**: Open the `cmd/generate/generate.go` file and register your new command as a subcommand. Add an import statement for your new command package and call `Root.AddCommand(python.Cmd)` (replace `python` with the name of your target language). + +8. **Update Documentation**: Update the documentation to include information about your new generator. This may include updating the README.md and any other relevant documentation files. + +9. **Commit and Push**: Commit your changes and push the new branch to your forked repository. + +10. **Create a Pull Request**: Create a pull request from your new branch to the main repository. Provide a clear and detailed description of your changes, including the purpose of the new generator and any relevant information. + +11. **Address Feedback**: Be responsive to feedback from the maintainers. Make any necessary changes and update your pull request as needed. ## Templates diff --git a/internal/generators/README.md b/internal/generators/README.md new file mode 100644 index 0000000..a349197 --- /dev/null +++ b/internal/generators/README.md @@ -0,0 +1,58 @@ +# Generators + +This directory contains the code generators for different programming languages. Each generator is responsible for generating code based on the OpenFeature flag manifest. + +## Structure + +Each generator should be placed in its own directory under `/internal/generators`. The directory should be named after the target language (e.g., `golang`, `react`). + +Each generator directory should contain the following files: + +- `language.go`: This file contains the implementation of the generator logic for the target language. Replace `language` with the name of the target language (e.g., `golang.go`, `react.go`). +- `language.tmpl`: This file contains the template used by the generator to produce the output code. Replace `language` with the name of the target language (e.g., `golang.tmpl`, `react.tmpl`). + +## How Generators Work + +Each generator consists of two main components: the `language.go` file and the `language.tmpl` file. The `language.go` file contains the logic for processing the feature flag manifest and generating the output code, while the `language.tmpl` file defines the template used to produce the final code. + +### `language.go` + +The `language.go` file is responsible for reading the feature flag manifest, processing the data, and applying it to the template defined in the `language.tmpl` file. This file typically includes functions for parsing the manifest, preparing the data for the template, and writing the generated code to the appropriate output files. + +### `language.tmpl` + +The `language.tmpl` file is a text template that defines the structure of the generated code. It uses the Go template syntax to insert data from the feature flag manifest into the appropriate places in the template. The `language.go` file processes this template and fills in the data to produce the final code. + +### Example Workflow + +1. The `language.go` file reads the feature flag manifest and parses the data. +2. The data is processed and prepared for the template. +3. The `language.go` file applies the data to the `language.tmpl` file using the Go template engine. +4. The generated code is written to the appropriate output files. + +By following this pattern, you can create generators for different programming languages that produce consistent and reliable code based on the feature flag manifest. + +## Example + +Here is an example structure for a Go generator: + +``` +/internal/generators/ + golang/ + golang.go + golang.tmpl +``` + +## Adding a New Generator + +To add a new generator, follow these steps: + +1. Create a new directory under `/internal/generators` with the name of the target language. +2. Add the `language.go` and `language.tmpl` files to the new directory. +3. Implement the generator logic in the `language.go` file. +4. Create the template in the `language.tmpl` file. +5. Ensure that your generator follows the existing patterns and conventions used in the project. +6. Write tests for your generator to ensure it works as expected. +7. Update the documentation to include information about your new generator. + +We appreciate your contributions and look forward to seeing your new generators! \ No newline at end of file