Code Management

General

Within Recognize, we use Git as our software for version control. To store our code remotely, the following services are allowed:

  • Azure DevOps
  • GitHub

The use of any other version control software, or other remote Git solution is prohibited. To prevent the loss of any code, it is recommended to push any code you are working on at the end of the day to the remote version control software that is used for your project. When finished and creating a pull request, please amend all intermediate commits, which in some cases van be done from within the remote version control software being used.

Repositories

Projects can have several components. Within Recognize, these components should be stored within one single repository (mono-repo) with one exception: mobile apps. These can have a separate repository, as it makes testing the app with different versions of the backend software more easy.

Commit Messages

To find information about a specific feature quickly, all the commit messages that are made should adhere to a fixed format. Every commit message (apart from merge commits) should have a ticket number defined, and a short but descriptive comment about the changed code within the commit. This is done to ensure traceability, and see which commit to relate to what functionality. It should be formatted as follows:

<ticket number> - <short description>, e.g. ID-96 - Add sections about code management and mobile app development to the development policy

Pull Requests

All code that is deployed to any of the three environments, should be checked by at least one other person, other than the author. This is done in the form of pull requests. A pull request is created when a developer finishes a feature, or bugfix, or wants intermediate feedback. Unless the feature is a hotfix, a pull request should be targeted at the develop branch. Before merging, a pull requests should be approved by at least one other team member other than the author and cannot be in the 'request changes' state. All CI/CD pipelines need to be finished and have ran successfully. See also the section on branch permissions.

Branching Model

For our branching model, we use the Gitflow Workflow. The Gitflow Workflow defines branch names for the three environments. All code follows a fixed flow, as shown below:

Gitflow Visualization (source Chuka Ofilioti)

Development

During the development of a functionality, or bugfix, one creates a new branch. Depending on what is being developed, one can create a feature/ branch, or a hotfix/ branch. A feature/ branch is used for a new functionality, whereas a hotfix/ branch is used for bugfix. All feature/ branches are branched from develop or a different feature/-branch, whereas a hotfix/ branch is based on the current master branch. The naming of a feature/ branch is as follows:

feature/<ticket-number>-<short description>, e.g. feature/ID-96-write-development-policy

For hotfix/ branches, the naming is similar:

hotfix/<ticket-number>-<short description>, e.g. hotfix/ID-97-fix-development-policy-spelling-error

Test

The develop branch represents the state of the test environment. For more information, visit the section about the test environment.

Acceptance

A release/` branch represents a new version for the acceptance environment. All release branches should be named in the following format: release/<version number> or release/<tenant>/<version number> where tenant can be a isolated environment for a customer. The version number should be formatted according to the semantic versioning format. A release/* branch is based on the develop branch. All versions should be incremental. For more information, visit the section about the acceptance environment.

Production

The master branch contains the current state of the production environment. To make a release to the production environment, one can merge a release/* branch into the master branch. This commit should be tagged with the corresponding version number. For more information, visit the section about the production environment.

Branch Permissions

Although not all remote version control tools support the same options, in general, every project should adhere to the following branch permission model.

  • develop

    • Rewriting branch history is not allowed
    • Deleting this branch is not allowed
    • All members of the team should have write access via pull requests merges
    • All team members have direct write access, which should only be used for releases and in case of an emergency
    • Merge criteria
      • Pull request should not be in the changes requested state
      • Pull request should have at least 1 approval (although a team can opt to increase this)
      • The last commit of the branch in the pull request should have at least 1 successful build, and no failed builds.
    • A merge should be prevented if one of the merge criteria is not met

  • release/*

    • Rewriting branch history is not allowed

    • Deleting this branch is not allowed

    • All members of the team should have write access via pull requests merges

    • All team members have direct write access, which should only be used for releases and in case of an emergency

    • Merge criteria

      • Pull request should not be in the changes requested state

      • Pull request should have at least 1 approval (although a team can opt to increase this)

      • The last commit of the branch in the pull request should have at least 1 successful build, and no failed builds.

    • A merge should be prevented if one of the merge criteria is not met

  • master or main

    • Rewriting branch history is not allowed
    • Deleting this branch is not allowed
    • All members of the team should have write access via pull requests merges
    • All team members have direct write access, which should only be used for releases and in case of an emergency
    • Merge criteria
      • Pull request should not be in the changes requested state
      • Pull request should have at least 1 approval (although a team can opt to increase this)
      • The last commit of the branch in the pull request should have at least 1 successful build, and no failed builds.
    • A merge should be prevented if one of the merge criteria is not met