OIT Version Control

Scope: OIT
Type: Standard
Version: 2022-initial

Goal

The goal of a version control system (VCS) is simple: to keep track of changes to your source code. Proper use of a VCS gives you a clear record of technological decision-making over time, and store of structured data with powerful capabilities.

For those who write or maintain source code, tracking changes is useful for a number of purposes, such as examining differences between different versions of code.

Use of a VCS contributes toward important organizational objectives as well. A centrally-managed VCS supports business continuity by preserving the source code of critical systems, and the version history supplies an audit log of changes.

See the Requirements section for more detail on how and why VCS use is generally recommended, and frequently mandated.

Ownership

Direct questions to the Owner: Alex Tulinsky email redacted

Resources to comply with this standard should be directed via the Executive sponsor: Jason Lin email redacted

Timeline & Enforcement

All applications SHOULD live up to this standard. All critical applications MUST live up to this standard, and have been required to do so since 2016.

Other projects that can benefit from version control (infrastructure-as-code configurations, standards repositories) SHOULD live up to this standard. If these projects support a critical application, they MUST live up to this standard by the end of 2022.

Exception Process

Exceptions to use other repositories can be granted by the Architecture Review Board. An exception request must be submitted to the ARB with an explanation of why the recommended Version Control Repositories can not be used. An exemption shall be granted by majority vote.

Terminology

Requirements

Scope

  1. This document covers all applications and projects that OIT manages, oversees, or otherwise participates in.
  2. The most common use of VCS is for application source code, but this document covers all uses, such as “infastructure as code” configurations.

Repositories

  1. The code MUST be checked in to one of OIT’s recommended version control systems regularly.
    1. The standard VCS tool is Git and the central repository is the OIT GitHub Enterprise service
  2. Each application or project SHOULD have its own repository.

Secrets

  1. Secrets MUST NOT be committed to version control in clear text
    1. It is permissible to add encrypted secrets, as long as all of the following criteria are met. When in doubt, consult the security team.
      1. The key to decrypt the secret MUST NOT be checked in to the same repository
      2. Alternative means of meeting the business requirements incur excessive cost
  2. If a secret is added to version control in clear text, you MUST purge the history to avoid the secret leaking. You SHOULD also rotate, regenerate, or change the secret if possible.

Background

Introduction

VCS has a long history and among the best-known systems include: CVS, Subversion, Git, and Mercurial.

The most common use case is to support application development: tracking history of an application’s source code, easing collaboration and team development, and supporting multiple run-time environments, among other things.

Beyond app development and source code strictly-speaking, VCS is often used for artifacts like configuration files and documentation. This is especially common with source code equivalent artifacts like documentation or config templates (used to generate final artifacts through some build process) or test harness definitions.

The basic history-tracking function of VCS is fundamental to a wide range of usages and features, some of which are very common and others that may or may not be relevant to a specific use case. The guidelines below cover the most common and are meant to help users understand the general standard around VCS from two perspectives: (1) how VCS can help you do your work better, and (2) how your VCS use benefits the OIT organization.

User-Oriented VCS Guidelines

From a user perspective, VCS should support your desired workflow.

VCS offers useful features for the individual coder:

The ubiquity of VCS has made for a plethora of tooling around VCS usage – seamless integration with editors and IDEs, diff tools, visualization of the change graph, and so on.

Organizational VCS Guidelines

From an organizational perspective as well, VCS should support your desired workflow.

The team involved in a coding project benefits from many of the same functions that assist individuals directly working with source code.

Both the team and the larger organization benefits in terms of operational continuity, as VCS helps support

Finally, the benefits of tooling goes for the team as well as the individual coder – VCS is tightly integrated with modern team productivity tools like:

Given the range of benefits enabled, VCS use has become standard practice for all forms of software engineering.