Repository management standards and best practices in [#git]

The organization, maintenance, and security of source code and other project assets are all part of effective repository management. Proactively understanding and following repository management best practices is an important part of working at LinkORB.

At the time of this writing, LinkORB has 250 open source repositories on GitHub and an additional 450 private repositories. The standards and procedures specified in this article are crucial to ensuring security, providing a good developer experience, and maintaining applications at scale. This guide is divided into the following topics:

Location and naming

All repositories should be children of the LinkORB organization on GitHub. As a standard, repository names should:

1. Be brief (3-4 words maximum)
2. Use hyphens between words
3. Exclude the word “LinkORB”

It’s also important to note that repository names often terminate with or include one of the following keywords:

• server: runnable web application servers, API servers
• bundle: a Symfony bundle
• php: a PHP library, often published on either packagist.org as open source or packagist.com as private

While inclusion of keywords is not required, it is suggested when applicable. If you are unsure of how to name a repository, get a second opinion! While GitHub does support repository renaming, use of this option should be limited.

Visibility

Unless otherwise specified by a team lead, all LinkORB repositories should be set to private status.

Open-sourceable

All LinkORB repositories should be structured and maintained in such a way that they can be open sourced at any time. Generally speaking, this means repository content should avoid LinkORB-only concepts, references, and specifics. When possible, such values should be abstracted from the repository.

Main branch settings

The main branch at all LinkORB repositories should named main as well as protected and require a pull request before merging (no direct pushes).

Read access for collaborators

In most cases, repository collaborators should be granted read access. In order to submit updates, collaborators must fork the source repository and submit pull requests from their fork.

Centralized commmunity health files

By default, repositories existing under the LinkORB organization leverage GitHub community health files as defined at github.com/linkorb/.github.

This provides centralized management and consistent organization-wide use of a common:

• Pull request template when opening a PR against any LinkORB repository.
• Contributing guide for making meaningful contributions to LinkORB’s projects on GitHub

Though not automatically used by organization repositories, LinkORB maintains a recommended linkorb_commit.template with the community health files. Specific guidance on the use of this template can be found at Write effective commit messages with a template.

Centralized GitHub actions and workflows

LinkORB employs GitHub actions in both required and optional workflows to:

• Manage application deployment
• Evaluate code quality and adherence to standards
• Automatically tag new versions + releases based on conventional commit types
• Build and publish docker images
• Build and publish Helm charts

The actions inventory for LinkORB can be found at github.com/linkorb/github-actions-examples.

Centralized repository configuration

To assist with consistency across repositories, LinkORB uses Ansible automation in our repo-ansible repository to:

• Maintain and apply a single-source-of-truth for standard repository auxiliary files and configuration.
• Assist with evaluating repositories for adherence to centralized standards

The repo-ansible README provides usage instructions, but as mentioned above provides a configurable playbook to apply auxiliary file templates for GitHub actions/workflows, software licenses, Docker and devcontainer files, reviewdog, and much more.

Key auxiliary files

Supporting files like README.md, LICENSE, and CHANGELOG.md are critical for keeping your repository informative and easy to use. These files however are just a small sample of the required and optional auxiliary files found in LinkORB repositories.

Unless otherwise specified, the following files or directories should be stored on the project root.

README

A README contains information to help users and developers understand what the project is, how it works, and how to get started with it.

The README file should be named in all caps and be of type Markdown (file extension .md).

All LinkORB README files should terminate with the following:

## Brought to you by the LinkORB Engineering team

<img src="http://www.linkorb.com/d/meta/tier1/images/linkorbengineering-logo.png" width="200px" /><br />
Check out our other projects at [linkorb.com/engineering](http://www.linkorb.com/engineering).

Btw, we're [hiring](https://engineering.linkorb.com/jobs/)!

LICENSE

A LICENSE file must be included in all open source, public repositories. Unless otherwise specified, open source LinkORB repositories should be licensed under the MIT License.

The license file should be named LICENSE in all caps and have no terminating file type.

CHANGELOG

A CHANGELOG file’s purpose is to provide an easily readable and accessible history of changes to the software project, such as bug fixes, new features, and other updates. This file serves as a communication tool for the software development team, and users to understand how the project has evolved from one version to the next. Within this file, you can establish and maintain software versions in accordance with the Semantic Versioning standard.

The CHANGELOG file should be named in all caps and be of type Markdown (file extension .md).

.gitignore

The .gitignore file is used to instruct Git which files and directories to ignore when tracking changes in a project. This file is typically used to exclude files that are not intended to be tracked, such as temporary files, or sensitive information.

.env.yaml

Environment variable configuration settings for production and pre-production are stored in the .env.yaml file in YAML format. It provides information on how to set them, and describes the type (string, url, number) along with the default and sample values for each.

It usually contains a list of key-value pairs, where the keys represent the names of the environment variables and the values represent their corresponding values. You can learn more at github.com/linkorb/envoi.

CODEOWNERS

This file specifies the GitHub usernames or the team names for those responsible for reviewing and approving changes to particular files or folders in the repository. When changes are suggested to those files or directories, code review tools use the CODEOWNERS file to automatically request review from the appropriate persons or teams.

The CODEOWNERS file should be named in all caps have no terminating file type.

.editorconfig

The .editorconfig file assists in keeping code styles consistent across different editors and IDEs. It includes a set of rules to be followed by text editors and other tools while editing and formatting source code files.

The .editorconfig file should be named in all lowercase and, as shown, preceded with a .. As such, it is it’s own filetype.

repo.yaml

The repo.yaml is a structured data file used to store metadata about a GitHub repository. It can be readily scanned and processed to offer an aggregated view of the repository and its characteristics.

Examples of metadata found in a repo.yaml file include:

• Status: If repos are actively used in prod, prototyping, or deprecated.
• License: The license under which the software is distributed and used.
• Ownership and subject matter experts.
• Date of the most recent penetration test.
• Key routes and URLs for application health checks.

SECURITY

The SECURITY file provides guidelines for reporting vulnerabilities or security issues that contributors, maintainers, or users discover while using a project.

The file consists of the following information:

• how to report an issue
• what information to give when reporting an issue
• the security practices followed by LinkORB
• a disclosure notice

The SECURITY file should be named in all caps and be of type Markdown (file extension .md).

/docs

A docs directory at the project root contains Markdown files that support or extend information provided in the README.

OPS

Contained in the docs/ directory, an OPS.md file is used to provide application administration, support, and maintenance information such as:

• A high-level explanation of the application architecture and logic
• Related applications, services, and APIs either upstream or downstream of the application
• Endpoints for application status and health checks
• Location and access instructions for application event logs and reporting
• Common administration, maintenance, support, and troubleshooting steps and resources

Auxiliary file templates and examples

As mentioned above, templates for several of these files can be configured using repo-ansible. Additionally, active examples can be found in the demo-symfony-app repository.

Security standards

It’s important that security standards are implemented to ensure the security and integrity of the codebase. These guidelines help in protecting the repository from unauthorized access, data breaches, and other security concerns.

• Ensure that no genuine credentials, such as names or API keys, are used in or committed to the git repo.
• Implement a code review process to ensure that all changes to the repository are thoroughly reviewed for security vulnerabilities and best practices.
• Make sure that the repository and its contents are only accessible to authorized individuals or teams.
• Monitor and manage third-party dependencies to ensure that they are up-to-date and free from known vulnerabilities.

To guarantee the overall security of the software and its repository, it is critical that all contributors and users of the repository are aware of and follow these standards.