Releasing and versioning Gatsby themes

Releasing themes works precisely the same way as releasing a plugin (see Section 9), so I won’t repeat the instructions to publish to the Gatsby Plugin Library and the NPM package registry in this section. Because themes, like plugins, are typically intended for use by other Gatsby developers rather than strictly for private use, the same best practices in terms of semantic versioning also apply.

Gatsby outlines several best practices for semantic versioning in themes that account for various changes you may need to make as you evolve your theme, such as removing queries that certain sites may depend on. As we saw in the previous section, in semantic versioning there are three types of releases. These are summarized here with information relevant for themes:

• Patch (0.0.x) releases are bug fixes that are backward-compatible, so no breaking changes are made. Public APIs should remain unaffected. For themes, a patch release might entail fixing a bug in a component, adding error handling or default values, or upgrading upstream dependencies to their latest minor and patch versions.
• Minor (0.x.0) releases introduce new features that remain backward-compatible, so no changes break existing theme users’ sites. In minor versions, existing public APIs should remain unaffected. For themes, a minor release might entail adding new pages or queries, adding new theme configuration options, rendering additional data, adding new props to a component, or adding a new MDX shortcode.
• Major (x.0.0) releases include any new bug fixes or features that are not backward-compatible, meaning these changes will break Gatsby sites using the theme. In major version releases, a migration path or guide should be provided in order to upgrade the theme to the latest version. For themes, a major version release might include changing a filename (which requires updates to any files that shadow that file), removing or modifying props accepted by a component, modifying queries, removing theme configuration options or modifying how they work, removing attributes in schema definitions, removing default data, or changing plugins or plugin configuration.

NOTE

For a more detailed overview of semantic versioning in Gatsby themes, consult the semantic versioning section of the guide to Gatsby theme conventions and Semantic Versioning 2.0.0.