Disclaimer: The following information is meant to serve as a reference to the expected format, fields, and parameters of a theme's readme.txt for a successful review to be complete. Not all information provided below is currently a requirement, but it provides a solid foundation moving forward to allow Theme Sniffer to parse and validate a theme's readme.txt file.
This must be the the very first line of your readme.txt file.
The format for the theme's name should be:
A single space surrounding the theme's name.
││
┌────┴┴────┐
│ │
=== Theme Name ===
│││ │││
│││ │││
└┴┴─────┬┬─────┴┴┘
││
Three equals signs at the beginning and end of the theme's name.
Immediately following the theme's name on a newline are fields, some fields are required while others are optional. Fields are required to follow the following specifications:
The field WP: The content for the field.
│ ││ │││││ └ No trailing whitespace following content.
│ ││ │││││
│ ││ ││││└─ The content for the field.
│ ││ ││││
│ ││ │││└─ A single space follows the colon.
│ ││ │││
│ ││ ││└─ A single colon follows the field.
│ ││ ││
│ ││ └┴─ Each letter in an initialism should always be uppercased.
│ ││
│ │└─ Preceding words after the first should only be lowercased.
│ │
│ └─ Multiple words are seperated by a single space.
│
└─ The first word should be capitalized.
The following fields are required for entry into the WordPress.org theme repository:
- Tags: This is a list of applicable tags for your theme delimited by a comma followed immediately by a single space. The guidelines for the allowed tags can be found in the handbook for required theme tags. The tags used in your readme must match the tags used in your
style.cssfile. - License: This must be a valid SPDX identifier or name representing the license of your theme. This license is required to be compatible with GNU General Public License v2.0 or later.
- **License URI: The URL to the license's matching spdx.org license text, or other valid URLs listed under SPDX specifications.
- Requires at least: The minimum required version of WordPress core your theme is compatible with.
- Requires WP: An alias for the __Requires at least** field.
- Tested up to: The highest version of WordPress core you have tested your theme against.
- Requires PHP: The minimum required PHP version for this theme to run and function as intended, without any warnings or fatals.
The following fields can optionally be added to your readme.txt, but are not required for the review or acceptance of a theme. If these fields are used, they must adhere to the guidlines outlined for each:
- Contributors: This should be a list of wordpress.org userid's that have contributed to the development of your theme.
- Stable tag: The tag that is marked as being the stable release for your theme. If no stable tag is found trunk will be used by default.
Note: Following suit with the Tested up to field found in plugin readme.txts, the Tested up to field in a theme ignores the patch version, as a patch version increment shouldn't cause any backwards compatibility issues. This means you only need to define the major and minor version it is tested against and the WordPress.org theme directory will automatically add the patch versions for you. This should be numbers only, so 5.1 and not WP 5.1 or v5.1. The Requires at least and Tested up to fields are used for compatibility checking with WordPress core. If a theme sets the required version to 5.0, then users on versions below 5.0 will not receive update notifications. Use this wisely.
After the fields in readme.txt there should be a single empty line, which then can be followed by an optional short description. Short descriptions should be no more than 150 characters. Anything over this will not be displayed. If no short description is provided, a description will be parsed from the primary Description section of the readme.txt.
This is an example of how a short description should follow your required and optional fields:
License: GPLv2 or later
License URI: http://www.gnu.org/licenses/gpl-2.0.html
Short description for my new theme that is less than 150 characters.
Sections are where the bulk of your readme.txt's content lives. Sections should follow preceding components with a single empty line to give a clear visual break in the content's hierarchy.
All section names should follow this format:
A single space surrounding the section name.
││
┌─────┴┴─────┐
│ │
== Section Name ==
││ ││
││ ││
└┴──────┬┬──────┴┘
││
Two equals signs at the beginning and end of the section name.
Following the short description, the first section of a theme's readme.txt should be the description. This area contains an extended description of your theme that can exceed the 150 word character limit for the short description.
The readmes use a customized version of Markdown. Most Markdown calls work as expected.
A popular use for Markdown in your readme.txt is to create links. Just write like this to link a word to a URL:
[WordPress](http://wordpress.org)
Videos can be put into your readme.txt too. A YouTube or Vimeo link on a line by itself will be auto-embedded. It’s also possible to embed videos hosted on VideoPress using the wpvideo shortcode.
Resources are the assets found within your theme. This includes (but is not limited to) any and all fonts, images, videos, stylesheets, PHP code, JS, ect. Anything that is bundled within your theme, that you did not write or make. The resources are used to ensure proper attribution is provided to the authors of the content, and to help identify any licensing conflicts.
Resources should be on one line, and begin with a * . They consist of 4 parts, which should be delimited with a comma and a single space.
- The path from the diretory containing your
readme.txtto the resource file as used in your theme.
I copy and paste the code from normalize.css in my style.css stylesheet for a theme called "my-theme". The path to the resource would be: style.css. This helps other users identify where the resource was used, and helps make the theme review process smoother when validating a theme that's submitted.
Adding this information to our readme, our resources section would look like this so far:
== Resources ==
* style.css
- The resource's name and version.
Building off of the above example - we know the resource is called normalize.css. Normally a resource's name is the same as the repository's name. If the respository has a different name assigned, typically it would be found in their readme file. For normalize.css, we should check which version we are using. I can see in the stylesheet,normalize.css, v8.0.1, but in the repo itself, I see the actual version number that's used is 8.0.1 and the v prefix was dropped.
It's common for dependencies to have or not have the v, and the best practice for license documentation standards is to use the matching tag version verbatim. Doing so makes it easy for others who extend or reuse your work to find exact documentation, issues, tickets, reference, and many other things for a given resource.
For this example, the matching tag is 8.0.1, so following best practices, my resource's documentation now looks like this:
== Resources ==
* style.css, normalize.css 8.0.1
- The resource's copyright notice exactly as it appears in it's license file.
IMPORTANT: Not every license file includes copyright information directly inside. Every license can be a little different, but the license always will provide explicit instructions on how to implement the copyright notice information if it's not displayed directly inline. For example GPLv2.
We would obtain the copyright notice information from the license file of the normalize.css repository or directory of files we downloaded for the resource. You might have noticed at the very top of normalize.css is an attribution line. While this information is adequate for distribution since the MIT license explicitly states that every file included in your distribution must provide this information, it might not always be the format that is expected for resource documentation in your readme.txt. Building off the requirements and this example, our normalize.css resource documentation would now look like this:
== Resources ==
* style.css, normalize.css 8.0.1, Copyright © Nicolas Gallagher and Jonathan Neal
- The URI for obtaining the resource.
Example: Typically the URI for a resource is going to be a URL. The URI should be where an end user can obtain the resource, and/or find official documentation for a resource. Usually this is the resource's repository URL. However, it can be an alternative website specified by the author of the resource. Alternative websites are often encountered when using packages installed through package managers like composer or yarn, and are set explicitly by the author for reference as the official website for the resource. This is not necessary for you to determine especially when it comes to the longevity of a resource that might phased out, shut down a privately owned/hosted website, or no longer actively has interest in a project.
While alternative websites are considered fine to use, the best practice for license documentation standards is to provide the URL to the primary repository for a resource where issues are handled or linked to, and active development occurs/occurred.
Following the best practices, we will include the URL for the github repository:
== Resources ==
* style.css, normalize.css 8.0.1, Copyright © Nicolas Gallagher and Jonathan Neal, https://github.com/necolas/normalize.css
- The SPDX license identifier or full name for the resource's license.
The last part of our resource documentation will be the standardized full name or identifier for the license the resource uses. In our case, the project's license file indicated that it uses the The MIT License (MIT). The notation can be verified from the list in license names and identifiers. @TODO
To wrap up our resource documentation for normalize.css, and pass the theme-sniff validation for readme.txt, our resource's documentation would be:
== Resources ==
* style.css, normalize.css 8.0.1, Copyright © Nicolas Gallagher and Jonathan Neal, https://github.com/necolas/normalize.css, MIT
Some important things to keep in mind when adding a new resource:
-
The resource should be compatible with your license. If you release your theme as
GPL-2.0-or-later, then the resources bundled in your theme must be compatible with that license as this is software that is being distributed and potentially code reused by others. -
The resource should always include the correct version number when applicable to the resource. Take for example the popular icon pack, FontAwesome.
- FontAwesome v1.0.0
This was released under Creative Commons Attribution 3.0 Unported ( CC-BY-3.0 ). This license is not compatible with GPL-2.0-or-later, so this version of FontAwesome could not be used in a theme!
- FontAwesome v4.7.0
Later on down the road v4.7.0 came out, and if we look at the license - we see that the licensing was modified to include the font under SIL OFL1.1, the css/less/sass files under MIT, and the documentation licensed under CC-BY-3.0. This is compatible with GPL-2.0-or-later tag, so a theme could bundle the Font, and CSS/LESS/Sass files with the theme, just not the documentation.
- FontAwesome5.7.2
Fast forward ahead, and we have 5.7.2.
This version had more licensing changes, and seperated out icons into their own license with a CC BY 4.0 license, and code/fonts remained the same as in v4.7.0 above.
Also take note that this version number no longer contains a prefix of v before the numbers. A version of 5.7.2 is not the same as a version of v5.7.2. Some software will attempt to normalize a prefix of v as it just stands for "version" - but when referencing license information in your readme it is important to copy the exact version number you are including/bundling, and update that information as your update your dependencies.
- The license must remain intact for all resources you include in your theme.
We can use FontAwesome as an example again. With FontAwesome 5.7.2 they mention in their README that they also include attribution and license information inline, so if you use the "Download Font Awesome" feature, then you don't have to worry about additional steps aside from your own documentation and reference in the readme.txt.
If you had a build process that bundles and minifies things, there's a possibility this attribution is stripped out. Most modern minifiers/compilers like Google's closure library, or uglify do have built in measures for keeping license/attribution intact. They do have options to disable this feature for software that scans the dependency tree and generates a liscense list and disclaimer file, so it's important to ensure this is disabled by plugins you may use for a build process, and know what those things do.
When you use modern tools like webpack or the likes to create a bundle, yes this can make you have a small distributable in the end, but often time developers remove the REQUIRED license information. Either stripping out the license details included inline on files, or just simply only moving files matching a glob pattern like *{.js,.css}. By doing this you're skipping over the actual license file which MUST be distributed with the resource.
There are other tools to concactenate licenses into a single license file, but it's also important to note you can't do things like combining multiple names on a single license to reduce the size of the file. Some packages, such as the popular Lodash javascript library, will combine all the license disclaimers for subcomponents into a single license file. If you used 3 or 4 components from lodash, they would automatically concact into a single license file mentioning just the components you used. This is especially handy when using tools like yarn to handle licenses for your dependencies by running yarn licenses generate-disclaimer --prod.
When using outside resources that you bundle or include in your theme, it's always important to include the original license for those resources. Many of the licenses have explicit instructions that require you to do so in order to stay compliant, and thus hold true to your intended license, and other project that may want to rely on your work in the future. Many compilers and build tools have additional tools in place for this process, along with tools running OSS compliancy scans for resources. When doing things by "hand", it's your responsibility to make sure that your project doesn't infringe upon the copyright and license requirements set forth in code that others allowed you to use. Keeping that in mind - you'd expect the same for the software you are about to distribute. If someone were to take your theme, styles, customizer controls, frontend scripts, templates, or any peice of code you spent a lot of time and hard work on - you'd want to be acknowledged for that. This remains even more true with more modular aspects of your code. This is why many licenses require you to include a copyright notice in every file that you include for distribution as any of the code you've created should hold proper attribution and license information for any one who were to use it in the future in their projects.