diff --git a/README.md b/README.md index a5afd6e9..6c8379de 100644 --- a/README.md +++ b/README.md @@ -303,6 +303,10 @@ You can avoid this by: If you think the error you are getting is not related to this at all, please [fill a new issue](https://github.com/testing-library/eslint-plugin-testing-library/issues/new/choose) with as many details as possible. +## Other documentation + +- [Semantic Versioning Policy](/docs/semantic-versioning-policy.md) + ## Contributors ✨ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)): diff --git a/docs/semantic-versioning-policy.md b/docs/semantic-versioning-policy.md new file mode 100644 index 00000000..764b29f0 --- /dev/null +++ b/docs/semantic-versioning-policy.md @@ -0,0 +1,28 @@ +# Semantic Versioning Policy + +`eslint-plugin-testing-library` follows [Semantic Versioning](https://semver.org/). However, for [the same reason as ESLint itself](https://github.com/eslint/eslint#semantic-versioning-policy), it's not always clear when a minor or major version bump occurs. To help clarify this for everyone, we've defined the following Semantic Versioning Policy for this ESLint plugin: + +- Patch release (intended to not break your lint build) + - A bug fix in a rule that results in `eslint-plugin-testing-library` reporting fewer errors. + - A bug fix to the core. + - Re-releasing after a failed release (i.e., publishing a release that doesn't work for anyone). + - A dependency gets updated +- Minor release (might break your lint build) + - A bug fix in a rule that results in `eslint-plugin-testing-library` reporting more errors. + - A new rule is created. + - A new option to an existing rule that does not result in ESLint reporting more errors by default. + - A new option to an existing rule that might result in ESLint reporting more errors by default. + - A new addition to an existing rule to support a newly-added Testing Library feature that will result in `eslint-plugin-testing-library` reporting more errors by default. + - An existing rule is deprecated. + - New capabilities to the public API are added (new classes, new methods, new arguments to existing methods, etc.). + - A new shareable configuration is created. + - An existing shareable configuration is updated and will result in strictly fewer errors (e.g., rule removals). + - Support for a Node major version is added. +- Major release (likely to break your lint build) + - An existing shareable configuration is updated and may result in new errors (e.g., rule additions, most rule option updates). + - Part of the public API is removed or changed in an incompatible way. The public API includes: + - Rule schemas + - Configuration schema + - Support for a Node major version is dropped. + +According to our policy, any minor update may report more errors than the previous release (ex: from a bug fix). As such, we recommend using the tilde (`~`) in `package.json` e.g. `"eslint-plugin-testing-library": "~4.3.0"` to guarantee the results of your builds.