Skip to main content

Contributing

Extending the Project​

New service​

  1. Implement the service logic in the backend (server/).
  2. Update the service list in the API and documentation.

New action or reaction​

  1. Add the action/reaction logic to the relevant service in the backend.
  2. Update the API documentation and about.json response.

New client feature​

  1. Implement the feature in the web (web/) or mobile (mobile/) client.
  2. Ensure it communicates with the backend via REST API.

Development Workflow​

Purpose​

In order to maintain a clean and reliable production branch, all changes to main must be properly staged, reviewed and tested.

This section defines how branches, commits and pull requests (PRs) must be handled.

Branching Strategy​

  • main: Production branch. Updated weekly with the latest stable version of the apps.
  • dev: Integration branch. All features and fixes must be merged here before going to main.
  • Feature/Bugfix branches: Branches off dev for new work. Use clear names, e.g., add login-ui, fix payment-crash.
  • Hotfix branches: Only for urgent fixes that must go directly to main. Must follow the hotfix procedure below.

Commits norm​

Every commits must follow these rules:

  1. With one or two gitmoji, the 2nd specifying an action on the first one.
  2. A short description of the change starting by an action verb at the imperative tense, try to stay under 80 characters.
  3. Optional, if you want to provide more informations in your commit, do it in the commit's message description.
Simple example
📝 Update the contributing guidelines to add the commit norm.
Multiple gitmojis + description
📝🏗️ Setup production ready documentation architecture.

With 3 folders: getting started, guides & API references.

Pull Request​

targeting main

dev is the only source branch allowed for PRs targeting main

PR Title & Description​

  • Use a descriptive title explaining the change.
  • Include a short summary, Jira stories or tasks, List of changes/features/fixes and how you tested the feature in the description.
pull request template

Use the pull request template when creating a new one, it will set the skeleton for the description + tasks you have to do.

Review Requirements​

At least 2 reviewers must be selected, 4 if the base branch is main:

  • The person in charge of this part of the project.
  • The Scrum Master which will check for potentially required continuous integration updates & tests to add/edit.

If new commits are pushed, all reviews will be stalled thus requiring all reviewers to do it again.

Refer to the team section to know who is in charge of which part in the project.

Check Tests​

  • All status checks (CI, linters, unit tests, etc) must pass before being able to merge.
  • If new commits are pushed, all status checks will be relaunched.

Merging commits messages​

The only method authorized is Squash & Merge.

The commit message must start with an appropriated gitmoji and resume the pull request content (you can use the title).

Changing PR Base Branch​

Avoid changing the base branch off a PR after creation.

If a PR was mistakenly created targeting main from another branch than dev, create an empty commit so the blocking CI job is retriggered and cleared.

GitHub actually has a way to rerun workflows on PR base change but it does not dismiss old failed workflow runs.

Hotfix Procedure​

warning

Hotfixes must be used only in case of an emergency production issue.

Because hotfixes bypass some verification, they may require rollback or temporary disabling of affected functionality.

Branch off main as hotfix/description.

After merging back into main, immediately merge the hotfix into dev to keep branches in sync. You must request at least 2 other people's reviews in order to merge it, ideally the same persons as in the standard procedure. If these persons are not able to do it, you might request reviews from any two other members of the team.

Monitoring & Compliance​

  • Review open PRs where you are required as reviewer regularly.

  • Remember that every new commits on a PR automatically re-request a review from all reviewers.

If you find a violation of any of the rules above, mark your review as Request Change with the broken rule in the description. This will block the PR from being merged, remember to check back more often in order to make your review again once it is fixed.

Branch Protection Rules​

main branch (production)​

  • Require pull requests before merging.
  • Source of the PR must be dev.
  • Require all status checks to pass.
  • Require approval from at least 4 core team members.

dev branch​

  • Require pull requests before merging.
  • Require all status checks to pass.
  • Require at least two approval from team members, see how to choose who.

The team​

The core team of the AREA project is actually composed of 5 peoples:

  • Arthuryan Loheac: Project director & web frontend dev.
  • Jean Bizeul: SCRUM master & DevOps.
  • Nathan Bezard: Mobile dev.
  • Mathys Fillon: Backend dev.
  • Léopold Pintard: Backend dev.

Questions?​

Open an issue on the GitHub project page or contact the maintainers via contact@area.azerty.