From 9b2d51b50fc2187138bf2ab3c94571db6fa1b580 Mon Sep 17 00:00:00 2001 From: Obinna Ekwuno Date: Wed, 19 Feb 2020 18:09:01 +0100 Subject: [PATCH] chore (doc): maintaining a plugin guide. (#21221) * Started work on Maintaining plugin stub * Corrected Comments that were casuing .md file form showiing in preview * added Handling patches and improvments, Updating Readme and use case sections * aAdded Tooling and dependency improvements section * updated doc to fit style guide. * Updated PR with correction from Kyle G. * Updated PR with review * Updated PR with review * Updated PR with reviews * update doc with review and remove asterisk from doc-liink yaml * add reviews from Laurie * Update * update maintianing Plugin PR with reviews from Marcy Co-authored-by: GatsbyJS Bot --- docs/docs/maintaining-a-plugin.md | 59 ++++++++++++++++++++++++++-- www/src/data/sidebars/doc-links.yaml | 2 +- 2 files changed, 56 insertions(+), 5 deletions(-) diff --git a/docs/docs/maintaining-a-plugin.md b/docs/docs/maintaining-a-plugin.md index bb05a9dcfc729..cbd2790191835 100644 --- a/docs/docs/maintaining-a-plugin.md +++ b/docs/docs/maintaining-a-plugin.md @@ -1,10 +1,61 @@ --- title: Maintaining a Plugin -issue: https://github.com/gatsbyjs/gatsby/issues/21067 --- -This is a stub article meant to be filled with tips on how to maintain a Gatsby plugin once you've published it as an npm package. +The Gatsby community thrives on the power of plugins. You often find that there is a plugin for almost everything ranging from source plugins to transformer plugins. A useful way of understanding the purpose of a plugin at a glance is by its name. Check out the [guide to naming conventions for plugins](/docs/naming-a-plugin/) to learn more. -Topics to be covered: +> Wondering how to [create a plugin](/docs/creating-plugins)? Look no further. Start contributing. -- yarn workspaces can solve yarn link inconsistencies +## What is a plugin? + +Gatsby plugins are Node.js packages that implement Gatsby APIs. To learn more take a look at the [plugin documentation](/docs/plugins/). + +In creating plugins, the bulk of the work is during the development phase. However, there’s still a need to take a look at the dependencies and security features from time to time. Keeping plugins up to date can become really tasking and it is important to be careful when updating dependencies, seeing as this could potentially break users' apps. + +However, the consequences of not updating and maintaining a plugin can introduce security issues to your users. The following are some recommendations for maintaining plugins: + +## Handling patches and improvements + +Most plugins generally follow [Semantic Versioning](https://semver.org/) to determine how many releases to do and the type of releases. + +The first public release of a plugin is 0.1.0 or 1.0.0. From there, bugs are fixed in patch releases (e.g. 0.1.1) and features are added or changed in minor releases (e.g. 0.2.0). + +Version 1.0.0 should be released when the plugin's API is considered stable. Version 2.0.0 (and subsequent major releases) would introduce breaking API changes. + +> Consider a version format of X.Y.Z (Major.Minor.Patch). Bug fixes not affecting the API increment the patch version, backwards compatible API additions/changes increment the minor version, and backwards incompatible API changes increment the major version. + +Read more about this concept [in this paper on semantic versioning ](https://semver.org/). + +## Update README and document use cases + +Every major version update should also be reflected in the README of the plugin as well as the use case examples. + +It would be great for users to be able to reference several versions of the plugin with the updated examples to see if they want to keep the current version or upgrade and also to understand what the new version offers. Although this is good: + +- Try to not clog your release repository with older versions of the plugin as you update, as they’re not often needed. Instead, simply keep the last few in place. + +- Try not to push every iterative change from Git live + +## Tools for dependency version maintenance + +There are a couple of useful tools that can help with keeping dependencies up to date. + +- [Version Lens](https://marketplace.visualstudio.com/items?itemName=pflannery.vscode-versionlens) enables you to update your dependencies from your `package.json` by allowing you see the available version number the package can be updated to, right above the current version each package in dependencies or devDependencies uses. + +- The [npm check updates](https://www.npmjs.com/package/npm-check-updates) command line tool helps to check for outdated dependencies. You can also use this tool to update those dependencies by following these steps: + +1. Install the tool + +```shell + npm i -g npm-check-updates +``` + +2. Run the command to update dependencies + +```shell +ncu -u +``` + +## Community supporting content and feedback + +Having example repos and support forums on Discord, Twitter or Reddit are great ways to offer community support for your plugin. This would offer a pool of resources for users to get more information on implementations and contribute. diff --git a/www/src/data/sidebars/doc-links.yaml b/www/src/data/sidebars/doc-links.yaml index 6c89b84bc8e9e..7a134160bf441 100644 --- a/www/src/data/sidebars/doc-links.yaml +++ b/www/src/data/sidebars/doc-links.yaml @@ -265,7 +265,7 @@ link: /docs/pixabay-source-plugin-tutorial/ - title: Remark Plugin Tutorial link: /docs/remark-plugin-tutorial/ - - title: Maintaining a Plugin* + - title: Maintaining a Plugin link: /docs/maintaining-a-plugin/ - title: Themes link: /docs/themes/