17. Contributing to Goe 🤝
We welcome contributions to the Goe framework! Whether you're fixing a bug, improving documentation, or proposing a new feature, your help is appreciated. This guide outlines how to contribute effectively.
Code of Conduct
Before contributing, please read our Code of Conduct. We expect all contributors to adhere to it to ensure a welcoming and inclusive environment for everyone.
Ways to Contribute
- Reporting Bugs: If you find a bug, please open an issue on the GitHub repository. Include:
- A clear and descriptive title.
- Steps to reproduce the bug.
- What you expected to happen.
- What actually happened.
- Your Goe version, Go version, and OS.
- Any relevant code snippets or logs.
- Suggesting Enhancements or New Features: Open an issue to discuss your ideas. Provide:
- A clear description of the proposed enhancement or feature.
- The problem it solves or the value it adds.
- Potential implementation ideas (if any).
- Improving Documentation: If you find errors, omissions, or areas that could be clearer in the documentation, please open an issue or submit a pull request with your improvements. This documentation itself is a great place to contribute!
- Writing Code: Submit pull requests for bug fixes or new features.
- Reviewing Pull Requests: Help review PRs submitted by others.
Setting Up Your Development Environment
Prerequisites:
- Go 1.24 or newer.
- Git.
- A GitHub account.
Fork the Repository:
- Go to the Goe GitHub repository (let's assume
github.com/oease/goe
for this example). - Click the "Fork" button to create your own copy of the repository.
- Go to the Goe GitHub repository (let's assume
Clone Your Fork:
bashgit clone https://github.com/YOUR_USERNAME/goe.git cd goe
Add Upstream Remote: This allows you to keep your fork in sync with the main repository.
bashgit remote add upstream https://github.com/oease/goe.git
Install Dependencies: Goe uses Go modules. Dependencies should be automatically managed.
bashgo mod tidy
Making Changes
Keep Your Fork Updated: Before starting work on a new contribution, ensure your
main
(ormaster
) branch is up-to-date with the upstream repository:bashgit checkout main git pull upstream main git push origin main # Update your fork's main branch
Create a New Branch: Create a descriptive branch for your changes:
bashgit checkout -b feature/my-new-feature # For new features # or git checkout -b fix/bug-description # For bug fixes # or git checkout -b docs/improve-config-guide # For documentation
Write Your Code/Documentation:
- Make your changes.
- Follow existing code style and conventions (see below).
- Ensure your code is well-commented, especially for public APIs.
- If adding new features or fixing bugs, write or update relevant tests.
Code Style and Conventions:
- Go Standard Formatting: Run
gofmt
orgoimports
on your code before committing. Many IDEs do this automatically.bashgofmt -w . # or goimports -w .
- Linting: While not strictly enforced by a specific linter in this guide, consider using a linter like golangci-lint to catch common issues. If the project adopts one, its configuration will be in the repository.
- Comments: Write clear and concise comments. Exported functions, types, and constants should generally have godoc comments.
- Error Handling: Follow Go's idiomatic error handling. Wrap errors for context.
- Testing: Strive for good test coverage.
- Go Standard Formatting: Run
Run Tests: Before submitting your contribution, ensure all tests pass:
bashgo test ./...
If the project has a
Makefile
with a test target, use that (e.g.,make test
).Commit Your Changes:
- Use clear and descriptive commit messages. A good format is:Or for smaller changes:
feat: Add support for new cache driver X This commit introduces a new cache driver X, providing... Fixes #123 (if applicable)
fix: Correct typo in configuration documentation
- Prefixes like
feat:
,fix:
,docs:
,test:
,chore:
,refactor:
are common (Conventional Commits). - Commit frequently with logical units of work.
- Use clear and descriptive commit messages. A good format is:
Push to Your Fork:
bashgit push origin feature/my-new-feature
Submitting a Pull Request (PR)
Open a Pull Request:
- Go to your fork on GitHub (
https://github.com/YOUR_USERNAME/goe
). - You should see a button to "Compare & pull request" for your recently pushed branch. Click it.
- If not, go to the "Pull requests" tab and click "New pull request". Select your fork and branch to compare against the main repository's
main
(ormaster
) branch.
- Go to your fork on GitHub (
Describe Your PR:
- Provide a clear title for your PR.
- In the description, explain the changes you've made and why.
- If your PR addresses an existing issue, link to it (e.g., "Closes #456", "Fixes #789").
- Include any relevant information for the reviewers.
Code Review:
- Project maintainers and other contributors will review your PR.
- Be prepared to discuss your changes and make adjustments based on feedback.
- Respond to comments professionally and constructively.
CI Checks: The Goe project likely has Continuous Integration (CI) checks (e.g., GitHub Actions) that automatically build your code, run tests, and perform other checks. Ensure these pass.
Merging: Once your PR is approved and all checks pass, a maintainer will merge it into the main repository. 🎉
Licensing
By contributing to Goe, you agree that your contributions will be licensed under its MIT License.
Thank you for considering contributing to the Goe framework! Your efforts help make it better for everyone.
Please refer to the documentation for comprehensive guides on using the framework.