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 type: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 trunk 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 trunk 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 trunk 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.

If you go the GitHub Pages route, which is our default preference, you should:

In this way, merging a feature or development branch that contains new/updated code will simultaneously update the documentation to match the new code.

Our Distributor project recently added a GitHub Action to automatically build hook documentation to GitHub Pages based on JSDoc-formatted docblocks within the code (see resulting hook doc site for Distributor). 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.

Coding standards #coding-standards back to top

All WordPress plugin-related projects should adhere to WordPress Coding Standards (WPCS), like WordPress core, and WordPress VIP Coding Standards (VIPCS). Using our WPCS GitHub Action across all repos and making sure all Pull Requests are required for this check to pass before merging will ensure that all code output matches community agreed upon expectations. Non-WordPress plugin projects should attempt to use a community standard for coding standards where they exist and ideally as part of a GitHub Action to act as a check on all Pull Requests.

In addition to PHP, we should keep JS/TS code following standards. For Open Source plugins, it’s recommended to use eslint and @wordpress/eslint-plugin:

#.eslintrc
{
	"extends": [ "plugin:@wordpress/eslint-plugin/recommended" ]
}

Using GitHub Actions is recommended to ensure the changes follow the project’s coding standards. To fit with various setup and requirements, we generate the linting JSON report and use ataylorme/eslint-annotate-action to highlight all errors and warnings with annotations.

Block for Apple Maps is a great example of using GitHub Actions to check both PHP and JS/TS code.

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.

Already doing all this?
Careers at 10up

Open source, MIT licensed.
Copyright 2024 @10up.