01 Rules & Guides

These rules and guides are written with git (a decentralised SCC system) in mind:
- commit = add changes to local repository
- push = sync changes with remote (central) repository

• Commit early, commit often

  • Commit only intentional changes (avoid “Save all”!)
  • Group changes logically into multiple commits (eg. by module)

• Talk to the other developers to avoid editing files at the same time

  • this is especially true for binary files such as all LabVIEW files

• Implement and apply changes in your own feature branches, not in develop or master

  • use gitflow

• Use .gitignore settings

• Try to avoid committing unfinished work (finish your train of thought)

  • Remember: Executable (no „broken VIs“) does not necessarily mean finished

• No broken code outside own feature branches

• No changes to develop branch without integration testing

Meaningful branch names

• For naming, adhere to the format described here:

  • (Optional) start with the number (only the digits) of the issue that's addressed in this branch
  • An underscore (_)
  • A descriptive, but short and precise string

    • no capital letters
    • separate words with dash (-)
  • An underscore (_)
  • Your initials (first letter of first name, first two letters of last name)
  • If possible, use lowercase letters
• These rules apply also (and especially) if you're working with gitflow. Rules are to be applied to feature and hotfix branches.

• Examples:

  • 106_module-names-in-ui_mse
  • update-hse-libs_jha

Meaningful Commit Messages

• should summarize the changes done in one short sentence or a few words
• should work like a headline, so the history is more useful
• See also:

  • Writing a Good Git Commit Message (GitKraken)

• Think of the commit message as the end to this sentence “If applied, this commit will your commit message here”
• Examples:

  • If applied, this commit will refactor subsystem X for readability
  • If applied, this commit will update getting started documentation
  • If applied, this commit will remove deprecated methods
  • If applied, this commit will release version 1.0.0
  • If applied, this commit will merge pull request #123 from user/branch

Mentioning other resources like issues in commit messages will make it easier to map commits on the git history with other tools like issue trackers etc. Depending on the tool used, it will allow for jumping from one item to another (like clicking on the issue number in a commit message and jumping to the issue description).

Issue

Add the string (issue #<number>) to the commit message and use one of the defined prefixes for release notes.

  this is some message (issue #45)

Merge Request

Add the string (MR !<number>) to the commit message

  another message (MR !7)

• Use the tag annotation to create a static description for a release:

WIP: definition of rules to be used for automatically generating useful release notes

• every line starts with one of the following prefixes in upper cases

  • [FIX] (don't use BUG)
  • [FEATURE]
  • [IMPROVEMENT]
• References to issues

  • (issue #123)
  • (issues #123, #124)
• no bullet points

• Setup lvdiff (and lvmerge) for your git client

  • https://www.sasworkshops.com/setting-up-lvcompare-and-lvmerge/
• Use project-specific .gitignore settings

• Avoid committing project files unless you explicitly changed them (like adding another build or library), otherwise unnecessary merge conflicts may arise
• Stage only the .lvproj file for a separate commit, and add any changes (what was added/removed) to the commit message

• Stage only one FPGA main VI/bitfile per commit operation
• Add compilation results to commit message.