GitHub Process

The following items are required across all repositories managed by our Open Source Practice team. By keeping the same experience across all our repositories, it makes it easier for 10uppers and external contributors to work within any repository and operate with the same assumptions as any other 10up repository.

Issue and PR labels #issue-pr-labels back to top

The following labels will our standard set of labels across all open source repositories to help ensure we use clear and consistent labelling terminology. This will allow us to see the status and type of all issues at a glance, to help track and report on contributions across our repositories, and to provide easier ways to find issues to contribute to (e.g., all needs:ux and good-first-issues). We’re starting a minimal set of labels and will let progressive enhancement further define them for us as well as perform occasional housekeeping.

Milestones #milestones back to top

We are also adding the following set of milestones across our open source repositories to help give some clarity to the priority of our work (e.g., numbered milestone has priority, Future Release has low priority). When it comes to using numbered milestones (e.g., 1.3.7), we follow the Semantic Versioning as noted in the 10up Engineering Best Practices.

Branching, Merging, and Deploying #branching-merging-deploying back to top

Each repository should have a master and develop branch with develop being the default branch. Branching and Deploying should follow the processes outlined in the Engineering Best Practices for plugins. Similarly, we should protect the master branch as outlined in the Engineering Best Practices. Merges should be handled as non-fast-forwards merges as outlined in the Engineering Best Practices and not squash merges so that the master branch maintains full commit and code author history, this is done for transparency and to honor all contributions to our open source work. This means that we’ll want the following GitHub settings:

Documentation #documentation back to top

Maintain documentation in the same repository as much as possible. This keeps everything portable and usable even when offline. There are two main varieties of documentation typically associated with open source software: usage instructions and maintenance guidelines. Most of this section focuses on maintenance guidelines to support the process you’ve outlined, as usage instructions will vary widely between projects.

Depending on the amount of documentation associated with your projects usage instructions, you may find that hosting them as a separate view, such as GitHub Pages or a GitHub wiki, is preferable to markdown files in a /docs/ subfolder. Note that if you go the GitHub Pages route, that you’ll want to consider a gh-pages branch that deploys to your GitHub Pages site.

Our Distributor project recently added a GitHub Action, some JSON config files, and JSDoc-formatted docblocks to automatically build hook documentation to GitHub Pages. Where feasible, we should look to replicate that process to generate WordPress plugin or theme hook documentation across other projects to improve our level of technical documentation.

Support Levels #support-levels back to top

The intended support level for each repository should be determined (i.e., Beta, Active, Stable, Archived) and then noted within the GitHub repository and, where applicable, within the WordPress.org repository to clearly state our intentions. The following are recommended GitHub badges and section copy for the README.md file as well as pinned posts within the WordPress.org support forums.

Beta

For repositories determined to be under Beta support, the following GitHub badge should be added at the top of the README.md file:

[![Support Level](https://img.shields.io/badge/support-beta-blueviolet.svg)](#support-level)

…and the following section should be added within the README.md file:

## Support Level

**Beta:** This project is quite new and we're not sure what our ongoing support level for this will be. Bug reports, feature requests, questions, and pull requests are welcome. If you like this project please let us know, but be cautious using this in a Production environment!

Active

For repositories determined to be under Active support, the following GitHub badge should be added at the top of the README.md file:

[![Support Level](https://img.shields.io/badge/support-active-green.svg)](#support-level)

…and the following section should be added within the README.md file:

## Support Level

**Active:** 10up is actively working on this, and we expect to continue work for the foreseeable future including keeping tested up to the most recent version of WordPress. Bug reports, feature requests, questions, and pull requests are welcome.

Stable

For repositories determined to be under Stable support, the following GitHub badge should be added at the top of the README.md file:

[![Support Level](https://img.shields.io/badge/support-stable-blue.svg)](#support-level)

…and the following section should be added within the README.md file:

## Support Level

**Stable:** 10up is not planning to develop any new features for this, but will still respond to bug reports and security concerns. We welcome PRs, but any that include new features should be small and easy to integrate and should not include breaking changes. We otherwise intend to keep this tested up to the most recent version of WordPress.

Archived

For repositories determined to be under Archived support, the following GitHub badge should be added at the top of the README.md file:

[![Support Level](https://img.shields.io/badge/support-archived-red.svg)](#support-level)

…and the following section should be added within the README.md file:

## Support Level

**Archived:** This project is no longer maintained by 10up. We are no longer responding to Issues or Pull Requests unless they relate to security concerns. We encourage interested developers to fork this project and make it their own!

WordPress.org Support Forum

For projects that extend to WordPress.org, the following pinned post should be added to its Support Fourm:

OpenGraph image #opengraph-image back to top

Ensure that an appropriately sized OpenGraph image is created and uploaded for the repository to ensure social shares best highlight our tools/plugins visually in social streams.

Dependency management #dependency-management back to top

All repositories will leverage GitHub’s built-in security fixes feature (currently in beta) to help automate dependency management so that we are alerted as dependencies update, receive a pull request with dependency updates, and see whether dependency updates pass our automated testing or otherwise requiref further code changes before updating.

Code coverage #code-coverage back to top

Every feature should be accompanied with tests and all pull requests should come with associated tests, all living within the tests directory. While we have no intention of striving for 100% code coverage, we should aim for above 80% with above 90% being the ideal. We should also look to utilize a code coverage / automated code review tool like Coveralls, Code Climate, or Codecov and ensure that is a pull request requirement before merging.

Coding standards #coding-standards back to top

Like WordPress core, we should adhere to WPCS (or 10up ruleset) and WPCS VIP 2.0 and ensure that this is a pull request requirement before merging.

Continuous integration #continuous-integration back to top

Coming soon: GitHub Actions and Travis configurations

Changes to our projects should not cause issue with the two most recent major versions of WordPress and the lowest supported version of PHP and above. Our CI pipelines should be testing for and alerting for any changes that do run afoul of this approach.