Development Guidelines for Contributing to Easegress: A Complete Workflow Guide

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/<description>-<issue> or feat/<description>-<issue>.

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 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:

git clone https://github.com/<yourusername>/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/<short-description>-<issue-number>. For new features, use feat/<short-description>-<issue-number>. For example:

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 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:

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.

Testing Requirements

Every code change must include corresponding unit tests. Run the full test suite to verify your changes do not break existing functionality:

make test

For comprehensive validation, run the integration tests:

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:

• 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:

git checkout main
git pull --rebase upstream main
git checkout <your-branch>
git rebase main

After rebasing, force-push your branch to your fork:

git push -f origin <your-branch>

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/<desc>-<issue>.
• 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 <branch> && git rebase main. This maintains a linear commit history preferred by the maintainers. After rebasing, use git push -f origin <branch> to update your remote branch before opening the Pull Request.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}