Skip to content

Latest commit

 

History

History
114 lines (80 loc) · 6.08 KB

readme.md

File metadata and controls

114 lines (80 loc) · 6.08 KB
Raw

Source Control

There are many different options when working with Source Control. In CSE we use AzureDevOps for private repositories and GitHub for public repositories.

Sections within Source Control

Goal

  • 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

General Guidance

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

Creating a new repository

When creating a new repository, the team should at least do the following

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"

References:

Resources