Skip to content

Latest commit

 

History

History
179 lines (127 loc) · 5.8 KB

flow-git.md

File metadata and controls

179 lines (127 loc) · 5.8 KB
Raw

Git flow

How to use git with this project.

To know how to develop in this project, go here.

Table of contents

Branch naming

There are 2 main branches on which modifications are (normally) not directly applied:

  • master: Represents a stable production state:
    All the code works and provides a functional solution.
  • develop: Usually before merging on master:
    A functional code on which is added a set of new features to be tested for validation.

When can master or develop be modified ?
These branches should never be modified directly (see Merge/Pull Request).

But it can be done if the following conditions are true:

  • All members are aware of the changes and have agreed to them.
  • The changes are ridiculously small (or they are not really developed features).
  • They are made on a critical time or to test infrastructure.

Here's some examples:

  • The CI has just been set on a production server. The change: increase timeout
  • An update of an infrastructure needs to change some parameters. The change: update configuration/environment values

Work branches

To develop, use the dev/ branch directory. It is also the feature directory.
These work branches are followed by a meaningful name or nominal group.

Examples:

  • dev/back/login: implementation of the login in the backend code.
  • dev/common/create-dtos: Creations of common _DTO_s
  • dev/update-id: Change the type of entity IDs from string to number

If using a 3rd party project management, such as Jira, It could be more efficient to add the Issue/task ID in the branch name.

Fix branches

If a feature has already been merged and a fix is needed, use fix/ subdirectory.
The naming is the same as the one for work branches.

Examples:

  • fix/office/login
  • fix/update-id

These branches can also be created from the post-development testing process.

Documentation branches

Use the doc/ directory when the documentation is created or modified.

Examples:

  • doc/how-to-test
  • doc/back/migration

Other branches

Except for the previous reserved names feel free to use other names for other kind of modification.

Examples:

  • infra/ci: Update of the CI process
  • infra/docker: Add some docker files
  • init/worker: Add a new Nx Library

As the branches are deleted once merged, the naming is not that important.
But to keep thing clean and usable (notably on some Git editors) use existing branch directories (e.g. already a documentation/bla branch) or add reserved names to this documentation.

Commit message

Use commitizen:

npx cz

The scope can be freely chosen.

Warning:
Do not use a fix type for something that is not yet merged (on "your" working branch).

Example:

  • A new feature is implemented:
    feat(login): can login
  • Then, even before it is ready to merge, a bug is fixed
    chore(login): do not return the sent password on login

Keep in mind that the fix type will appear in the CHANGELOG.
It would be strange if a Bug fixes section appears for a bug that never occurred.

Merge/Pull Request

This section describe how to create/review/approve/... a Merge Request or Pull Request (or whatever is used).

PR (Pull Request) will be used to reference this.

Creation

When creating a PR, use a meaningful title and add the issue(s) in the description. More information can be added in the description if necessary:

  • Errors encountered (for the reviewer)
  • Important change (not related to the current feature)
  • New utility added (class/function)

Review

No real constraints here except to be humble when reviewing;
Nobody's always true, anybody can still be wrong.

Validation

  • All CI tests must succeed.
  • The styleguide must be respected.
  • The code is up-to-date.
  • (There's tests for the added feature(s))

What is the styleguide applied?
See here.

Approval and merging

To merge a PR, all conversations must be resolved and approved by at least one other person.

A PR can be verbally approved (live review), so it can be auto-approved with the given message approved verbaly by <user.name>.

Merge commit vs squash merge

There is no answer to this here. It is up to the team (or the reviewers of a PR) to define it.

Keep in mind that a squash leaves a cleaner history, but removes information about it.
It also can generate an incomplete CHANGELOG.

After merging

After merging, the branch must be deleted.
In which case, manual tests must be performed on the server(s).
If an error is found, then the merge is revert or a fix branch is created.

The purpose of these manual tests is to ensure that the deployment worked and that no obvious errors occur.