Contribution Guide

Strict

• Don't Push to main branch: Always avoid pushing directly to the main branch. Instead, create a new branch that contains your work and create a Pull Request (PR) for review. This helps to keep the main branch clean and stable.

• Atomic Pull Requests: PRs should be focused on a single, well-defined issue or feature. This makes reviewing easier and more manageable. Link your PR to the relevant GitHub issue (GitHub supports automatically closing issues when merging a PR by mentioning Fixes #<issue_number> in the PR description).

• Linear History: To maintain a clean history, use squash and merge or rebase and merge when merging a PR. This combines all commits from the branch into a single commit, making it easier to track changes in the history without a lot of noise or unnecessary intermediate commits.

• PR Reviews: Every PR should have at least one reviewer to ensure quality and consistency. Ideally, someone familiar with the codebase or the part you're modifying should review your work.

---

Less Strict

• Meaningful Branch Names: Use descriptive branch names to make it clear what the branch is for. A good naming convention could be fix/<description>, feat/<description>, or chore/<description>. This makes it easier for others to understand the context of your work at a glance.

• Delete Stale Branches: After a branch has been merged or is no longer needed, make sure to delete it. This helps keep the repository clean and prevents clutter. Stale branches can confuse others and create unnecessary noise in the branch list.

• Semantic Commit Messages: Follow a consistent format for commit messages to improve clarity. A common convention is to use prefixes like feat:, fix:, docs:, refactor: etc. For example:

  • feat: add user authentication
  • fix: correct typo in README
  • refactor: improve performance of search function

  This helps to quickly understand the nature of each change and supports tools that generate changelogs automatically.

• Descriptive Issues: Use the issue templates shared in the repository to ensure uniformity and enforce the following properties of a well-defined issue:

  • Includes a deadline and an estimate of the effort required, i.e., the time needed to complete the task.
  • Has a well-defined description that focuses on a single task. Broad ideas and problems should be discussed on the discussion page.
  • Provides reproduction steps if the issue is a bug report.
  • Defines clear acceptance criteria; the issue should only be closed when all criteria are met.
  • Is assigned, even if you will be the one working on it. Avoid assigning multiple people, as that indicates the issue may be too broad.
  • Is tagged with appropriate labels, such as pri: and effort:.

---

Good to Have

• Descriptive PR Titles and Descriptions: Having a well-written PR title and description helps others quickly understand the purpose of your changes. Use the PR description to explain why you made these changes and provide any context that might be useful to the reviewer.