Version Control

Use Git for version control and store your code on GitHub (recommended), BitBucket, or equivalent.

Best Practices

A git repository is a version controlled bucket of files and information. Most repositories are made up of code for software but can also include documentation, knowledge bases, blogs, or any collection of plain text files. So what shouldn't go in a git repository?

• Non-text files like Photoshop documents, pictures, videos, etc.
• Generally, files built by a script using code from the repository
• Other large files

Branching

Following the GitFlow methodology, you should Always work with a minimum of 2 branches, a dev branch that can be changed and a main branch that serves as the most recent stable version.

Commits

Commit messages are an often overlooked but important part of working with git. Clear commit messages can be incredibly helpful if there is ever a need to look at the git history or to find when a specific change was made. For best effect, make a commit when any single unit of work is completed. The exact definition of that will differ between projects and languages, but you want individual commits to change as little code as possible and be focused on a specific goal.

• The commit title should be capitalized like a sentence but shouldn't include a period
• The commit title should be written in the imperative voice and answer the question “If applied, this commit will...”
• If additional context is required, use the commit message body to provide that information, explain why the change was made, or reference any Issues the commit is related to
• Don't explain what exactly changed, other developers can always look at the git diff to see the exact code changes

Pull Requests

It is highly encouraged to set up branch protections and require pull requests that should be peer reviewed by someone else familiar with the codebase.

As a best practice, keep pull requests short and focused on a single logical change. Smaller pull requests are easier to review and approve. Here's some more tips for writing a good pull request:

• The title should answer the question “What does this pull request do?”
• In the description, provide context for people who might be unfamiliar with the problem the PR addresses. This is also a good time to link to any relevant Issues
• Don't explain what changes were made (we can see the git diff), but focus on why the changes are needed or how the PR solves the issue it is addressing if an explanation is needed
• Before opening a PR, make sure your code passes any CI/CD checks like linting or unit tests, test the code to make sure it works as intended across any applicable benchmarks, and make sure any build scripts run successfully

Versioning

Its general best practice to use Semantic Versioning which offers guidelines on how to version software in a meaningful way. The basic formula is X.Y.Z for a production build or X.Y.Z-A.B for a pre-release build.

• X in semantic versioning is the major version of the software. It is only incremented when breaking changes are introduced, and all other version segments are reset to 0
• Y is the minor version, incremented when new features or functionality are added. When the minor version is incremented, the patch version is reset to 0
• Z is the patch version, incremented when a bug fix is implemented.
• In the pre-release example, A refers to the prerelease type. These are usually rc > beta > alpha.
• In the pre-release example, B refers to the iteration of that prerelease

In pre-release versioning, rc usually stands for “Release Candidate”.