# Development Guidelines for Contributing to Easegress: A Complete Workflow Guide > Follow Easegress development guidelines for contributing to easegress-io/easegress. Learn the workflow, style guide, and testing requirements to submit your code effectively. - Repository: [easegress-io/easegress](https://github.com/easegress-io/easegress) - Tags: getting-started - Published: 2026-03-01 --- **Contributors to the easegress-io/easegress repository must adhere to the Uber Go Style Guide, run `make fmt` and `make test` before submitting, and use descriptive branch names like `fix/-` or `feat/-`.** The Easegress open-source project welcomes contributions ranging from new request filters and core objects to documentation improvements and performance optimizations. Whether you are implementing a custom processor in the `filter/` directory or extending pipeline logic in `object/`, following the established development guidelines ensures your code maintains consistency with the existing architecture. This guide distills the essential workflow, coding standards, and submission requirements defined in [`CONTRIBUTING.md`](https://github.com/easegress-io/easegress/blob/main/CONTRIBUTING.md) and the official Developer Guide. ## Getting Started with the Easegress Contribution Workflow Before writing code, configure your local environment to track the upstream repository and follow the branching conventions used by the maintainers. ### Repository Setup and Branch Naming Fork the repository on GitHub, then clone your fork and add the official repository as the `upstream` remote to keep your local `main` branch synchronized: ```bash git clone https://github.com//easegress.git cd easegress git remote add upstream https://github.com/megaease/easegress.git ``` Create a feature or fix branch using the project naming conventions. For bug fixes, use `fix/-`. For new features, use `feat/-`. For example: ```bash git checkout -b fix/timeout-bug-123 # or git checkout -b feat/add-custom-filter-456 ``` ### Pre-Development Reading Review the architectural overview in [`docs/06.Development-for-Easegress/6.1.Developer-Guide.md`](https://github.com/easegress-io/easegress/blob/main/docs/06.Development-for-Easegress/6.1.Developer-Guide.md) to understand extension points for **filters** (request/response processors) and **objects** (core controllers). Check existing issues or open a new one using the appropriate GitHub template before starting significant work. ## Coding Standards and Static Analysis Easegress enforces strict code quality through automated tooling and style guidelines. ### Style Guide and Formatting All Go code must comply with the **Uber Go Style Guide**. Before committing any changes, run the formatter to ensure consistency: ```bash make fmt ``` The repository uses **Revive** for static analysis. While the CI pipeline runs these checks automatically, you can install Revive locally to catch issues early as described in [`CONTRIBUTING.md`](https://github.com/easegress-io/easegress/blob/main/CONTRIBUTING.md). ### Testing Requirements Every code change must include corresponding unit tests. Run the full test suite to verify your changes do not break existing functionality: ```bash make test ``` For comprehensive validation, run the integration tests: ```bash make integration_test ``` ## Contribution Types and Extension Points The project structure supports several categories of contributions, each targeting specific directories. ### Implementing New Filters **Filters** are request/response processing components located in the `filter/` directory. When adding a new filter, implement the required interfaces and place your source files alongside existing filters. Include comprehensive unit tests in `*_test.go` files within the same package. ### Adding New Objects **Objects** represent core controllers and pipeline definitions, located in the `object/` directory. Extend this directory when adding custom controllers or new configuration objects that integrate with Easegress's internal API. ### Other Contribution Categories - **Bug Fixes**: Modify any source file to correct logic errors or crashes, ensuring tests cover the regression. - **Performance Improvements**: Add benchmarks under `bench/` and optimize CPU/memory usage in hot paths. - **Documentation**: Update markdown files in `docs/` to reflect API changes or new architectural patterns. ## Submitting Your Changes: The PR Checklist Before opening a Pull Request, verify the following items from the submission checklist in [`CONTRIBUTING.md`](https://github.com/easegress-io/easegress/blob/main/CONTRIBUTING.md): - **Issue Reference**: Create or reference a GitHub issue describing the problem or feature. - **Branch Naming**: Ensure your branch follows the `fix/` or `feat/` convention. - **Code Quality**: Confirm `make fmt` produces no changes and your code adheres to the Uber Go Style Guide. - **Test Coverage**: Verify `make test` passes completely and new functionality has unit tests. - **CI Compliance**: Ensure the Revive linter and all GitHub Actions workflows pass. - **PR Description**: Explain *what* changed and *why* the change is necessary, linking to the relevant issue. ### Rebase Strategy Keep your branch up-to-date with `main` using rebase rather than merge commits to maintain a clean history: ```bash git checkout main git pull --rebase upstream main git checkout git rebase main ``` After rebasing, force-push your branch to your fork: ```bash git push -f origin ``` Then use the GitHub UI to open a Pull Request against the `main` branch of `easegress-io/easegress`. ## Development Environment Commands The `Makefile` at the repository root provides standard commands for building, testing, and formatting. Key targets include: - `make fmt`: Formats all Go source files using the project standard. - `make test`: Executes the unit test suite. - `make integration_test`: Runs integration tests against a live environment. - `make build`: Compiles the Easegress binary. ## Summary - **Clone and configure**: Fork the repository, add `upstream` remote pointing to `megaease/easegress`, and use descriptive branch names like `fix/-`. - **Follow standards**: Write Go code conforming to the **Uber Go Style Guide** and run `make fmt` before committing. - **Test thoroughly**: Include unit tests for all changes and ensure `make test` passes before submitting. - **Target correct directories**: Place new filters in `filter/`, new objects in `object/`, and documentation in `docs/`. - **Submit properly**: Rebase onto `main`, force-push to your fork, and open a PR with a clear description referencing the related issue. ## Frequently Asked Questions ### What coding standards does Easegress require? Easegress follows the **Uber Go Style Guide** for all Go source code. The project enforces these standards using **Revive** for static analysis and requires contributors to run `make fmt` before submitting changes to ensure consistent formatting across the codebase. ### Where should I implement a new filter or object? Implement new **filters** (request/response processors) in the `filter/` directory, following existing interface implementations in that folder. Add new **objects** (controllers or pipeline components) to the `object/` directory. Both locations require corresponding `*_test.go` files containing unit tests for your new code. ### How do I ensure my code passes the required checks? Run `make fmt` to automatically format your code according to project standards. Then execute `make test` to run the unit test suite and verify no regressions exist. For comprehensive validation, run `make integration_test`. The CI pipeline will also run **Revive** linting; ensure this passes by following the Uber Go Style Guide strictly. ### What is the correct workflow for updating my branch before submitting a PR? Rebase your feature branch onto the latest `main` from upstream rather than merging. Use the sequence: `git checkout main && git pull --rebase upstream main && git checkout && git rebase main`. This maintains a linear commit history preferred by the maintainers. After rebasing, use `git push -f origin ` to update your remote branch before opening the Pull Request.