Skip to content

Latest commit

 

History

History

best-practices-for-successful-git-collaboration

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
README.md
README.md
 
 

README.md

Annotations to the discussed page:

Unspecified link collection:

Comment:

  • "If it's not pushed, it doesn't exist."

Discussed page:

Git Guidelines

Commit Messages Guidelines (How to work with Git)

Synopsis/tl;dr:

  • Adhere to Conventional Commits (whenever possible)

  • Imperative Mood

  • Refer to Jira Ticket (Use Smart Commits!)

  • Short (<72 chars) Summary

  • More detailed explanatory text after line break

Detailed

Short (72 chars or less) summary

More detailed explanatory text. Wrap it to 72 characters. The blank line separating the summary from the body is critical (unless you omit the body entirely).

Write your commit message in the imperative: "Fix bug" and not "Fixed bug" or "Fixes bug." This convention matches up with commit messages generated by commands like git merge and git revert.

Further paragraphs come after blank lines.

  • Bullet points are okay, too.
  • Typically a hyphen or asterisk is used for the bullet, followed by a single space. Use a hanging indent.

Example

feat(ABC-123): Add CPU arch filter scheduler support

In a mixed environment of…

A properly formed git commit subject line should always be able to complete the following sentence

If applied, this commit will

Rules for a great git commit message style

  • Separate subject from body with a blank line

  • Do not end the subject line with a period

  • Capitalize the subject line and each paragraph (adhering to Conventional Commits)

  • Use the imperative mood in the subject line

  • Wrap lines at 72 characters

  • Use the body to explain what and why you have done something. In most cases, you can leave out details about how a change has been made.

Information in commit messages

  • Describe why a change is being made.

  • How does it address the issue?

  • What effects does the patch have?

  • Do not assume the reviewer understands what the original problem was.

  • Do not assume the code is self-evident/self-documenting.

  • Read the commit message to see if it hints at improved code structure.

  • The first commit line is the most important.

  • Describe any limitations of the current code.

  • Do not include patch set-specific comments.

References in commit messages

If the commit refers to an issue, add this information to the commit message header or body.

In header:

fix(ABC-123): Refer to GitHub issue…

In body:

… Fixes ABC-123, ABC-124

References

Branching Guidelines (How to work with Git Repos)

Synopsis/tl;dr:

  • develop always contains buildable code

  • main (old: master) contains every main-line release

  • Code reaches develop & main only through Pull Requests

  • Branch names follow the schema feature/ABC-123-short-ticket-description

  • For releases use release/MAJOR.MINOR.PATCH, for hotfixes use hotfix/MAJOR.MINOR.PATCH

  • Custom releases use a different prefix, custom-prefix/feature/ABC-123-short-ticket-description, etc. We try to avoid custom releases!

  • Always create a (Jira) ticket and refer to it! (“No ticket, no work!”)

Detailed

At the time of writing we currently use Git Flow. For a detailed explanation read the reference. This might change in the future with improved CI/CD.

Typically a repo has at least two branches:

  • main (new/encouraged naming) or master (old/discouraged naming): Each commit onto this branch represents a main-line release. Jumping between commits on this branch represents jumping between publicly released versions.

  • develop: Each commit onto this branch represents a piece of work (== feature) being worked on and finished at the time of the commit. Jumping between commits on this branch represents jumping between functionally complete versions with a potentially different feature set.

When working on a new feature, a developer checks out develop, branches off from there to feature/ABC-123-short-description, and ends up (squash) committing back to develop using a Pull Request.

References

Pull Request Guidelines (How to request Code Reviews)

Synopsis/tl;dr:

  • Use git rebase for a linear history

  • Descriptive PR Name with corresponding ticket [ABC-123]

  • Open PR asap & mark with “[WIP]”

  • Describe your PR! Bad: No Description. Better: Too much detail.

  • Delete old feature/-branches after merging

  • Keep release/-branches

Detailed

We use git rebase to keep our merge history linear, clean and easy-to read. When you are done with your work on your feature branch and your main branch is up-to-date:

git rebase main git push --force-with-lease

This also allows you to have merge commits in the history of your branch (e.g. from previously merging main into your feature/ branch).

References

Code Review Guidelines (How to review other people’s code)

Synopsis/tl;dr:

  • Be nice when reviewing other people’s code - challenge the idea, not the person

Detailed

WIP

References