Source Control

Workflow

Loupe uses git source control and GitHub to manage and track project changes. For more information on git, see https://www.atlassian.com/git/tutorials.

We use Gitflow to determine what branches are created in a repository and how they are used.

Gitflow uses 5 types of branches: main, release, develop, feature, and hotfix.

  • main: Running on the physical machine
  • release: Commissioning or updating a machine
  • develop: Integrating completed features
  • feature: Implementing new features
  • hotfix: Fixing bugs on the machine

New software features should be implemented on feature branches. Once the feature is complete, the changes should be reviewed and merged into the develop branch, and then the feature branch should be deleted.

Before commissioning or updating a machine, a release branch should be created off of develop and tested on the physical machine until it is stable. Once it is stable, the release branch should be merged into both main and develop, and then deleted.

If the machine needs a bug fix after commissioning or updating, then a hotfix branch should be created off of the main branch. Once the fix is finished, the hotfix branch should be merged into both main and develop, and then deleted.

Branches other than main or develop should be named <branch_type>/<description>, for example, feature/file-logging. A new merge commit (not fast-forward) should be made when merging into the main or develop branches. Branches other than main or develop should be deleted after being fully merged.

For a detailed description of Gitflow, see https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow.

Versioning

Loupe uses semantic versioning.

Version numbers follow the convention Major.Minor.Patch. Versions less than 1.0.0 are considered unreleased and in development.

  • Major: The major version number should be incremented if the project has been released (version > 1.0.0) and there are changes that affect the whole project, such as changing the location of a configuration file.
  • Minor: The minor version number should be incremented whenever features are added.
  • Patch: The patch number should be incremented whenever small changes and bug fixes are added.

Whenever a branch is merged into the main branch, the version number should be incremented and tagged on the main branch.

Full documentation for semantic versioning can be found at https://semver.org/

Commit messages

An effective repository has concise and meaningful commit messages.

There should be a concise subject line to a commit message that summarizes the changes made using the imperative mood. The subject line should be capitalized and should not have a period at the end.

A useful example from Chris Beams is to make sure your commit message can finish the sentence: If applied, this commit will your subject line. For example Modify data collection frequency.

If necessary, a body section can be added after the subject line with a blank line between them. The body should explain why the changes were made, not how.

More information on proper formatting for commit messages can be found at https://chris.beams.io/posts/git-commit/.

Pull requests

Pull requests consist of three parts:

  • Title: Short informative summary of the pull request
  • #[Issue_ID] (if applicable)
  • Description: More detailed explanatory text describing the PR for the reviewer

Here is an example of a complete PR:

Add 'Edit on Github' button to all the pages #113

## What 

Adds an 'Edit on Github' button to all pages that will redirect users to the repository page. (include pictures)

## Why

This addition lowers the barrier to entry for contributing to the repository.

Title

Pull request titles should respect the following conventions:

  • Short and descriptive summary
  • Ends with a corresponding ticket/story id (e.g., GitHub issue, etc.)
  • Capitalized and written in imperative present tense
  • Does not end with a period

Example: Fix motors not de-powering in 'Stopping' state #6599

Description

The description of a pull request should:

  • Be separated with a blank line from the subject (Github will handle this)
  • Have an overview of the Issue
  • Give an example and/or steps to reproduce
  • Explain what, why, etc.
  • Capitalize each paragraph
  • Optionally include Markdown

Example: Motors will now de-power in the 'Stopping' state, which will assert that motors will always be disabled in the 'Stopped' state. This is to prevent unsafe situations when users enter the cell