Klassen Software Solutions

Git Procedures

Git Example We use git, typically hosted on GitHub, as our main source repository. When developing software for KSS, you generally need to know the following.

Branches

  • master: This is the main repository branch and is always kept in a deployable state. This means that no work is done on it directly, and the branches are not merged into it until they are ready for the release of a new version.
  • release/v##: When it is time to change the major version of our software, such that master will no longer be back-compatible, we generate a release branch which will be used if patches must be made to a legacy version. (The ## would indicate the version, for example release/v2 or release/v3.1.) Like the master branch, the release branches are protected and code is only merged into them when they are ready to release a new version.
  • development/v##: The development branches are where the work towards the next major version is kept. Typically there would only be one of these, indicating the current version (e.g. development/v2), but occasionally, if a release branch requires a significant amount of work, there may be a development branch created for it as well.
  • feature/##-description: The feature branches are where the actual work is done. They are branched from the appropriate development (or sometimes release) branch. The ## should be the number of an issue in the given software project, and the description should be a short hyphen-separated-text description of the feature (or bug). For example, feature/12-auto-publish-docs.

Practices

  • You may push your feature branches at any time. Typically this will cause the CI (continuous integration) to run both the automated tests and the static code analysis. They will both need to pass before the branch may be merged.
  • If you prefix your comment with WIP: then the CI will not be run on the assumption that a "work in progress" would not be expected to pass anyway.
  • Before you merge your commit, you should attempt to squash your separate commits into a small number of them, indicating the significant work steps that you wish recorded. In particular, any WIP: checkins should be squashed.1
  • Do not used fast-forward merging when merging in your feature branches. We want to see the "create commit" and the separate branch path even after the merge is complete.2
  • Do not remove your branch after you have merged. Obviously you can remove it from your local machine, but we want the branch to remain in the repository, possibly for a number of years.2
  • After your branch is merged, if the issue is listed in a project, you should move it from "In progress" to "Done." However, you should not close the issue itself. That will be done either via the Git automation, or manually by the QA or release team, when the release is actually made. In other words, while the work may be considered done, the issue is not considered closed until it has actually been included in a release.

Commit Comments

Each commit should contain a comment describing it. At a minimum it must have a single, reasonably short, one line description. Optionally, that line can be followed by a blank line, then by a longer description.

When making your final commit (or when editing the comment as part of a squash), you should also reference the issue number (or numbers if more than one is involved), using the keywords "Fixes" for bugs and "Closes" for all other types of issues. An example of a commit message may be the following:

Added the CI

Also fixed the problem that was causing "behave" to fail intermittedly.
Closes #1, #3, and #22
Fixes #28

An example of a simpler message used for an interim checkin may be the following:

WIP: saving my current state before I try a risky refactoring

Pull Requests

For the most part, developers do not need to create pull requests. Instead, once you have merged your feature branch into the development branch, and pushed the development branch, your part is done.3

The only time that pull requests are used is when the development branch is merged into the master (or into a release) branch. This is typically done by one of the more senior developers or by the QA or release team (if a project has such a team).

1. While squashing out the `WIP:` commits is preferred, it is considered a "nice to have" as opposed to a hard requirement. If the squashing does not work smoothly, then you may merge without squashing rather than spending significant time trying to "fix" the history.

2. The reason for this is that if we need to track down problems in production code, it is useful to be able to search back, sometimes even a few years, in order to see what commits caused the problem.

3. "Done" is a relative term. If a code reviewer decides that your code is not good enough, it may be sent back to you. At that point you may need to resurrect the branch, make your fixes, then push it again. This differs from some development shops where the code review is considered a "gate" and all progress is halted until it passes.