Maintaining Plugins
Maintaining a plugin for the long haul can be difficult work. Open source maintenance is often a thankless job that is poorly compensated, if at all. Nonetheless, long-term maintenance is a core responsibility of plugin authors. Once the development work is complete, it’s time to consider how to handle issues like security vulnerabilities, semantic versioning, and dependency updates that don’t break Gatsby sites.
Handling plugin patches and improvements
Gatsby, like many other JavaScript ecosystems, recommends semantic versioning to manage your releases. Though a full overview of semantic versioning is well outside the scope of this book, it’s best to adhere to some best practices. The first public release of a plugin is often assigned version 0.1.0 or 1.0.0, the latter of which is generally reserved for the first stable release of a package.
When bugs are fixed or minor issues resolved, that generally results in a patch release (from 0.1.0 to 0.1.1 or 1.0.0 to 1.0.1). If you’ve added or modified features in the plugin, that is broadly considered grounds for a minor release (from 0.1.0 to 0.2.0 or 1.0.0 to 1.1.0). Finally, major releases are reserved for changes that break the API or disrupt backward compatibility.
Tip
For more information about semantic versioning, consult Semantic Versioning 2.0.0.
Writing a README and documentation
The README file in your plugin repository should also be very clear about major version releases so your plugin users don’t get confused. If you lack a separate documentation site, the README is your primary opportunity to give plugin users the rationales for changes to your plugin, working examples, and an account of how major version releases evolve the project.
Gatsby recommends performing spring cleaning of your plugin repository every so often to clear out older versions that are no longer needed. In the vast majority of cases, only the last few versions are required.
Managing dependency versions
The Gatsby documentation recommends two distinct tools for verifying and managing dependency versions. In JavaScript ecosystems, dependency management can be particularly difficult, but projects like Version Lens for Visual Studio Code and the npm-check-updates
command-line interface offer useful introspection and automated management capabilities.
While Version Lens provides a tool to update dependencies directly from within your package.json file in your development tool, namely by displaying the latest version number available for a given package, using npm-check-updates
offers a more active means of determining if any dependencies are obsolete. To use npm-check-updates
, install the package and then execute the ncu
command:
$
npm
install
-g
npm-check-updates
$
ncu
-u
Remember that the primary motivation for releasing a plugin to the community is to benefit those users in the community who need it. As such, it may also be a good idea to provide user support and example codebases for potential users. Gatsby, for instance, uses Discord as its primary conduit for community support. The more resources you have available for your users, the more likely they are to adopt your plugin and perhaps even contribute to it on their own time.
Note
For more information about dependency version management, consult the Version Lens documentation and npm-check-updates
documentation, respectively.