User Tools

Site Tools


Sidebar

Imprint

kb:bestpractices:scc:rules

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

Common

  • 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
Branching

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)
  • 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

Unfinished Code

  • 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

Commit Messages

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
  • 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

References

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

  this is some message (issue #45)

Merge Request

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

  another message (MR !7)

Release Notes

  • 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

  • Prefixes for commit messages
    • [FIX]
    • [FEATURE]

LabVIEW Specific

  • Avoid committing project files unless you explicitly changed them (like adding another build or library), otherwise unnecessary merge conflicts may arise.
  • For FPGA: Stage only one FPGA main VI/bitfile per commit operation and add compilation results to commit message.
kb/bestpractices/scc/rules.txt · Last modified: 2021/03/30 08:01 by joerg.hampel