Releasing Code

Naming #naming back to top

Avoid name conflicts if at all possible. Check for open source projects with a similar name. Make sure that the name doesn’t infringe upon any trademarks. Do a Google search for your project name to ensure that something else doesn’t appear in the search results that might negatively reflect on your project.

Aim for conceptual clarity over cleverness and puns. Creativity is good, but a name that also clearly explains or at least suggests what the software being released actually does is better.

Licensing #licensing back to top

At 10up, any project that is a WordPress plugin or theme should be licensed GPLv2. Standalone JavaScript libraries or modules can be licensed MIT. We recommend this route as a default, but any other included libraries and integrations must also be taken into consideration before making a final licensing decision.

Client permissions #client-permissions back to top

Open-sourcing code that has been developed as part of a client project can be complex. Many agency contracts (including many at 10up) define the work product as “work for hire” and grant copyright over the code produced to the client. In those cases, specific permission from the client is required in order to release any code developed on the projects governed by that contract.

That said, clients benefit as much as anyone (perhaps even more than anyone) when functionality developed as a part of their project can be released into open source or contributed back to the projects which it extends or builds upon. They get the benefit of ongoing community contribution, testing, and maintenance, and don’t have to shoulder the maintenance of that new plugin or feature themselves.

If you have identified code developed as part of a client project that would make an ideal contribution to an existing open source project or an open source release of its own, work with your account manager to specifically identify the need for and obtain client permission.

In order to be publicly open sourced, all new WordPress plugins should have Gutenberg support and must conform with the WCAG 2.0 guidelines at level AA.

Choosing tools #choosing-tools back to top

Repository hosting and issue management are separate considerations, but for convenience and familiarity we host and manage open source code on GitHub and are active participants in their maintainer community. WordPress plugins are generally also mirrored onto the SVN-backed WordPress.org Plugin Repository, where support requests are monitored and turned into GitHub issues where applicable.

GitHub’s strength and weakness is that it is very code and solution-focused. There are times where more specialized tools are necessary for including disciplines such as design; these are chosen based on needs and participants. Many of the following sections contain GitHub-specific guidance but are still broadly applicable to other tools for project and code management.

Accessibility #accessibility back to top

All newly released code should adhere to the WCAG 2.0 AA level with the goal of working through existing code as time allows to bring it up to WCAG 2.0 AA levels. Utilize checklists and linters to help ensure code released and updated adheres to these standards.

Security #security back to top

GitHub added support for security alerts in November 2017 and automated security fixes in May 2019. Both of these add up to additional help ensuring that your code is secure, so properly list the packages that your repository depends on and enable automated security fixes in your repository. If you have a private repository, then you’ll also need to allow GitHub read-only access, to enable the dependency graph, and to enable security alerts. Finally, make sure to pay attention to your security alerts and work to build a release with those updates as reasonably expeditiously as possible.

This means that we’ll want the following GitHub settings:

Release Process #release-process back to top

All releases should follow one of two release processes we’ve crafted (see Ads.txt and Distributor) or even more simply, leverage a GitHub Action to automate the release and deploy to WordPress.org as necessary (see Restricted Site Access). If this is a major release, we should consider publishing an update post on 10up.com/blog and updating any related microsites.

Once a release has been tagged on GitHub, include the link to the release tag in the related milestone, ensure the milestone date is accurate, move any remaining open issues or PRs from the milestone to a future milestone, remove any closed but unmerged PRs from the milestone, and then close the milestone.

Changelog #changelog back to top

We will maintain a changelog in its own CHANGELOG.md file, linked from the README.md file, follows the Keep a Changelog standard, and adheres to Semantic Versioning as described in the 10up Engineering Best Practices. See Restricted Site Access and Simple Local Avatars as an example. When building a changelog for a release, append any props to properly credit individuals who contributed to each item (see ClassifAI example).

Team and Credit Management #credit-management back to top

We should add a CREDITS.md file that lists maintainers, contributors (in chronological order of contribution), and optionally any libraries utilized by the plugin/tool (example: Insert Special Characters). While the concept of the All Contributors spec is nice, the implementation and layout can get a bit complex and none of our plugins/tools have a large enough contribution audience to warrant the broad contribution types / emoji key used in the spec. As such, the CREDITS.md file should be linked from the README.md file and should be laid out like this:

The following acknowledges the Maintainers for this repository, those who have Contributed to this repository (via bug reports, code, design, ideas, project management, translation, testing, etc.), and any Libraries utilized.

## Maintainers

The following individuals are responsible for curating the list of issues, responding to pull requests, and ensuring regular releases happen.

[Display Name](GitHub profile link), [Display Name2](GitHub profile link2), … , [Display NameN](GitHub profile linkN).

## Contributors

Thank you to all the people who have already contributed to this repository via .

[Display Name](GitHub profile link), [Display Name2](GitHub profile link2), … , [Display NameN](GitHub profile linkN).

## Libraries

The following software libraries are utilized in this repository.

[Library Name](library link), [Library Name2](library link2), … , [Library NameN](library linkN).