From c2eb7ae328837e7dab289fcf34191f7f41085304 Mon Sep 17 00:00:00 2001 From: Josh Black Date: Mon, 9 Jan 2023 13:50:20 -0600 Subject: [PATCH 1/9] docs: add versioning guide --- contributor-docs/versioning.md | 119 +++++++++++++++++++++++++++++++++ 1 file changed, 119 insertions(+) create mode 100644 contributor-docs/versioning.md diff --git a/contributor-docs/versioning.md b/contributor-docs/versioning.md new file mode 100644 index 00000000000..451e9e0aa20 --- /dev/null +++ b/contributor-docs/versioning.md @@ -0,0 +1,119 @@ +# Versioning + + + + +## Table of Contents + + + + +## Overview + +The Primer 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 +Primer you should feel confident that you can update without +anything breaking in your project. For a full list of changes that the team +commits to being backwards-compatible, view the [changes](#changes) table +below. + +## Changes + +| Category | Type of change | semver bump | +| :--------- | :------------------------------------------------------------ | :---------- | +| Component | A component is added | `minor` | +| | A component is deprecated | `minor` | +| | A component is removed | `major` | +| Props | A prop is added to a component | `minor` | +| | The type of a prop is made more general | `minor` | +| | The type of a prop is made more specific | `major` | +| | A prop is deprecated | `minor` | +| | A prop is removed from a component | `major` | +| | The element to which additional props are added to is changed | | +| Markup | The DOM node that an `id` corresponds to is changed | | +| | The DOM node that an `aria-label` corresponds to is changed | | +| | The `role` of a component is changed | | +| Styles | The `position` of the outermost element is updated | | +| | The `display` property of the outermost element is updated | | +| | A flex or grid property is updated | | +| Behavior | Interactions are added to a component | | +| | Interactions are removed from a component | | +| TypeScript | A type is added | `minor` | +| | A type is made more general | `minor` | +| | A type is made more specific | `major` | +| | A type is removed | `major` | +| Package | An entrypoint is added to the package | `minor` | +| | An entrypoint is removed from a package | `major` | + +### Examples + +#### A prop is added to a component + +semver bump: **minor** + +```diff +type Props = { + propA: string; ++ propB: string; +}; + +function ExampleComponent({ + propA, ++ propB, +}: Props) { + return ( + <> + {propA} ++ {propB} + + ); +} +``` + +#### An existing prop is deprecated + +semver bump: **minor** + +```diff +type Props = { + propA: string; ++ /** ++ * @deprecated This prop will be removed in the next major version of ++ * `@primer/react`. Please use instead. ++ */ + propB: string; +}; + +function ExampleComponent({ + propA, ++ propB, +}: Props) { + return ( + <> + {propA} ++ {propB} + + ); +} +``` + +#### The DOM node that an `id` corresponds to is changed + +semver bump: **major** + +#### The DOM node that an `aria-label` corresponds to is changed + +semver bump: **minor** From 4d71ac809746970d48766f8771e4911bf52e1f35 Mon Sep 17 00:00:00 2001 From: Josh Black Date: Mon, 9 Jan 2023 13:51:54 -0600 Subject: [PATCH 2/9] docs: run doctoc --- contributor-docs/versioning.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/contributor-docs/versioning.md b/contributor-docs/versioning.md index 451e9e0aa20..9bde6bfae9f 100644 --- a/contributor-docs/versioning.md +++ b/contributor-docs/versioning.md @@ -5,6 +5,14 @@ ## Table of Contents +- [Overview](#overview) +- [Changes](#changes) + - [Examples](#examples) + - [A prop is added to a component](#a-prop-is-added-to-a-component) + - [An existing prop is deprecated](#an-existing-prop-is-deprecated) + - [The DOM node that an `id` corresponds to is changed](#the-dom-node-that-an-id-corresponds-to-is-changed) + - [The DOM node that an `aria-label` corresponds to is changed](#the-dom-node-that-an-aria-label-corresponds-to-is-changed) + From 0a052f830e43854dc2257731c95f3e88cc7c1dcd Mon Sep 17 00:00:00 2001 From: Josh Black Date: Mon, 9 Jan 2023 14:09:23 -0600 Subject: [PATCH 3/9] Update versioning.md --- contributor-docs/versioning.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/contributor-docs/versioning.md b/contributor-docs/versioning.md index 9bde6bfae9f..d7ce17a5179 100644 --- a/contributor-docs/versioning.md +++ b/contributor-docs/versioning.md @@ -57,6 +57,10 @@ below. | Styles | The `position` of the outermost element is updated | | | | The `display` property of the outermost element is updated | | | | A flex or grid property is updated | | +| | A selector is added | | +| | A selector is removed | | +| | The specificity of a selector is raised | | +| | The specificity of a selector is lowered | | | Behavior | Interactions are added to a component | | | | Interactions are removed from a component | | | TypeScript | A type is added | `minor` | From 0af18685930c69410efbd5f69d1b2fa9e1d4c604 Mon Sep 17 00:00:00 2001 From: Josh Black Date: Tue, 10 Jan 2023 12:49:55 -0600 Subject: [PATCH 4/9] docs(versioning): update about section and add todo notes for bumps --- contributor-docs/versioning.md | 35 +++++++++++++++++----------------- 1 file changed, 18 insertions(+), 17 deletions(-) diff --git a/contributor-docs/versioning.md b/contributor-docs/versioning.md index d7ce17a5179..efd4b6a47bc 100644 --- a/contributor-docs/versioning.md +++ b/contributor-docs/versioning.md @@ -34,35 +34,36 @@ that we ship. From semver.org, this means that: As a result, whenever you see a `minor` or `patch` update for a package from the Primer you should feel confident that you can update without -anything breaking in your project. For a full list of changes that the team -commits to being backwards-compatible, view the [changes](#changes) table -below. +anything breaking in your project. For a full list of changes and their +corresponding semver bumps, check out the [changes](#changes) table below. + +For a full list of releases, visit our [releases](https://github.com/primer/react/releases) page. ## Changes | Category | Type of change | semver bump | | :--------- | :------------------------------------------------------------ | :---------- | | Component | A component is added | `minor` | -| | A component is deprecated | `minor` | +| | A component is deprecated | `major` | | | A component is removed | `major` | | Props | A prop is added to a component | `minor` | | | The type of a prop is made more general | `minor` | | | The type of a prop is made more specific | `major` | | | A prop is deprecated | `minor` | | | A prop is removed from a component | `major` | -| | The element to which additional props are added to is changed | | -| Markup | The DOM node that an `id` corresponds to is changed | | -| | The DOM node that an `aria-label` corresponds to is changed | | -| | The `role` of a component is changed | | -| Styles | The `position` of the outermost element is updated | | -| | The `display` property of the outermost element is updated | | -| | A flex or grid property is updated | | -| | A selector is added | | -| | A selector is removed | | -| | The specificity of a selector is raised | | -| | The specificity of a selector is lowered | | -| Behavior | Interactions are added to a component | | -| | Interactions are removed from a component | | +| | The element to which additional props are added to is changed | `` | +| Markup | The DOM node that an `id` corresponds to is changed | `` | +| | The DOM node that an `aria-label` corresponds to is changed | `` | +| | The `role` of a component is changed | `` | +| Styles | The `position` of the outermost element is updated | `` | +| | The `display` property of the outermost element is updated | `` | +| | A flex or grid property is updated | `` | +| | A selector is added | `` | +| | A selector is removed | `` | +| | The specificity of a selector is raised | `` | +| | The specificity of a selector is lowered | `` | +| Behavior | Interactions are added to a component | `` | +| | Interactions are removed from a component | `` | | TypeScript | A type is added | `minor` | | | A type is made more general | `minor` | | | A type is made more specific | `major` | From ca3559b6592da6d79a59b05af42fee1263f25c2c Mon Sep 17 00:00:00 2001 From: Josh Black Date: Thu, 12 Jan 2023 10:22:37 -0600 Subject: [PATCH 5/9] Update versioning.md --- contributor-docs/versioning.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/contributor-docs/versioning.md b/contributor-docs/versioning.md index efd4b6a47bc..06ae94d0559 100644 --- a/contributor-docs/versioning.md +++ b/contributor-docs/versioning.md @@ -70,6 +70,10 @@ For a full list of releases, visit our [releases](https://github.com/primer/reac | | A type is removed | `major` | | Package | An entrypoint is added to the package | `minor` | | | An entrypoint is removed from a package | `major` | +| | A dependency is added to the project's `package.json` | `` | +| | A dependency is removed from the project's `package.json` | `` | +| | A dependency range is updated | `` | +| | A pinned dependency version is updated to be range | `` | ### Examples From 621640ba251a650e35db7872058ad59676b050b7 Mon Sep 17 00:00:00 2001 From: Josh Black Date: Tue, 24 Jan 2023 09:56:33 -0600 Subject: [PATCH 6/9] Update versioning.md --- contributor-docs/versioning.md | 1 + 1 file changed, 1 insertion(+) diff --git a/contributor-docs/versioning.md b/contributor-docs/versioning.md index 06ae94d0559..ae7a2644803 100644 --- a/contributor-docs/versioning.md +++ b/contributor-docs/versioning.md @@ -74,6 +74,7 @@ For a full list of releases, visit our [releases](https://github.com/primer/reac | | A dependency is removed from the project's `package.json` | `` | | | A dependency range is updated | `` | | | A pinned dependency version is updated to be range | `` | +| Visual | The design for a component has been updated | `` | ### Examples From fa353fd79d23510e7b1feeb0926df7b997e27ed8 Mon Sep 17 00:00:00 2001 From: Josh Black Date: Mon, 30 Jan 2023 10:21:09 -0600 Subject: [PATCH 7/9] Add token reference --- contributor-docs/versioning.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/contributor-docs/versioning.md b/contributor-docs/versioning.md index ae7a2644803..d15c70188ef 100644 --- a/contributor-docs/versioning.md +++ b/contributor-docs/versioning.md @@ -55,13 +55,15 @@ For a full list of releases, visit our [releases](https://github.com/primer/reac | Markup | The DOM node that an `id` corresponds to is changed | `` | | | The DOM node that an `aria-label` corresponds to is changed | `` | | | The `role` of a component is changed | `` | -| Styles | The `position` of the outermost element is updated | `` | +| Style | The `position` of the outermost element is updated | `` | | | The `display` property of the outermost element is updated | `` | | | A flex or grid property is updated | `` | | | A selector is added | `` | | | A selector is removed | `` | | | The specificity of a selector is raised | `` | | | The specificity of a selector is lowered | `` | +| | A token used for a CSS property has changed | `` | +| | A component token is no longer used | `` | | Behavior | Interactions are added to a component | `` | | | Interactions are removed from a component | `` | | TypeScript | A type is added | `minor` | From 0800394e2d4afd75679f367a8bfa0392f04b0e24 Mon Sep 17 00:00:00 2001 From: Josh Black Date: Mon, 30 Jan 2023 10:21:50 -0600 Subject: [PATCH 8/9] Update versioning.md --- contributor-docs/versioning.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/contributor-docs/versioning.md b/contributor-docs/versioning.md index d15c70188ef..2d6ee88ff03 100644 --- a/contributor-docs/versioning.md +++ b/contributor-docs/versioning.md @@ -32,8 +32,8 @@ that we ship. From semver.org, this means that: > _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 -Primer you should feel confident that you can update without +As a result, whenever you see a `minor` or `patch` update to a package from the +Primer team you should feel confident that you can update without anything breaking in your project. For a full list of changes and their corresponding semver bumps, check out the [changes](#changes) table below. From 37cfd07fb1eef4c0655157a0c9025cec94abaed5 Mon Sep 17 00:00:00 2001 From: Josh Black Date: Mon, 30 Jan 2023 13:29:16 -0600 Subject: [PATCH 9/9] Update versioning.md --- contributor-docs/versioning.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/contributor-docs/versioning.md b/contributor-docs/versioning.md index 2d6ee88ff03..e48794987a0 100644 --- a/contributor-docs/versioning.md +++ b/contributor-docs/versioning.md @@ -77,6 +77,9 @@ For a full list of releases, visit our [releases](https://github.com/primer/reac | | A dependency range is updated | `` | | | A pinned dependency version is updated to be range | `` | | Visual | The design for a component has been updated | `` | +| Theming | A token in a theme is no longer used by a component | `` | +| | A token in a theme is added | `` | +| | A token value in a theme is changed | `` | ### Examples