Repositories

Guide to creating and managing Q-CTRL repositories


Source code and software created at Q-CTRL are versioned using git repositories.

Q-CTRL uses GitHub to host the repositories and they can be either private or public.

Types of repositories

The type of repository defines what configurations are set as well as some of the naming conventions.

Development

Development repositories are the default type. They are defined as repositories that contain any source code that will be directly used to contribute to Q-CTRL’s product. This can refer (but is not limited) to:

  • Applications.
  • Configurations.
  • Documentation.
  • Infrastructure code.
  • Software.

Development repositories will have more strict requirements around access control as well as configurations to ensure a higher standard of code.

Research

Research repositories are defined as repositories that are used for research purposes (including spikes). In order to encourage quick development for proof of concepts, the configurations on the repositories are less strict to allow this. As research repositories are held to a lower standard, they cannot be directly used to contribute to Q-CTRL’s product and should be discouraged from long term use. A research repository MUST be correctly configured before it can become a development repository.

Naming repositories

Refer to naming conventions.

Research repositories

All research repositories are denoted by a research- prefix on the repository name to identify it as a research repository.

Repository descriptions

Repository descriptions MUST take the form <emoji> <project name>.

Examples

RepositoryDescription
Q-CTRL Python Open Controls🎛 Q-CTRL Open Controls
Q-CTRL Template🧩 Q-CTRL Template

Ownership of repositories

All repositories MUST have at least one owner. An owner MUST be a team and not an individual person. Teams are defined by Q-CTRL’s organization structure.

A repository MAY have more than one owner and ownership of the repository can refer to:

  • All code in the repository.
  • A folder.
  • A file.

For example, for a GraphQL project, the Back-end Engineering Team may own the API code, the Front-end Engineering Team may own the GraphQL schemas defined in a folder, and the DevOps Engineering Team may own certain CI files.

Repository privacy

All repositories by default should be private unless there is a reason to make them public. Some reasons on why a repository would want to be public include:

  • The repository is open source.
  • The repository needs to be publically viewable by people outside of Q-CTRL.
  • The repository is a fork of another public repository.

Configuration

All repositories MUST use the standard configurations. If the repository is a development repository, then it also MUST use the development configurations.

Standard configurations

ConfigurationDescription
Automatically delete merging branchThis is to avoid stale branches. Restore the branch if more contributions are needed.
Issues disabled for private repositoriesUse JIRA to create issues. Issues are to be used for public facing issues only.
Master branch protectionThe master branch is protected and no commits can be pushed to it without a pull request.
Squash merges onlyAll other merge types are disabled. See contributing.
Wiki is disabledUse README files or contribute to Q-CTRL Elements and Q-CTRL Docs for documenting depending on the use case.

Development configurations

ConfigurationDescription
Dismiss stale reviewsDismissing stale reviews will require an owner to approve a pull request if any changes have been done since their last review. This is in place to avoid the situation where a pull request is approved, then a change is introduced that would have not been approved but was merged anyway.
Require pull requests to be approved by an ownerAn owner must approve a pull request before it can be merged.