Source Control

Source control allows us to work together on writing a shared codebase (really just a bunch of text files). It helps us do a few key things:

• Get a copy of the latest code
• Track changes to the code
• Save ("commit") a version of the codebase
• Share those changes with others
• Merge in changes from others
• Roll back changes when things go wrong
• Store the code in a central location

Key Concepts

Git vs. GitHub

Git is a a popular, open source distributed version control system that allows you to track sets of changes to code. Once you have cloned a repository to your local computer you start to make changes and save those changes, or commit them locally on your computer. The repository that you cloned to your machine is your local copy, and a central server acts as the remote that you push code to or pull code from. GitHub is an incredibly popular proprietary commercial service that hosts git remote repositories. There are many other types of version control systems and services (Microsoft Azure DevOps, AWS CodeCommit, GitLab, etc.) that all provide capabilities similar to GitHub.

Branching

When you want to make a set of changes, you create a branch. We often follow a trunk-based or GitHub Flow workflow to apply a consistent approach to branching (and later merging). The strategy to choose depends on the nature of the release cycle. The goal is to have small incremental changes that are merged with the main branch frequently (think a day or two, not weeks or months).

When & How to Commit, Push

Commit: Create commits to capture a snapshot of the code base. (Some compare this to a save point in video games.) This allows you to get to that version of the code, or even pull out a single file within that snapshot. Commit each time you create an incremental step forward - you added something without breaking anything. In general (but not always) your tests should pass before a commit. You should commit often - generally a few times per day. Your commit messages should be short, clean and concise describing the changes made in this specific commit.

Push: Commits happen on your local computer. That isn't part of the shared repo (e.g. GitHub.com) until you push the code to the remote repo. When you are working on a feature branch, it is generally best to push with each commit. This allows others to be able to see the most recent working increment of your code as needed.

Managing Secrets

"Secrets" refers to things that the running application needs to know, but are generally sensitive (things like database URLs, credentials, API keys, ...) so we don't want to share secrets widely because that would create a security risk. For example, sharing AWS credentials on a public repo could allow a bitcoin miners to hijack your account. This is not good. Instead, we inject such secrets as environment variables (a.k.a. ENV) to the application. Vault tools provide more sophisticated management for production systems.

Pluribus Expectations

• Git: We use Git whenever possible. It is by far the dominant industry standard.
• Trunk-based development: The trunk-based approach is a decent baseline. If we cannot get around release-specific overhead, then other approaches may be appropriate.
• GitHub: We use GitHub by default for any repos owned by Pluribus, but often work with client-provided repositories.
• DotEnv: By default, we use a "dotenv" approach. The libraries differ by language, but all use a local file (e.g. /.env) that is also in the .gitignore. A /.env.example file shows developers what values need to be filled in. In development envirionments, the contents of the file are loaded as environment variables. In production, the same environment variables are set via other means.

Resources

• Read Git docs Getting started
• Practice using proper hygiene on real or for-fun projects
• Git Flight Rules and GIT WTF walk you through common scenarios and the corresponding git commands