.Stat Suite documentation

Development guidelines

Table of Content

NOTE: these guidelines describe how the .Stat Suite developer team members are applying the git-flow process and what coding standards are followed.
As an external contributor of the project, you can directly jump in the very well described contributing to an open source repository, where it is explained how to contribute to an open-source project by submitting Merge Requests to the project maintainers.


Git-flow

Overview

The .Stat Suite gitlab repositories use the following naming conventions for the branches:

  • master (name=master)
    • represents the production state
    • should always be deployable
  • dev (name=dev)
    • developer’s hub
    • should always be developable (ie can be buggy as long as it does not block developers)
  • feature branches (name=feature/*)
    • new features/experiments
    • should be synced with dev from time to time
  • patch branches (name=patch/*)
    • fixing/enhancing/refactoring existing features
    • similar to feature branches flow
  • release branches (name=release/*)
    • transitional snapshot between dev and master
    • should be used for demo
    • allows dev branch to receive next release features
  • hotfix branches (name=hotfix/*)
    • fixing critical bug(s) in production
    • avoid blocking dev while fixing master

Rules

  • feature/patch branches are created from dev (after a merge in dev)
  • feature/patch branches must be merged back into dev when the feature is done
  • release branches are created from dev (after a merge in dev)
  • release must be merged back into dev and master
  • hotfix branches are created from master (after a merge in master)
  • hotfix branches must be merged back into dev and master

Good practices

  • perform atomic commits (ie commit a lot)
    • git history is detailed
    • allows efficient time travel in past
    • branches are squashed into dev, so dev history is not flooded
  • push often, like twice a day at least
    • backup your work (commits are local)
    • share your work

Merge request conventions to maintain git-flow quality

  • The description of a merge request must contain information related to what is being changed and the gitlab ticket URL to link it with the merge request.
    • This description must be relevant and concise to provide a clear understanding of the implemented changes.
  • In case of multiple commits in a merge request, the peer-reviewer should squash the commits into the target develop branch to maintain a clean and easy-to-follow Git history.
  • When creating a new merge request, the request should not be conflicting with the target version of the code, and the automatic validation tests should be passing.
    • In case of potential conflicts in the merge request, the person peer-reviewing the related ticket will initiate the conflict resolution process. Depending on the situation, resolution may involve the peer-reviewer, the original implementer, or other involved developers.
  • The contributor is free to choose between merging develop into the feature branch or rebasing the feature branch on top of develop to keep the feature branch up to date.
    • NOTE: .NET team members prefer the rebase method, but as mentioned above, this is only a recommendation.
    • Before creating a merge request, the contributor is always required to keep the feature branch updated alongside develop and free of conflicts.

Use case of a git-feature

lifecycle of a feature (morebanana).

$ git checkout dev
$ git pull
$ git checkout -b feature/morebanana
$ git push origin feature/morebanana

At this point, a new feature branch has been created from dev and pushed to origin.

$ git commit -m 'add a banana'
$ git commit -m 'add another banana'
$ git push

It is important to commit and push code to back it up.
If you are not working alone on a feature, do a git pull before pushing.
If the feature is big, keep it up to date with dev to limit conflicts:

$ git checkout dev
$ git pull dev
$ git checkout feature/morebanana
$ git merge dev

Once the feature is done, squash it into dev:

$ git commit -m 'last commit!'
$ git push
$ git checkout dev
$ git pull
$ git merge --no-ff feature/morebanana

The merge option --no-ff allows to squash all the commits of the feature branch into a single commit in dev branch to let the history clean and clear.
Last thing to do is removing the local feature branch and let the world know about the new feature:

$ git branch -d feature/morebanana
$ git push

Use case of a git-conflict

I am working on a new feature, while updating my feature branch with dev, I get a conflict.

$ git checkout dev
$ git pull dev
$ git checkout feature/morebanana
$ git merge dev

The merge failed because there is a conflict.

$ git mergetool

The above command will launch your default editor in a diffing mode with 3 versions of the conflicted file:

  • the remote version
  • the reconciliated version
  • the local version

The essence of resolving a conflict is to help git by writing the reconciliated version from the remote and the local versions.
A merge can have more than one conflict.
A conflict generally does not concern a whole file but only a chunk of it.
Once all conflicts are solved, let git know about it:

$ git commit

No need to enter a message neither to add reconciliated (and thus updated) files to the stage, git does automatically (conflicted state).


Process

  • All changes to the code are done via merge requests. No one ever pushes directly to master. This applies to all core developers and community contributors.
    • All changes to code need to be approved by a member of the core technical team. A member cannot approve their own code.
  • All changes to code must meet the published guidelines on code style and version control practices.
  • Merge requests are configured with CI/CD for all required security checks. If any check fails, then the core team must request fixes to the merge request.

Coding standards

We are using JavaScript (Node.js), SQL and C# (on .NET Core).

  • ECMAScript 6 is used to standardise JavaScript (Node.js) code.
  • Jetbrains’ Resharper is a plugin used on SQL and C# (on .NET Core) code checking in real-time standardisation and common practices.

Linting utilities

  • ESlint is used on JavaScript (Node.js) for checking code’s consistency and reporting on security patterns.
  • Checkmarx is used for SQL and C# (on .NET Core) code.

Contributing to an open source repository

See here for the process to be followed: https://www.selketjah.com/oss/2018/02/06/flow-of-open-source/