Skip to content

Commit

Permalink
tidy up CONTRIBUTING.md
Browse files Browse the repository at this point in the history
  • Loading branch information
@dcousens
dcousens committed Sep 30, 2022
1 parent 6f63c9f commit 15c8039
Showing 1 changed file with 5 additions and 184 deletions.
189 changes: 5 additions & 184 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,8 @@ KeystoneJS adheres to the [Contributor Covenant Code of Conduct](/CODE-OF-CONDUC

## Repository Setup

KeystoneJS follows the [Thinkmill Monorepo Style Guide](https://github.com/Thinkmill/monorepo). For more information on the reasoning behind using certain tooling, please refer to it.
KeystoneJS follows the [Thinkmill Monorepo Style Guide](https://github.com/Thinkmill/monorepo).
For more information on the reasoning behind using certain tooling, please refer to it.

### Version management

Expand Down Expand Up @@ -74,9 +75,9 @@ You can have multiple changesets in a single PR. This will give you more granula

We’re sometimes lovingly picky on the wording of our changesets because these end up in changelogs that people like you read. We want to try to get a consistent tone of voice while providing useful information to the reader.

In particular, please try to write in the past tense (e.g. "Added a new feature" rather than "Add a new feature") and write in complete sentences. This means proper capitalisation and punctuation, including full stops/periods at the end of sentences. We try to be terse when possible but if needed it's fine to write multiple lines including examples for changing APIs.

Thanks for your help with this.
In particular, please try to write in the present tense, like git commits (e.g. "Adds a new feature" rather than "Added a new feature") and write in complete sentences.
This means proper capitalisation and punctuation, including full stops/periods at the end of sentences.
Changesets should be short, and prefer leaving complicated explanations to the pull request description.

### How we version packages

Expand Down Expand Up @@ -115,186 +116,6 @@ Minor refactoring, including incorporating changes to Keystone APIs, would not w

Generally, these guidelines are in place so that we don't spam consumers with version upgrades that don't provide value. They are subjective however, and not "one size fits all" so if you're not sure whether a change warrants a version bump, ask for advice in the PR.

### Release Guidelines

#### How to do a release

> This should only ever be done by a very short list of core contributors
Releasing is a two-step process. The first step updates the packages, and the second step publishes updated packages to npm.

##### Update Packages (automatic)

This step is handled for us by the Changesets GitHub Action. As PRs are opened
against `main`, the bot will open and update a PR which generates the
appropriate `CHANGELOG.md` entries and `package.json` version bumps.

Once ready for a release, merge the bot's PR into `main`.

> _NOTE: For information on manually updating packages, see [Update Packages
> (manual)](#update-packages-manual)_
##### Publish Packages

Once the version changes are merged back in to main, to do a manual release:

```sh
yarn fresh && \
yarn publish-changed && \
git push --tags
```

The `yarn publish-changed` command finds packages where the version listed in the `package.json` is ahead of the version published on npm, and attempts to publish just those packages.

NOTE: There is no reason you should ever manually edit the version in the `package.json`

##### Update Packages (manual)

If you wish to do a manual release (useful for back-porting fixes), follow these
steps. Otherwise, skip on to the next section for _Publishing Packages_.

The first step is `yarn version-packages`. This will find all changesets that have been created since the last release, and update the version in package.json as specified in those changesets, flattening out multiple bumps to a single package into a single version update.

The `yarn version-packages` command will generate a release commit, which will bump all versions, necessary dependency version changes, and update changelog.mds.

The commands to run are:

```sh
git checkout main && \
git pull && \
git branch -D temp-release-branch && \
git checkout -b temp-release-branch && \
yarn fresh && \
yarn build && \
yarn version-packages && \
yarn format && \
git add . && \
git commit -m "Version packages" && \
git push --set-upstream origin temp-release-branch
```

Once you have run this you will need to make a pull request to merge this back into main.

Finally, make sure you've got the latest of everything locally

```sh
git checkout main && \
git pull && \
yarn
```

#### A quick note on changelogs

The release process will automatically generate and update a `CHANGELOG.md` file, however this does not need to be the only way this file is modified. The changelogs are deliberately static assets so past changelogs can be updated or expanded upon.

In addition, content added above the last released version will automatically be appended to the next release. If your changes do not fit comfortably within the summary of a changelog, we encourage you to add a more detailed account directly into the `CHANGELOG.md`.

#### Backporting Fixes

Occasionally a bug goes undetected for a few versions. When a fix is discovered,
it may need to be applied to all affected versions (depending on the
severity, security considerations, etc). This is called _backporting_.

First, find out the oldest version which was affected. This can be done using
`git blame`, browsing the `CHANGELOG.md`s, etc.

Once we know which version introduced the bug, walk forward through the
`CHANGELOG.md` noting all the _minor_ and _major_ releases made since.

> Example: If a bug was introduced in `14.0.0`, but not discovered until after
> `15.1.1` was released, the list of _minor_ and _major_ releases may look like:
>
> - `14.0.x`
> - `14.1.x`
> - `15.0.x`
> - `15.1.x`
We're going to do a backport and release for the HEAD of every _minor_ and
_major_ release, ignoring any interim patch releases.

> Example: These may be the releases we'd backport to:
>
> - ❌ `14.0.0`
> - ✅ `14.0.1`
> - ✅ `14.1.0`
> - ❌ `15.0.0`
> - ❌ `15.0.1`
> - ✅ `15.0.2`
> - ✅ `15.1.0`
Now, for each release we want to backport to, we follow this process:

1. Checkout the tag of the release

Let's say the package being patched is `@keystonejs/keystone`, then we
want to run:

```sh
git checkout -b backport-keystone-14.0.1 @keystonejs/keystone@14.0.1
```

2. Cherry pick the commit across.

Fix any merge conflicts that might arise.

NOTE: Make sure the changeset is either regenerated or edited to accurately
relfect the change to the one package you're bumping, otherwise weirdness
will happen.
```sh
git cherry-pick abc123123
```
3. Bump package versions
```sh
yarn fresh --prefer-offline && \
yarn build && \
yarn version-packages && \
yarn format && \
git add . && \
git commit -m "Backport fix"
```
4. Do _NOT_ open a PR
This change is not going to be PR'd into main. Instead we'll later push
the tag which contains the commits.
To confirm everything is as expected, look at the git log:
```sh
git log -p
```
5. Publish the newly version bumped package
Note we can't use changesets to do this special publish as it doesn't handle backports.
```sh
(\
export PACKAGE_NAME=@keystonejs/keystone && \
export OTP_CODE= && \
cd packages/core && \
yarn publish --tag=backport --otp=$OTP_CODE && \
export BACKPORTED_VERSION=`npm dist-tag ls $PACKAGE_NAME | grep 'backport' | sed -e 's/backport: //'` && \
yarn tag remove $PACKAGE_NAME backport --otp=$OTP_CODE && \
git tag -a "$PACKAGE_NAME@$BACKPORTED_VERSION" -m "$PACKAGE_NAME@$BACKPORTED_VERSION"
git push --tags \
)
```
_NOTE: When prompted for "New version", just hit Enter_
<!-- this was the cd command but we don't have a command to replace the exact bolt part yet: cd `bolt ws $PACKAGE_NAME exec -- pwd | grep pwd | sed -e 's/.*pwd[ ]*//'` && \ w
-->

6. Confirm it was published

```sh
npm show <PACKAGE_NAME> versions
```

### Build Process

Some of the packages in keystone need to compiled before they're published, we use [preconstruct](https://github.com/preconstruct/preconstruct) to do this.
Expand Down

0 comments on commit 15c8039

Please sign in to comment.