Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs(adr): add draft ADR for library release automation #1576

Merged
merged 8 commits into from
Dec 5, 2023
46 changes: 46 additions & 0 deletions adrs/0006-automatic-library-release.md
Original file line number Diff line number Diff line change
@@ -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.
dancormier marked this conversation as resolved.
Show resolved Hide resolved

## 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.
dancormier marked this conversation as resolved.
Show resolved Hide resolved

#### 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)