equinix-labs

Standards for experimental and labs projects by Equinix teams.

View the Project on GitHub equinix-labs/equinix-labs

Glossary

CI/CD

In software engineering, CI/CD or CICD generally refers to the combined practices of continuous integration and either continuous delivery or continuous deployment. CI/CD bridges the gaps between development and operation activities and teams by enforcing automation in building, testing and deployment of applications. Modern day DevOps practices involve continuous development, continuous testing, continuous integration, continuous deployment and continuous monitoring of software applications throughout its development life cycle. The CI/CD practice or CI/CD pipeline forms the backbone of modern day DevOps operations.

Code of Conduct

This may be included in the body of README or in separate files for other providers of the project type. These are generally sensible. If the same Code exists in another Equinix Metal owned project, it can be assumed to be approved.

Contributors Guide

Contributing notes may be included in README.md or in a separate CONTRIBUTING.md. Expectations around licensing, copyright, and what to expect when contributing to this project should be covered. Tips on what linters and tests are run should be provided so that users can perform these locally. These may differ from project to project, even among common programming languages, based on the ecosystem of the project.

Developer Certificate of Origin

Developer Certificate of Origin provides basic accountability for the code being submitted to the project.

Getting Started Tutorial

May be included in the README.md and needs to include:

LICENSE

Every OSS project should include an approved OSS license. Observe instructions in the license file about copyright notices. When forking, honor (do not strip) copyright notices. The licenses may stipulate when and how additional copyrights should be applied. Copyright notices should be assigned to “Equinix Metal”, not the individuals working on the project.

Maintainer

An organization owner can promote any member of the organization to team maintainer for a team, giving them a subset of privileges available to organization owners.

Manifest File

While the specific filename varies from programming environment or packaging tool, manifest files contain “meta” information about a project. Take advantage of manifest files to store the appropriate set of categories, keywords, and tags for a project. Project descriptions and overviews should be taken advantage of as well. Logos are a common feature of manifests, projects should use approved logos and branding to fit the project and organization’s visual requirements and theme.

CODEOWNERS

Repository owners are the last line of defense when no other maintainers have responded to an issue or pull request after a certain amount of time. These people follow up with the relevant maintainers of a repository to move forward on a feature or bug.

GitHub offers a filesystem tiered format for defining the owners of specific folders and files as well as generic catch-all owners. Find out more at About Code Owners.

OWNERS.md

This file defines governance and should be used to identify the maintainers of the project (people before organizations) and how the direction of the project is controlled. A project that has been given to the community should have clear governance otherwise the project risks favoring the original contributors and being perceived as such. Equinix Metal projects should have at least two owners.

README.md

Readme files pertain to the contents of a directory or the scope of a repository. They should not be used as a substitute for end-user documentation or end-user guides. Some end-users will experience the application without ever seeing the README file contained within the repository, others will contribute to an application without the need for guidance on performing routine or complex tasks. It is therefore important to make documentation available for the correct audience and transition users to more advanced or more approachable content.README.md files should strive to include the following sections:

RELEASE.md

Release knowledge is often lost when not recorded properly. A RELEASE.md could be used to record this information - consider automation like release-drafter/release-drafter. How is the software built for distribution? How many channels, architectures, artifacts are there? How and where are tags applied? Are tags referenced and tracked in multiple places - Git, docs, config files, Docker images? What commands are needed to run the release? What responsibilities do humans have and what responsibilities do robots have? What changelogs or documentation should be updated on release?

SUPPORT.md

SUPPORT.md files will appear when users create issues on projects. Support between OSS projects should not vary wildly. Some projects will be community supported and we should offer links to the appropriate email address, forum, or slack channel, while others may actually be supported by Equinix Metal support.