|
| 1 | +# Contributing Guidelines |
| 2 | + |
| 3 | +We appreciate your interest in contributing to this project! This document establishes the mandatory standards that ensure high-quality contributions and efficient collaboration. |
| 4 | +By following these guidelines, you help us maintain code quality and project consistency. |
| 5 | + |
| 6 | +## Code of Conduct |
| 7 | + |
| 8 | +All contributors must adhere to our project's code of conduct. We expect professional communication, respectful collaboration, and constructive feedback in all interactions. |
| 9 | + |
| 10 | +## Before You Start |
| 11 | + |
| 12 | +### Development Environment Setup |
| 13 | + |
| 14 | +**Required dependencies:** |
| 15 | +- Go version must be equal to the one in `go.mod` or higher; |
| 16 | +- Git for version control; |
| 17 | +- Make for build automation. |
| 18 | + |
| 19 | +### Pre-Implementation Discussion |
| 20 | + |
| 21 | +**All non-trivial changes must be discussed in an issue before implementation.** This prevents duplicate work and ensures alignment with project goals. |
| 22 | + |
| 23 | +**Required steps:** |
| 24 | +1. **Search existing issues** to avoid duplicates; |
| 25 | +2. **Create a detailed issue** describing your proposed changes; |
| 26 | +3. **Wait for maintainer approval** before beginning implementation; |
| 27 | +4. **Reference the issue number** in your pull request. |
| 28 | + |
| 29 | +**Exception:** Minor fixes (typos, documentation corrections) may skip this requirement. |
| 30 | + |
| 31 | +## Mandatory Commit Message Convention |
| 32 | + |
| 33 | +All commits merged into the main branch **must** strictly follow [Conventional Commits v1.0.0](https://www.conventionalcommits.org/en/v1.0.0/). |
| 34 | +While temporary commits may use alternative formats, conventional commits are strongly recommended throughout development. |
| 35 | + |
| 36 | +Commit scope is optional but encouraged for clarity. |
| 37 | + |
| 38 | +Definition of scope: |
| 39 | +- the LCA (Lowest Common Ancestor) of the directories modified in the PR; |
| 40 | +- the name of the feature implemented/improved in the PR. |
| 41 | + |
| 42 | +### Required Commit Types |
| 43 | + |
| 44 | +**You must** use one of the following commit types: |
| 45 | + |
| 46 | +- **`build`** - Changes related to build system (Dockerfile, build scripts, etc.); |
| 47 | +- **`chore`** - Repository maintenance tasks (Makefile changes, code comments, bump of dependencies etc.); |
| 48 | +- **`ci`** - CI/CD pipeline modifications; |
| 49 | +- **`docs`** - Documentation updates (excluding code comments); |
| 50 | +- **`feat`** - New user-facing functionality implementation; |
| 51 | +- **`fix`** - Bug resolution (e.g., fixing race conditions in single-node version due to buffer reuse); |
| 52 | +- **`perf`** - Performance optimizations (e.g., adding ASCII ToLower array and using it as hot-path); |
| 53 | +- **`refactor`** - Code restructuring for improved readability without functionality changes (e.g., refactoring sealing logic); |
| 54 | +- **`revert`** - Reverting previous commits (e.g., fixing broken MergeQPRs from previous commit); |
| 55 | +- **`style`** - Code style corrections (linter compliance); |
| 56 | +- **`test`** - Test additions or modifications. |
| 57 | + |
| 58 | +### Commit Message Examples |
| 59 | + |
| 60 | +**Good examples:** |
| 61 | +```text |
| 62 | +feat: add `ip_range` function |
| 63 | +fix: resolve buffer reuse race condition in single-node mode |
| 64 | +docs: update benchmarks results in the documentation |
| 65 | +perf(query): optimize ASCII character processing |
| 66 | +refactor: improve sealing logic readability |
| 67 | +``` |
| 68 | + |
| 69 | +**Bad examples:** |
| 70 | +```text |
| 71 | +updated stuff |
| 72 | +fix bug |
| 73 | +changes |
| 74 | +WIP |
| 75 | +``` |
| 76 | + |
| 77 | +## Mandatory Go Style Compliance |
| 78 | + |
| 79 | +**All Go code must comply** with the following style guides in this exact order of priority: |
| 80 | + |
| 81 | +1. [Google Go Style Guide](https://google.github.io/styleguide/go/guide); |
| 82 | +2. [Google Go Style Decisions](https://google.github.io/styleguide/go/decisions); |
| 83 | +3. [Google Go Best Practices](https://google.github.io/styleguide/go/best-practices); |
| 84 | +4. [Uber Go Style Guide](https://github.com/uber-go/guide/blob/master/style.md); |
| 85 | +5. [Effective Go](https://go.dev/doc/effective_go). |
| 86 | + |
| 87 | +**Code that does not comply with these standards will require revision before acceptance.** |
| 88 | + |
| 89 | +## Mandatory Branch Naming Convention |
| 90 | + |
| 91 | +Branch names must use `kebab-case` and strictly follow this format: |
| 92 | + |
| 93 | +```text |
| 94 | +{issue-number}-{branch-name} |
| 95 | +``` |
| 96 | + |
| 97 | +For branches not associated with any issue, **you must** use: |
| 98 | + |
| 99 | +```text |
| 100 | +0-{branch-name} |
| 101 | +``` |
| 102 | + |
| 103 | +### Branch Naming Examples |
| 104 | + |
| 105 | +**Good examples:** |
| 106 | +```text |
| 107 | +123-fix-datarace-in-single-mode |
| 108 | +789-update-dependencies |
| 109 | +0-fix-typo-in-readme |
| 110 | +``` |
| 111 | + |
| 112 | +**Bad examples:** |
| 113 | +```text |
| 114 | +feature-branch |
| 115 | +my-changes |
| 116 | +fix |
| 117 | +update |
| 118 | +``` |
| 119 | + |
| 120 | +**Non-compliant branch names will require revision.** |
| 121 | + |
| 122 | +## Required Issue Classification and Labeling |
| 123 | + |
| 124 | +### Mandatory Issue Types |
| 125 | + |
| 126 | +**You must** classify all issues using one of these types: |
| 127 | + |
| 128 | +- **Bug** - All bug reports and defects; |
| 129 | +- **Feature** - New feature requests and enhancements; |
| 130 | +- **Security** - Security-related vulnerabilities and concerns; |
| 131 | +- **Question** - General inquiries (will be redirected to GitHub Discussions); |
| 132 | +- **Blank** - All other issue types. |
| 133 | + |
| 134 | +### Required Labeling Strategy |
| 135 | + |
| 136 | +**Apply appropriate labels** in combination with issue types, for example: |
| 137 | + |
| 138 | +- Code optimization issues: **Must** use **Blank** type with `performance` label; |
| 139 | +- Documentation fixes: **Must** use **Blank** type with `documentation` label; |
| 140 | +- **Apply additional relevant labels** as required for proper categorization. |
| 141 | + |
| 142 | +### Issue Examples |
| 143 | + |
| 144 | +**Good issue descriptions:** |
| 145 | +- Bug reports: **Bug** type + `bug` label + detailed reproduction steps; |
| 146 | +- Performance optimization: **Blank** type + `performance` label + benchmarks; |
| 147 | +- Documentation updates: **Blank** type + `documentation` label + specific section reference. |
| 148 | + |
| 149 | +## Mandatory Pull Request Requirements |
| 150 | + |
| 151 | +### Pull Request Standards |
| 152 | + |
| 153 | +**Every pull request must include:** |
| 154 | +- **Appropriate labels** corresponding to the type of changes (to group several PRs one can use additional labels e.g. `epic-offloading`); |
| 155 | +- **Reference to related issue** (e.g., "Closes #123", "Fixes #123"); |
| 156 | +- **Clear description** of changes made; |
| 157 | +- **Test coverage** for new functionality (generated automatically); |
| 158 | +- **Updated documentation** when applicable. |
| 159 | + |
| 160 | +### Code Review Process |
| 161 | + |
| 162 | +**Pull request review requirements:** |
| 163 | +- **All automated checks** must pass (CI, linting, tests); |
| 164 | +- **At least two maintainer approvals** are required; |
| 165 | +- **Address all review feedback** before merge; |
| 166 | +- **Squash commits** during merge to maintain clean history. |
| 167 | + |
| 168 | +**Pull requests that do not meet these standards will require revision.** |
| 169 | + |
| 170 | +## Getting Started for New Contributors |
| 171 | + |
| 172 | +### Finding Good First Issues |
| 173 | + |
| 174 | +Look for issues labeled with: |
| 175 | +- `good-first-issue` - Beginner-friendly tasks; |
| 176 | +- `help-wanted` - Community contributions welcome; |
| 177 | +- `documentation` - Non-code contributions. |
| 178 | + |
| 179 | +### Contribution Process |
| 180 | + |
| 181 | +**Follow these mandatory steps:** |
| 182 | + |
| 183 | +1. **Fork the repository** and clone your fork locally; |
| 184 | +2. **Create a new branch** following the mandatory naming convention; |
| 185 | +3. **Set up your development environment** using the instructions above; |
| 186 | +4. **Implement your changes** in strict compliance with the Go style guides; |
| 187 | +5. **Write or update tests** as required for your changes; |
| 188 | +6. **Ensure all commits** follow the conventional commit format; |
| 189 | +7. **Run all tests locally** to verify your changes; |
| 190 | +8. **Submit a pull request** with appropriate labels and complete description. |
| 191 | + |
| 192 | +**Contributions that do not follow these steps will require revision.** |
| 193 | + |
| 194 | +## AI Assistance Notice |
| 195 | + |
| 196 | +> [!IMPORTANT] |
| 197 | +> |
| 198 | +> If you are using **any kind of AI assistance** to contribute to `seq-db`, |
| 199 | +> it must be disclosed in the pull request. |
| 200 | +
|
| 201 | +If you are using any kind of AI assistance while contributing to `seq-db`, |
| 202 | +**this must be disclosed in the pull request**, along with the extent to |
| 203 | +which AI assistance was used (e.g. docs only vs. code generation). |
| 204 | +If PR responses are being generated by an AI, disclose that as well. |
| 205 | +As a small exception, trivial tab-completion doesn't need to be disclosed, |
| 206 | +so long as it is limited to single keywords or short phrases. |
| 207 | + |
| 208 | +An example disclosure: |
| 209 | + |
| 210 | +> This PR was written primarily by Claude Code. |
| 211 | +
|
| 212 | +Or a more detailed disclosure: |
| 213 | + |
| 214 | +> I consulted ChatGPT to understand the codebase but the solution |
| 215 | +> was fully authored manually by myself. |
| 216 | +
|
| 217 | +Failure to disclose this is first and foremost rude to the human operators |
| 218 | +on the other end of the pull request, but it also makes it difficult to |
| 219 | +determine how much scrutiny to apply to the contribution. |
| 220 | + |
| 221 | +Please be respectful to maintainers and disclose AI assistance. |
| 222 | + |
| 223 | +> This section is adapted from [ghostty](https://github.com/ghostty-org/ghostty/blob/main/CONTRIBUTING.md). |
| 224 | +> Credit goes to the original authors! |
| 225 | +
|
| 226 | +## Recognition and Community |
| 227 | + |
| 228 | +### Contributor Recognition |
| 229 | + |
| 230 | +**We value all contributions** and recognize contributors through: |
| 231 | +- Acknowledgment in release notes; |
| 232 | +- Listing in project credits and README for significant contributions; |
| 233 | + |
| 234 | +### Communication Channels |
| 235 | + |
| 236 | +**Get help and stay connected:** |
| 237 | +- **GitHub Issues** - Bug reports and feature requests; |
| 238 | +- **GitHub Discussions** - General questions and community discussions; |
| 239 | +- **Code Reviews** - Technical discussions on pull requests. |
| 240 | + |
| 241 | +## Support and Questions |
| 242 | + |
| 243 | +For questions regarding contribution requirements: |
| 244 | + |
| 245 | +- **Review existing issues and discussions** before creating new ones; |
| 246 | +- **Create a Question-type issue** (will be redirected to GitHub Discussions); |
| 247 | +- **Thoroughly review** this contributing guide and all referenced style guides; |
| 248 | +- **Check the project README** for additional context and setup information. |
| 249 | + |
| 250 | +**All contributions must meet these standards. Non-compliant submissions will require revision before acceptance.** |
| 251 | + |
| 252 | +## Resources |
| 253 | + |
| 254 | +**Helpful links:** |
| 255 | +- [Conventional Commits Specification](https://www.conventionalcommits.org/en/v1.0.0/); |
| 256 | +- [Go Style Guides](https://google.github.io/styleguide/go/guide); |
| 257 | +- [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/); |
| 258 | +- [GitHub Flow Guide](https://guides.github.com/introduction/flow/). |
| 259 | + |
| 260 | +Thank you for contributing to our project! |
0 commit comments