Skip to content

Commit

Permalink
docs: Updating publishing section of CONTRIBUTING.md
Browse files Browse the repository at this point in the history
Adding sections explaining the automated publishing process enabled by
the release workflow.

Plus left my notes at the bottom
  • Loading branch information
Nathan Stilwell committed Oct 19, 2022
1 parent 2fa658a commit f0d5cfa
Show file tree
Hide file tree
Showing 2 changed files with 50 additions and 0 deletions.
50 changes: 50 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,3 +34,53 @@ Since CSS modules provides the ability to scope class names to a particular modu
```

For more context on how we compose class names in general, see the [objectToClassNames](https://github.com/cockroachdb/ui/blob/master/packages/ui-components/src/utils/objectToClassnames.ts) utility function which expresses how we perform our mappings between component properties that are intended to impact the rendered visual and the module class names which support those visual changes.

## Automated Publishing

A [Github workflow](https://docs.github.com/en/actions/using-workflows/about-workflows) has been setup
[to automatically publish](https://github.com/cockroachdb/ui/blob/master/.github/workflows/release.yml) the packages of
this monorepo using [`auto`](https://intuit.github.io/auto/index). `auto` was created to publish code modules from a
continuous integration environment through pull request interaction. Publishing the packages in this repo is now as
simple as adding labels to a pull request and merging. Each pull request will have a canary version published for testing.
Semantic version increases (patch, minor, or major versions) can be controlled by applying the appropriate label to your
pull request. Each time a version is published, a new [release](https://github.com/cockroachdb/ui/releases) will be created
as well as [tags](https://github.com/cockroachdb/ui/tags) for each published package.

### Branching vs Forking
It is important to note that the [Release workflow](https://github.com/cockroachdb/ui/blob/master/.github/workflows/release.yml)
uses [secrets](https://docs.github.com/en/actions/security-guides/encrypted-secrets) to access tokens necessary to
interact with pull requests and labels as well as publishing to npm. Most secrets are not accessible to the runner when
a workflow is triggered from a
[forked repository](https://docs.github.com/en/actions/security-guides/encrypted-secrets#using-encrypted-secrets-in-a-workflow).
This means that when a pull request is created from a fork, the pull request will not be updated with a canary release.
Version labels can still be applied and packages will still be published upon merging to master. If you would like to
test your changes with a canary release, make sure to create a branch from the `cockroachdb/ui` rather than a branch
from a forked repository.

### Canary Releases
When a pull request is created on a branch, the **Release** workflow will run and publish a canary version of the packages
that have changes in the pull request. The version will be in the form of `X.X.X-canary.yyy.shortSha.#` and have the
[distribution tag](https://docs.npmjs.com/cli/v8/commands/npm-dist-tag) "`canary`". Your PR description will be updated
with a `<details>` block with instructions for installing the canary version.

![Example update PR description](docs/assets/pr-canary-publish-dark.png)

### Applying labels to Pull Requests

`auto` will look at the labels applied to pull request to make decisions about how to increase the version of packages
when publishing after a merge. `auto` is configured to only look at certain labels (labels prefixed with 🤖). Here are
the current labels and what they do,

|label | description |
|----------------|-------------------------------------------------------------------------------------------------------------------------------|
|🤖 major | increase the major version (i.e. - from 1.0.0 to 2.0.0). This is used to denote incompatible changes to the API of a package. |
|🤖 minor | increase the minor version (i.e. - from 0.1.0 to 0.2.0). This is used to denote added functionality (that is backward compatible). |
|🤖 patch | increase the patch version (i.e. - from 0.0.1 to 0.0.2). This is used for bug fixes or refactoring that doesn't change the API. |
|🤖 skip-release | preserve the current version. |

## Publish Notes / Working

- A word about "merging quickly" - https://intuit.github.io/auto/docs/welcome/quick-merge
- Description of labels (release labels and otherwise)
- Canary releases
- Release job might fail to update with Canary release if PR doesn't exist yet
Binary file added docs/assets/pr-canary-publish-dark.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit f0d5cfa

Please sign in to comment.