Skip to content

Latest commit

 

History

History
135 lines (89 loc) · 6.21 KB

git-guidelines.md

File metadata and controls

135 lines (89 loc) · 6.21 KB
Raw

Git & Commit Guidelines

This is a guide covering how we expect to work with Git at MarsBased. Most of this guide is GitHub oriented but might be adapted to other Git tools like Gitlab or Bitbucket.

Please, notice that at MarsBased we work with a large variety of clients. There could be clients that follow their own guidelines. You can always suggest improvements over their guidelines but there will be cases where it won't be possible to use ours.

Commit Message Guidelines

We have very precise rules over how our git commit messages can be formatted. This leads to more readable messages that are easy to follow when looking through the project history.

Commit Message Format

Each commit message consists of a header, a body and a footer. The header has a special format that includes a type, a scope and a subject:

<type>(<scope>): <subject>
-BLANK LINE-
<description>
-BLANK LINE-
<footer>

The header is mandatory but the scope of the header is optional.

The maximum length of the header must be 72 characters and any other line of the commit message cannot be longer than 100 characters. This allows the message to be easier to read on GitHub as well as in various git tools. The language used in the commit messages is English. If the client wants to have access to the commit history for documentation purposes and they don't understand English, other languages can be used instead.

The <footer> should contain a closing reference to a github issue, a Trello card link, a JIRA issue ID or link. If there is no GitHub issue or project management tool reference for this specific commit just leave it blank.

Type

Choose the one that best fits the task:

  • fix: Represents a bug fix for your application.
  • feature / feat: Adds a new feature to your application or library.
  • refactor: A code change that neither fixes a bug nor adds a feature.
  • deploy: Changes to modify or related to the deployment process.
  • chore: Upgrades libraries and/or performs maintenance tasks.
  • docs: Documentation only changes.
  • test: Adding missing tests or correcting existing tests.

Scope

The scope is meant to describe a specific module/part of the application and it's highly dependant on the application you are building.

Some examples to serve as inspiration:

  • admin: Refers to the admin panel.
  • users: Refers to the user management module.
  • payment: Changes on the payment gateway.

Message Samples

chore(deploy): Update Docker base image to v2.6

Closes #345

feature(admin): Add users CRUD

We can now manage users through the admin panel.
We have added a new search module with an integrated calendar to be able to
filter entities by creation date.

https://trello.com/c/random-id/20-mycooltask

fix: Users can't log out when authenticated via oauth2

JIRA Issue: 23456

Git branches naming

Any branch created for the project will have the following structure:

<type>/<short-name-of-task>

Samples:

  • feature/users-crud
  • fix/logout-for-oauth-users

Git workflow

We are using a modified and simplified version of Gitflow.

For big projects already deployed to production, there will always be two branches: main (master in older projects) and development. The main branch will contain the code that has been deployed while the development branch will contain the most recent stable version of it.

For small projects or projects that are have not been deployed we allow simplifying this by working only with a main branch.

These are the required steps to add new code to a branch (development or main, depending on the nature of the project).

  1. Create a new branch using the branch naming convention from the branch you think relevant (main, development).
  2. Do as many commits as are required to complete your task.
  3. You may open a draft Pull Request (PR) if you want some colleagues to review your work in progress.
  4. Once the work is finished, rebase your commits to leave only the meaningful ones for the reviewer to better understand your changes. Leaving only one commit is also fine.
  5. Rebase your branch with the one from where you open yours to have the latest changes.
  6. Open a Pull Request to be reviewed by your colleagues.
  7. Once reviewed, squash & merge on the target branch. The commit resulting from the squash & merge must be compliant with the Commit Message Format.

If the project is using a development branch, this is the recommended way of merging against the main branch:

  1. Create a Pull Request from development to main
  2. Once all automated tests and manual reviews have finished, merge the development branch to the main branch by creating a merge commit strategy.
  3. Create a new Github release pointing to the main branch and create a new tag to identify the release.

You might want to add additional steps depending on your project.

Dangerous behaviours

  • Avoid using git push -f while working on the same brach with other developers. Use git push --force-with-lease instead.

Credits

This guide is heavily influenced by:

Some parts of this guide are a copy & paste of theirs. All the credit and respect go to the original authors 🙌