Skip to content

Coding Together

Jump to bottom
Maël Imhof edited this page Dec 19, 2024 · 3 revisions

Coding is fun. But as Sartre once said

Hell is other people.

Sources tell he said this after a colleague of his pushed terrible commits to the main branch without doing a PR first.

The goal of this wiki page is to have all team members of the same page when it comes to how things should be named or done.

  1. General development workflow
  2. Branch naming convention
  3. How to write a PR
  4. Conflicts resolution

General development workflow

When working on Hike Mate, no code is to be directly pushed to the main branch. The main branch is the last stable version of the code, where everything needs to be merged eventually.

The general workflow of creating a feature/fix for Hike Mate is

  1. Create a new branch (see naming convention)
  2. Work on that particular feature or fix on the branch. Only changes relative to that feature should exist on the branch. To add changes related to another fix or feature, create yet another branch.
  3. Write tests. Note that CI checks will not pass under 80% code coverage. For bug fixes, write regression tests.
  4. Once ready, push a first version of the feature/fix to GitHub
  5. Open a Pull Request (PR) from the created branch to main
  6. Ask someone to review the PR, depending on who is available and who still needs a PR for this week as per the milestones criteria.
  7. Answer the reviewer's comments and perform appropriate changes until the PR is approved
  8. Once the PR is approved, the person who created it can merge it. Do not simply merge, use squash and merge so that a single commit is added to main.

Branch naming convention

Our convention for branch naming is similar to how conventional Git commit messages are written.

  • Prefix the branch name with a type of change (fix, feat, test, chore, docs) followed by a / character

  • Continue with a descriptive name of what the branch is about

  • Ensure the branch name is not too long (should be 50 characters maximum)

  • The descriptive name is only lowercase (no uppercase letters in the branch name)

  • The only allowed separator in the descriptive name is - (no spaces, no underscores, ...)

For example, if someone wants to work on a sign-in screen, they might create a branch named feat/sign-in-screen.

How to write a PR

Opening a PR with a quick title and no message shall not be accepted, except for very simple PRs where what was done and how it was done is obvious to anyone reading the changes.

Most of the time, the changes are not obvious, hence, the person that creates the PR shall provide:

  • A descriptive title
  • A summary of what the end goal was (for example: Adds a sign-in screen and redirects to the overview screen once the user is logged-in)
  • A summary of how the end goal was achieved (conceptually). The objective of this section should be to ease the review process. The reviewer should have a high-level idea of what sections were changed and what each section is meant to do.
  • Details about the how if relevant.

Conflicts resolution

Because the software is getting more and more complex as the time passes, PR might get harder to merge when several people are working in the same area.

When very complex Git conflict occurs and the person working on the PR needs help, the conflicts shall be resolved together by:

  • The person who wrote the PR
  • The person who wrote the code that conflicts with the PR. In case of several conflicts, several people might need to review the resolution, each reviewing the part they wrote that conflicts with the PR.
  • The person that is assigned to review the PR.
Clone this wiki locally