Sections within Source Control
- Following industry best practice to work in geo-distributed teams which encourage contributions from all across CSE as well as the broader OSS community
- Improve code quality by enforcing reviews before merging into main branches
- Improve traceability of features and fixes through a clean commit history
Consistency is important, so agree to the approach as a team before starting to code. Treat this as a design decision, so include a design proposal and review, in the same way as you would document all design decisions (see Working Agreements and Design Reviews).
Creating a new repository
When creating a new repository, the team should at least do the following
- Agree on the branch, release and merge strategy
- Define the merge strategy (linear or non-linear)
- Lock the default branch and merge using pull requests (PRs)
- Agree on branch naming (e.g.
- Establish branch/PR policies
- For public repositories the default branch should contain the following files:
Contributing to an existing repository
When working on an existing project,
git clone the repository and ensure you understand the team's branch, merge and release strategy (e.g. through the projects CONTRIBUTING.md file).
Mixed DevOps Environments
For most engagements having a single hosted DevOps environment (i.e. AzureDevOps) is the preferred path but there are times when a mixed DevOps environment (i.e. AzureDevOps for Agile/Work item tracking & GitHub for Source Control) is needed due to customer requirements. When working in a mixed environment:
- Manually tag PR's in work items
- Ensure that the scope of work items / tasks align with PR's
Commit Best Practices
- Make small commits. This makes changes easier to review, and if we need to revert a commit, we lose less work.
- Commit complete and well tested code. Never commit incomplete code, get in the habit of testing your code before committing.
- Don't mix whitespace changes with functional code changes. It is hard to determine if the line has a functional change or only removes a whitespace, so functional changes may go unnoticed.
- Write good commit messages.
A good commit message should answer these questions:
- Why is it necessary? It may fix a bug, add a feature, improve performance, or just be a change for the sake of correctness
- How does it address the issue? For short, obvious changes, this can be omitted
- What effects does this change have? In addition to the obvious ones, this may include benchmarks, side effects etc.
- What limitations does the current code have?
Consider this when writing your commit message:
- Don't assume that the code is self-evident/self-documenting
- If it seems difficult to summarize your commit, it may be because it includes more than one logical change or bug fix. If so, it is better to split it into separate commits with
git add -p
- Don't assume the reviewer understands the original problem. It should be possible to review a change request without reading the contents of the original bug/task.
Good message structure:
- Separate subject from body with a blank line
- Limit the subject line to 50 characters
- Capitalize the subject line
- Do not end the subject line with a period
- Use the imperative mood in the subject line (Fix typo in log vs. Fixed typo in log or Misc fixes in log code)
- Wrap the body at 72 characters
- Use the body to explain what and why vs. how
- Reference fixed issues with closing keywords
Example of a well-structured git commit message:
Add code review recipe for Go - Helps teams automate linting and build verification for go projects. - Also gives a list of items to verify for go code reviews. The PR does not add info about VS Code extensions for go, this will be added in issue #124 Closes: #123
You can specify the default git editor, which allows you to write your commit messages using your favorite editor. The following command makes Visual Studio Code your default git editor:
git config --global core.editor "code --wait"
- How to Write a Git Commit Message
- A Note About Git Commit Messages
- On commit messages
- Information in commit messages
- Git commit best practices
- The GitHub Hello World
- CSE Git details details on how to use Git as part of a CSE project.
- GitHub - Removing sensitive data from a repository
- How Git Works Pluralsight course
- Mastering Git Pluralsight course