From 719b74993db90680eeb4421c722403f343eb79f8 Mon Sep 17 00:00:00 2001 From: Dan Cormier Date: Mon, 4 Dec 2023 17:23:40 -0500 Subject: [PATCH 1/7] docs(adr): add draft ADR for library release automation [STACKS-417](https://stackoverflow.atlassian.net/browse/STACKS-417) --- adrs/0006-automatic-library-release.md | 46 ++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) create mode 100644 adrs/0006-automatic-library-release.md diff --git a/adrs/0006-automatic-library-release.md b/adrs/0006-automatic-library-release.md new file mode 100644 index 0000000000..1fa0f7e6c7 --- /dev/null +++ b/adrs/0006-automatic-library-release.md @@ -0,0 +1,46 @@ +# Automatic Library Release + +**Date:** 2023-12-04 + +**Related PR:** [#1576](https://github.com/StackExchange/Stacks/pull/1576) + +## Issue + +At the time of writing, many Stacks libraries are released manually. This is a time-consuming process that is prone to human error. We should automate this process to save time and reduce errors. + +## Decision + +We will use [Changesets](https://github.com/changesets/changesets) to manage versioning and automate the release process of our libraries in conjunction with GitHub Actions. + +### Reasoning + +#### Ease of use + +The primary implentation of Changesets is its [CLI package](https://www.npmjs.com/package/@changesets/cli) which will help us manage the versioning and changelog entries for your packages. We can apply the [Changesets bot](https://github.com/apps/changeset-bot) to any repository verify that a given PR has a changeset associated with it and remind the author to create one if it does not. + +#### Level of automation + +With Changesets, it's [trivial to setup a GitHub Action](https://github.com/changesets/action/) that will create a release PR whenever a given branch includes pending changesets. This automates much of the effort required to release a new version of a library while still allowing us to review the changesets before they are released. + +#### Encourages good practices + +By using Changesets, we can encourage contributors to write detailed descriptions of their changes and group them together in a single changeset. This removes the reliance on Git messages to describe changes that may require more detail than one would generally include in a Git message. + +#### Monorepo support + +From Changesets' [documentation](https://github.com/changesets/changesets/blob/main/docs/problems-publishing-in-monorepos.md): + +> Monorepos have a heap of complexity around how publishing to npm works. Changesets helps most repository users avoid ever having to think about these problems, however repository maintainers, especially those who want to customise how their releases work (for example those not using our github action), may want to understand what it is solving for you. + +#### Changelog generation support + +The automated release PRs created by Changesets include a changelog entry for each changeset included in the release, which we can adjust if necessary before merging the PR. + +#### npm publish support + +Release PRs generated by Changesets can be used in conjunction with GitHub Actions to automatically publish a package to npm when the PR is merged. See the [GitHub Action currently in use in the axe-apca repository](https://github.com/StackExchange/apca-check/blob/main/.github/workflows/release.yml) for a real-world example. + + +## Additional info + +- [Changesets repository](https://github.com/changesets/changesets) \ No newline at end of file From 9611cc3c465d5b7da139ea167ee1dcaf4f4b25af Mon Sep 17 00:00:00 2001 From: Dan Cormier Date: Tue, 5 Dec 2023 12:28:54 -0500 Subject: [PATCH 2/7] Fix grammatical errors Co-authored-by: Giamir Buoncristiani --- adrs/0006-automatic-library-release.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/adrs/0006-automatic-library-release.md b/adrs/0006-automatic-library-release.md index 1fa0f7e6c7..c95d37ca40 100644 --- a/adrs/0006-automatic-library-release.md +++ b/adrs/0006-automatic-library-release.md @@ -16,7 +16,7 @@ We will use [Changesets](https://github.com/changesets/changesets) to manage ver #### Ease of use -The primary implentation of Changesets is its [CLI package](https://www.npmjs.com/package/@changesets/cli) which will help us manage the versioning and changelog entries for your packages. We can apply the [Changesets bot](https://github.com/apps/changeset-bot) to any repository verify that a given PR has a changeset associated with it and remind the author to create one if it does not. +The primary implentation of Changesets is its [CLI package](https://www.npmjs.com/package/@changesets/cli) which will help us manage the versioning and changelog entries for our packages. We can apply the [Changesets bot](https://github.com/apps/changeset-bot) to any repository to verify that a given PR has a changeset associated with it and remind the author to create one if it does not. #### Level of automation From 9465ebd8abcbae06270a21822720cefde63d4eb8 Mon Sep 17 00:00:00 2001 From: Dan Cormier Date: Tue, 5 Dec 2023 12:32:56 -0500 Subject: [PATCH 3/7] Add note on conventional commits --- adrs/0006-automatic-library-release.md | 1 + 1 file changed, 1 insertion(+) diff --git a/adrs/0006-automatic-library-release.md b/adrs/0006-automatic-library-release.md index 1fa0f7e6c7..4c1dcadfb3 100644 --- a/adrs/0006-automatic-library-release.md +++ b/adrs/0006-automatic-library-release.md @@ -11,6 +11,7 @@ At the time of writing, many Stacks libraries are released manually. This is a t ## Decision We will use [Changesets](https://github.com/changesets/changesets) to manage versioning and automate the release process of our libraries in conjunction with GitHub Actions. +***Note**: Despite using changesets to communicate the intent of creating releases in a more explicit way, we still follow [conventional commits standards](/Users/dan/Code/Stacks/adrs/0006-automatic-library-release.md) for keeping our git history easily parseable by the human eye.* ### Reasoning From 3f6686e58a3d7b3f44087711a628c94c15be0708 Mon Sep 17 00:00:00 2001 From: Dan Cormier Date: Tue, 5 Dec 2023 13:12:29 -0500 Subject: [PATCH 4/7] Match official case for "changesets" --- adrs/0006-automatic-library-release.md | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/adrs/0006-automatic-library-release.md b/adrs/0006-automatic-library-release.md index 4c1dcadfb3..70c7f50619 100644 --- a/adrs/0006-automatic-library-release.md +++ b/adrs/0006-automatic-library-release.md @@ -10,36 +10,38 @@ At the time of writing, many Stacks libraries are released manually. This is a t ## Decision -We will use [Changesets](https://github.com/changesets/changesets) to manage versioning and automate the release process of our libraries in conjunction with GitHub Actions. -***Note**: Despite using changesets to communicate the intent of creating releases in a more explicit way, we still follow [conventional commits standards](/Users/dan/Code/Stacks/adrs/0006-automatic-library-release.md) for keeping our git history easily parseable by the human eye.* +We will use [changesets](https://github.com/changesets/changesets) to manage versioning and automate the release process of our libraries in conjunction with GitHub Actions. + +***Note**: Despite using changesets to handle automatic library releases and changelogs, we still follow [conventional commits standards](/Users/dan/Code/Stacks/adrs/0006-automatic-library-release.md) for keeping our git history easily parseable by the human eye.* ### Reasoning #### Ease of use -The primary implentation of Changesets is its [CLI package](https://www.npmjs.com/package/@changesets/cli) which will help us manage the versioning and changelog entries for your packages. We can apply the [Changesets bot](https://github.com/apps/changeset-bot) to any repository verify that a given PR has a changeset associated with it and remind the author to create one if it does not. +The primary implentation of changesets is its [CLI package](https://www.npmjs.com/package/@changesets/cli) which will help us manage the versioning and changelog entries for your packages. We can apply the [changesets bot](https://github.com/apps/changeset-bot) to any repository verify that a given PR has a changeset associated with it and remind the author to create one if it does not. #### Level of automation -With Changesets, it's [trivial to setup a GitHub Action](https://github.com/changesets/action/) that will create a release PR whenever a given branch includes pending changesets. This automates much of the effort required to release a new version of a library while still allowing us to review the changesets before they are released. +With changesets, it's [trivial to setup a GitHub Action](https://github.com/changesets/action/) that will create a release PR whenever a given branch includes pending changesets. This automates much of the effort required to release a new version of a library while still allowing us to review the changesets before they are released. #### Encourages good practices -By using Changesets, we can encourage contributors to write detailed descriptions of their changes and group them together in a single changeset. This removes the reliance on Git messages to describe changes that may require more detail than one would generally include in a Git message. +By using changesets, we can encourage contributors to write detailed descriptions of their changes and group them together in a single changeset. This removes the reliance on Git messages to describe changes that may require more detail than one would generally include in a Git message. #### Monorepo support -From Changesets' [documentation](https://github.com/changesets/changesets/blob/main/docs/problems-publishing-in-monorepos.md): +From changesets' [documentation](https://github.com/changesets/changesets/blob/main/docs/problems-publishing-in-monorepos.md): > Monorepos have a heap of complexity around how publishing to npm works. Changesets helps most repository users avoid ever having to think about these problems, however repository maintainers, especially those who want to customise how their releases work (for example those not using our github action), may want to understand what it is solving for you. #### Changelog generation support -The automated release PRs created by Changesets include a changelog entry for each changeset included in the release, which we can adjust if necessary before merging the PR. +The automated release PRs created by changesets include a changelog entry for each changeset included in the release, which we can adjust if necessary before merging the PR. #### npm publish support -Release PRs generated by Changesets can be used in conjunction with GitHub Actions to automatically publish a package to npm when the PR is merged. See the [GitHub Action currently in use in the axe-apca repository](https://github.com/StackExchange/apca-check/blob/main/.github/workflows/release.yml) for a real-world example. +Release PRs generated by changesets can be used in conjunction with GitHub Actions to automatically publish a package to npm when the PR is merged. See the [GitHub Action currently in use in the axe-apca repository](https://github.com/StackExchange/apca-check/blob/main/.github/workflows/release.yml) for a real-world example. + ## Additional info From 10c06cc90d4dac8898451c5379929d7534cd1ed6 Mon Sep 17 00:00:00 2001 From: Dan Cormier Date: Tue, 5 Dec 2023 13:12:48 -0500 Subject: [PATCH 5/7] Add placeholder "other tools considered" section --- adrs/0006-automatic-library-release.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/adrs/0006-automatic-library-release.md b/adrs/0006-automatic-library-release.md index 70c7f50619..e43273edb3 100644 --- a/adrs/0006-automatic-library-release.md +++ b/adrs/0006-automatic-library-release.md @@ -42,7 +42,19 @@ The automated release PRs created by changesets include a changelog entry for ea Release PRs generated by changesets can be used in conjunction with GitHub Actions to automatically publish a package to npm when the PR is merged. See the [GitHub Action currently in use in the axe-apca repository](https://github.com/StackExchange/apca-check/blob/main/.github/workflows/release.yml) for a real-world example. +### Other tools considered +#### [standard-version](https://github.com/conventional-changelog/standard-version) + +`standard-version` was deprecated in May 2022. They recommend `release-please` as an alternative. + +#### [release-please](https://github.com/googleapis/release-please) + +TODO + +#### [semantic-release](https://github.com/semantic-release/semantic-release) + +TODO ## Additional info From 277b910f10f8c9202a759bebfed0f24c4b9ec801 Mon Sep 17 00:00:00 2001 From: Dan Cormier Date: Tue, 5 Dec 2023 14:21:17 -0500 Subject: [PATCH 6/7] Complete "Other tools considered" section --- adrs/0006-automatic-library-release.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/adrs/0006-automatic-library-release.md b/adrs/0006-automatic-library-release.md index 47c85b2641..c0224005d7 100644 --- a/adrs/0006-automatic-library-release.md +++ b/adrs/0006-automatic-library-release.md @@ -12,7 +12,7 @@ At the time of writing, many Stacks libraries are released manually. This is a t We will use [changesets](https://github.com/changesets/changesets) to manage versioning and automate the release process of our libraries in conjunction with GitHub Actions. -***Note**: Despite using changesets to handle automatic library releases and changelogs, we still follow [conventional commits standards](/Users/dan/Code/Stacks/adrs/0006-automatic-library-release.md) for keeping our git history easily parseable by the human eye.* +***Note**: Despite using changesets to handle automatic library releases and changelogs, we still follow [conventional commits standards](https://www.conventionalcommits.org/en/v1.0.0/) for keeping our git history easily parseable by the human eye.* ### Reasoning @@ -50,11 +50,11 @@ Release PRs generated by changesets can be used in conjunction with GitHub Actio #### [release-please](https://github.com/googleapis/release-please) -TODO +`release-please` is a very similar tool to changesets, but we opted for changesets because of `release-please`'s [*requirement* of using conventional commits](https://github.com/googleapis/release-please/tree/main#how-should-i-write-my-commits). We want to encourage conventional commits, but not require them or tightly couple to the format. #### [semantic-release](https://github.com/semantic-release/semantic-release) -TODO +`semantic-release` does not include first-class monorepo support. The extra setup and overhead required to use it in a monorepo environment made `semantic-release` less appealing when compared to other options. ## Additional info From 745679c64152535d7d79ac89a94058cfef00bb20 Mon Sep 17 00:00:00 2001 From: Dan Cormier Date: Tue, 5 Dec 2023 14:26:02 -0500 Subject: [PATCH 7/7] Add line describing the PoLP issue --- adrs/0006-automatic-library-release.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/adrs/0006-automatic-library-release.md b/adrs/0006-automatic-library-release.md index c0224005d7..89c0b44e4e 100644 --- a/adrs/0006-automatic-library-release.md +++ b/adrs/0006-automatic-library-release.md @@ -6,7 +6,7 @@ ## Issue -At the time of writing, many Stacks libraries are released manually. This is a time-consuming process that is prone to human error. We should automate this process to save time and reduce errors. +At the time of writing, many Stacks libraries are released manually. This is a time-consuming process that is prone to human error. We should automate this process to save time and reduce errors. The lack of an automated release process requires use to permit developer-specific accounts to publish, which is a liability and violates the [principle of least privilege](https://en.wikipedia.org/wiki/Principle_of_least_privilege). ## Decision