diff --git a/docs/guides/versioning.md b/docs/guides/versioning.md new file mode 100644 index 000000000000..bb76e9eaa84b --- /dev/null +++ b/docs/guides/versioning.md @@ -0,0 +1,230 @@ +# Versioning + + + + +## Table of Contents + +- [Overview](#overview) +- [`carbon-components-react`](#carbon-components-react) + - [Changes](#changes) + - [Examples](#examples) + - [A new prop is added to a component](#a-new-prop-is-added-to-a-component) + - [An existing prop is deprecated](#an-existing-prop-is-deprecated) + - [An existing prop is removed](#an-existing-prop-is-removed) + - [An existing prop type is changed to be more specific](#an-existing-prop-type-is-changed-to-be-more-specific) + - [An existing prop type is changed to be more generic](#an-existing-prop-type-is-changed-to-be-more-generic) + - [A `PropTypes.func` prop type is changed to have different arguments](#a-proptypesfunc-prop-type-is-changed-to-have-different-arguments) + - [A `PropTypes.func` prop type is changed to have additional arguments](#a-proptypesfunc-prop-type-is-changed-to-have-additional-arguments) + - [A `PropTypes.func` prop type is changed to have fewer arguments](#a-proptypesfunc-prop-type-is-changed-to-have-fewer-arguments) + + + + +## Overview + +The Carbon Design System team aims to follow +[Semantic Versioning](https://semver.org/) (semver) for each of the packages +that we ship. From semver.org, this means that: + +> Given a version number MAJOR.MINOR.PATCH, increment the: +> +> 1. **MAJOR** version when you make incompatible API changes, +> 2. **MINOR** version when you add functionality in a backwards compatible +> manner, and +> 3. **PATCH** version when you make backwards compatible bug fixes. +> +> _Additional labels for pre-release and build metadata are available as +> extensions to the MAJOR.MINOR.PATCH format._ + +As a result, whenever you see a `minor` or `patch` update for a package from the +Carbon Design System you should feel confident that you can update without +anything breaking in your project. + +**Note:** If you ever bring in an update and it does break something in your +project, please create an +[issue](https://github.com/carbon-design-system/carbon/issues/new?assignees=&labels=type%3A+bug+%F0%9F%90%9B&template=bug-report.md&title=Breaking%20change) +and we will resolve the issue as quickly as possible. + +In the following sections, you'll find specific details for our packages and the +types of changes you can expect to occur as a consumer of that package. We'll +try to highlight common changes in code and the corresponding `semver` bump that +you can expect for the package when it is updated. + +## `carbon-components-react` + +### Changes + +| Type of change | semver bump | +| ------------------------------------------------------------------- | ----------- | +| A new prop is added to a component | `minor` | +| An existing prop is deprecated | `minor` | +| An existing prop is removed | `major` | +| An existing prop type is changed to be more specific | `major` | +| An existing prop type is changed to be more generic | `minor` | +| A `PropTypes.func` prop type is changed to have different arguments | `major` | +| A `PropTypes.func` prop type is changed to have additional argument | `minor` | +| A `PropTypes.func` prop type is changed to have fewer arguments | `major` | + +### Examples + +#### A new prop is added to a component + +semver bump: **minor** + +```diff +function ExampleComponent({ + propA, ++ propB, +}) { + return ( + <> + {propA} ++ {propB} + + ); +} + +ExampleComponent.propTypes = { + propA: PropTypes.string, ++ propB: PropTypes.string, +}; +``` + +#### An existing prop is deprecated + +semver bump: **minor** + +```diff +function ExampleComponent({ propA, propB }) { + return ( + <> + {propA} + {propB} + + ); +} + +ExampleComponent.propTypes = { + propA: PropTypes.string, +- propB: PropTypes.string, ++ propB: deprecate(PropTypes.string), +}; +``` + +#### An existing prop is removed + +semver bump: **major** + +```diff +function ExampleComponent({ + propA, +- propB, +}) { + return ( + <> + {propA} +- {propB} + + ); +} + +ExampleComponent.propTypes = { + propA: PropTypes.string, +- propB: deprecate(PropTypes.string), +}; +``` + +#### An existing prop type is changed to be more specific + +semver bump: **major** + +```diff +function ExampleComponent({ propA, propB }) { + return ( + <> + {propA} + {propB} + + ); +} + +ExampleComponent.propTypes = { + propA: PropTypes.string, +- propB: PropTypes.node, ++ propB: PropTypes.string, +}; +``` + +#### An existing prop type is changed to be more generic + +semver bump: **minor** + +```diff +function ExampleComponent({ propA, propB }) { + return ( + <> + {propA} + {propB} + + ); +} + +ExampleComponent.propTypes = { + propA: PropTypes.string, +- propB: PropTypes.string, ++ propB: PropTypes.node, +}; +``` + +#### A `PropTypes.func` prop type is changed to have different arguments + +semver bump: **major** + +```diff +import { SomeComponent } from 'carbon-components-react'; + +function ExampleComponent() { + function onChange(arg) { + // If a or b change types (from number to string) or if they are removed + // (a or b no longer exists) + const { a, b } = arg; + } + + return ; +} +``` + +#### A `PropTypes.func` prop type is changed to have additional arguments + +semver bump: **minor** + +```diff +import { SomeComponent } from 'carbon-components-react'; + +function ExampleComponent() { +- function onChange(a, b) { ++ function onChange(a, b, c) { + // ... + } + + return ; +} +``` + +#### A `PropTypes.func` prop type is changed to have fewer arguments + +semver bump: **major** + +```diff +import { SomeComponent } from 'carbon-components-react'; + +function ExampleComponent() { +- function onChange(a, b, c) { ++ function onChange(a, b) { + // ... + } + + return ; +} +```