Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
149 lines (108 loc) · 4.07 KB

CONTRIBUTING.md

File metadata and controls

149 lines (108 loc) · 4.07 KB

CONTRIBUTING GUIDE

1. Welcome!

Thank you for considering contributing to this open source project! We welcome contributions of all kinds: code, documentation, ideas, and more.

Here are the simple yet important guidelines for this project :

  • respect the Code of conduct
  • use github tag to mention people and not their private names
  • do not mention secrets, passwords, private urls, sensitive tokens anywhere
  • use English as default language everywhere

And that's pretty much it ! You are now ready to get started.

2. Getting Started

2.1. For external contributors

We use the Forking Workflow, used in many open source projects. So to start contributing, please:

  • Fork the repository
  • Create a branch using the naming convention described below
  • Make your changes
  • Open a Pull Request (PR) referencing the related issue
  • Ensure your changes pass all tests and checks

2.2. For Ippon

We use the Feature Branch Workflow according to the size of our team. Each modification will be done on a new branch created from main.

gitGraph
	commit id: "C1"
	commit id: "C2"
	branch "feature/123-displays-results"
	commit id: "C3"
	checkout main
	commit id: "C4"
	branch "feature/456-saves-archi"
	commit id: "C5"
	checkout "feature/123-displays-results"
	commit id: "C6"
Loading

3. Commit Messages

We use Conventional Commits for commit messages, with the id of the corresponding ticket.

Example:

feat(auth): #789 implements login with email and password

It is checked in our Continous Integration. To avoid surprised rejects, you can install pre-commit on your personal environment of development.

4. Branch Naming Convention

We follow the Conventional Branches naming convention to ensure clarity, traceability, and automation.

Branch name format:

<type>/<issue-number>-<short-description>

Examples:

feature/42-add-authentication
bugfix/108-fix-mobile-layout
docs/77-update-readme-instructions

Rules:

  • Use a predefined type (see below)
  • Always include the related issue number
  • Use kebab-case for short, meaningful description

Allowed types:

  • feature: For new features (e.g., feature/add-login-page)
  • bugfix: For bug fixes (e.g., bugfix/fix-header-bug)
  • hotfix: For urgent fixes (e.g., hotfix/security-patch)
  • release: For branches preparing a release (e.g., release/v1.2.0)
  • chore: Maintenance tasks

4.1. Why This Convention Matters

  • 🔍 Clarity: It’s easy to understand the purpose of a branch.
  • 🔗 Traceability: The issue number links code to its discussion and context.
  • ⚙️ Automation: Tools like commit-check and commit-check-action can verify branch names and enforce consistency.

5. Merge convention

In the project, the pull request will be rebased and merge fast-forward.

gitGraph
	commit id: "C1"
	commit id: "C2"
	branch "feature/123-displays-results"
	commit id: "C3"
	checkout main
	commit id: "C4"
	checkout "feature/123-displays-results"
	commit id: "C5"
Loading

will be merged in:

gitGraph
	commit id: "C1"
	commit id: "C2"
	commit id: "C4"
	commit id: "C3'"
	commit id: "C5'"
Loading

or if squash is activated:

gitGraph
	commit id: "C1"
	commit id: "C2"
	commit id: "C4"
	commit id: "C3+C5"
Loading

6. Tools & Checks

To help enforce the rules, we use:

These tools will validate branch names and commit messages during pull requests.

7. Need Help?

If you have any questions or need assistance, feel free to open an issue or join the project discussion board. We’re happy to help!