From 5196d9068df64605f82d6ea0d144b500962341f9 Mon Sep 17 00:00:00 2001 From: Jeff Ching Date: Mon, 20 Dec 2021 10:59:09 -0800 Subject: [PATCH] docs: update docs for v13 (#1143) * docs: split out CLI and customization options * docs: anchor links * docs: fix links * update manifest documentation * docs: fix ordering * more crosslinks --- README.md | 162 +++++-------------------- docs/cli.md | 241 ++++++++++++++++++++++++++++++++++++++ docs/customizing.md | 107 +++++++++++++++++ docs/manifest-releaser.md | 121 ++++++++----------- package.json | 4 +- src/bin/release-please.ts | 6 +- 6 files changed, 436 insertions(+), 205 deletions(-) create mode 100644 docs/cli.md create mode 100644 docs/customizing.md diff --git a/README.md b/README.md index 756abf3a8..342bc4e08 100644 --- a/README.md +++ b/README.md @@ -89,31 +89,25 @@ chore: release 2.0.0 Release-As: 2.0.0 ``` -## Release types supported +## Strategy (Language) types supported Release Please automates releases for the following flavors of repositories: | release type | description |-------------------|---------------------------------------------------------| -| node | [A Node.js repository, with a package.json and CHANGELOG.md](https://github.com/yargs/yargs) | -| python | [A Python repository, with a setup.py, setup.cfg, CHANGELOG.md](https://github.com/googleapis/python-storage) and optionally a pyproject.toml and a <project>/\_\_init\_\_.py | -| terraform-module | [A terraform module, with a version in the README.md, and a CHANGELOG.md](https://github.com/terraform-google-modules/terraform-google-project-factory) | -| krm-blueprint | [A kpt package, with 1 or more KRM files and a CHANGELOG.md](https://github.com/GoogleCloudPlatform/blueprints/tree/main/catalog/project) | -| rust | A Rust repository, with a Cargo.toml (either as a crate or workspace) and a CHANGELOG.md | -| ocaml | [An OCaml repository, containing 1 or more opam or esy files and a CHANGELOG.md](https://github.com/grain-lang/binaryen.ml) | -| simple | [A repository with a version.txt and a CHANGELOG.md](https://github.com/googleapis/gapic-generator) | -| helm | A repository with a Chart.yaml and a CHANGELOG.md | -| elixir | A repository with a mix.exs and a CHANGELOG.md | -| dart | A repository with a pubspec.yaml and a CHANGELOG.md | - -## Adding additional release types - -To add a new release type, simply use the existing [releasers](https://github.com/googleapis/release-please/tree/main/src/releasers) and [updaters](https://github.com/googleapis/release-please/tree/main/src/updaters) -as a starting point. - -**releasers** describe the files that should be updated for a release. - -**updaters** describe how to update the version in these files. +| `dart` | A repository with a pubspec.yaml and a CHANGELOG.md | +| `elixir` | A repository with a mix.exs and a CHANGELOG.md | +| `go` | A repository with a CHANGELOG.md | +| `helm` | A repository with a Chart.yaml and a CHANGELOG.md | +| `krm-blueprint` | [A kpt package, with 1 or more KRM files and a CHANGELOG.md](https://github.com/GoogleCloudPlatform/blueprints/tree/main/catalog/project) | +| `node` | [A Node.js repository, with a package.json and CHANGELOG.md](https://github.com/yargs/yargs) | +| `ocaml` | [An OCaml repository, containing 1 or more opam or esy files and a CHANGELOG.md](https://github.com/grain-lang/binaryen.ml) | +| `php` | A repository with a composer.json and a CHANGELOG.md | +| `python` | [A Python repository, with a setup.py, setup.cfg, CHANGELOG.md](https://github.com/googleapis/python-storage) and optionally a pyproject.toml and a <project>/\_\_init\_\_.py | +| `ruby` | A repository with a version.rb and a CHANGELOG.md | +| `rust` | A Rust repository, with a Cargo.toml (either as a crate or workspace) and a CHANGELOG.md | +| `simple` | [A repository with a version.txt and a CHANGELOG.md](https://github.com/googleapis/gapic-generator) | +| `terraform-module` | [A terraform module, with a version in the README.md, and a CHANGELOG.md](https://github.com/terraform-google-modules/terraform-google-project-factory) | ## Setting up Release Please @@ -121,128 +115,34 @@ There are a variety of ways you can deploy release-please: ### GitHub Action (recommended) -The easiest way to run release please is as a GitHub action: - -1. If you haven't already done so, create a `.github/workflows` folder in your - repository (_this is where your actions will live_). -2. Now create a `.github/workflows/release-please.yml` file with these contents: - - ```yaml - on: - push: - branches: - - main - name: release-please - jobs: - release-please: - runs-on: ubuntu-latest - steps: - - uses: GoogleCloudPlatform/release-please-action@v2 - with: - token: ${{ secrets.GITHUB_TOKEN }} - release-type: node - package-name: release-please-action - ``` - -3. Merge the above action into your repository and make sure new commits follow - the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) - convention, [release-please](https://github.com/googleapis/release-please) - will start creating Release PRs for you. - -#### Automating publication to npm - -With a few additions, the Release Please action can be made to publish to -npm when a Release PR is merged: - -```yaml -on: - push: - branches: - - main -name: release-please -jobs: - release-please: - runs-on: ubuntu-latest - steps: - - uses: GoogleCloudPlatform/release-please-action@v2 - id: release - with: - token: ${{ secrets.GITHUB_TOKEN }} - release-type: node - package-name: test-release-please - # The logic below handles the npm publication: - - uses: actions/checkout@v2 - # these if statements ensure that a publication only occurs when - # a new release is created: - if: ${{ steps.release.outputs.release_created }} - - uses: actions/setup-node@v1 - with: - node-version: 12 - registry-url: 'https://registry.npmjs.org' - if: ${{ steps.release.outputs.release_created }} - # if you are using Yarn, substitute the command below with `yarn install --frozen-lockfile` - - run: npm ci - if: ${{ steps.release.outputs.release_created }} - - run: npm publish - env: - NODE_AUTH_TOKEN: ${{secrets.NPM_TOKEN}} - if: ${{ steps.release.outputs.release_created }} -``` - -> So that you can keep 2FA enabled for npm publications, we recommend setting -`registry-url` to your own [Wombat Dressing Room](https://github.com/GoogleCloudPlatform/wombat-dressing-room) deployment. +The easiest way to run release please is as a GitHub action. Please see [google-github-actions/release-please-action](https://github.com/google-github-actions/release-please-action) for installation and configuration instructions. ### Running as CLI -Install release-please globally: +Please see [Running release-please CLI](docs/cli.md) for all the configuration options. -```bash -npm i release-please -g -``` +### Install the GitHub App -### Creating/updating release PRs +There is a probot application available, which allows you to deploy Release +Please as a GitHub App. Please see +[github.com/googleapis/repo-automation-bots](https://github.com/googleapis/repo-automation-bots/tree/main/packages/release-please) +for installation and configuration instructions. -```bash -release-please release-pr --package-name=@google-cloud/firestore" \ - --repo-url=googleapis/nodejs-firestore \ - --token=$GITHUB_TOKEN -``` +## Bootstrapping your Repository -| option | description | -|-------------------|---------------------------------------------------------| -| `--package-name` | is the name of the package to publish to publish to an upstream registry such as npm. | -| `--repo-url` | is the URL of the repository on GitHub. | -| `--token` | a token with write access to `--repo-url`. | -| `--default-branch`| branch to open pull release PR against (detected by default). | -| `--path` | create a release from a path other than the repository's root | -| `--monorepo-tags` | add prefix to tags and branches, allowing multiple libraries to be released from the same repository. | -| `--pull-request-title-pattern` | add title pattern to make release PR, defaults to using `chore${scope}: release${component} ${version}`. | -| `--signoff` | Add [`Signed-off-by`](https://git-scm.com/docs/git-commit#Documentation/git-commit.txt---signoff) line at the end of the commit log message using the user and email provided. (format "Name \") | -| `--api-url` | URL to use when making API requests [default: "https://api.github.com"] | -| `--graphql-url` | URL to use when making GraphQL requests [default: "https://api.github.com"] | - -### Creating a release on GitHub - -```bash -release-please github-release --repo-url=googleapis/nodejs-firestore \ - --token=$GITHUB_TOKEN -``` +Release Please looks at commits since your last release tag. It may or may not be able to find +your previous releases. The easiest way to on-board your repository is to +[bootstrap a manifest config](/docs/cli.md#bootstrapping). -| option | description | -|-------------------|---------------------------------------------------------| -| `--package-name` | is the name of the package to publish to publish to an upstream registry such as npm. | -| `--repo-url` | is the URL of the repository on GitHub. | -| `--token` | a token with write access to `--repo-url`. | -| `--path` | create a release from a path other than the repository's root | -| `--api-url` | URL to use when making API requests [default: "https://api.github.com"] | -| `--graphql-url` | URL to use when making GraphQL requests [default: "https://api.github.com"] | +## Customizing Release Please -### Running as a GitHub App +Release Please provides several configuration options to allow customizing +your release process. Please see [customizing.md](docs/customizing.md) for more details. -There is a probot application available, which allows you to deploy Release -Please as a GitHub App: +## Supporting Monorepos via Manifest Configuration -* [github.com/googleapis/repo-automation-bots](https://github.com/googleapis/repo-automation-bots/tree/main/packages/release-please). +Release Please also supports releasing multiple artifacts from the same repository. +See more at [manifest-releaser.md](docs/manifest-releaser.md). ## Supported Node.js Versions diff --git a/docs/cli.md b/docs/cli.md new file mode 100644 index 000000000..031fbb349 --- /dev/null +++ b/docs/cli.md @@ -0,0 +1,241 @@ +# Running release-please CLI + +Install release-please globally: + +```bash +npm i release-please -g +``` + +## Global options + +These options are available on all commands. + +| Option | Type | Description | +| ------ | ---- | ----------- | +| `--token` | string |REQUIRED. GitHub token with repo write permissions | +| `--repo-url` | string | REQUIRED. GitHub repository in the format of `/` | +| `--api-url` | string | Base URI for making REST API requests. Defaults to `https://api.github.com` | +| `--graphql-url` | string | Base URI for making GraphQL requests. Defaults to `https://api.github.com` | +| `--target-branch` | string |The branch to open release PRs against and tag releases on. Defaults to the default branch of the repository | +| `--dry-run` | boolean | If set, reports the activity that would happen without taking effect | +| `--debug` | boolean | If set, sets log level to >=DEBUG | +| `--trace` | boolean | If set, sets log level to >=TRACE | + +## Bootstrapping + +This command is used to generate the initial `release-please-config.json` +and `.release-please-manifest.json` files or update +them with additional configs. + +It will open a pull request against the target branch with the new +configuration options. + +```bash +release-please bootstrap \ + --token=$GITHUB_TOKEN \ + --repo-url=/ \ + --release-type= [extra options] +``` + +Extra options: + +| Option | Type | Description | +| ------ | ---- | ----------- | +| `--config-file` | `string` | Override the path to the release-please config file. Defaults to `release-please-config.json` | +| `--manifest-file` | `string` | Override the path to the release-please manifest file. Defaults to `.release-please-manifest.json` | +| `--path` | `string` | Path for changes to consider part of this component's release. Defaults to `.` | +| `--package-name` | `string` | Name of the package being released. Defaults to a value determined by the configured release type | +| `--component` | `string` | Name of the component used for branch naming and release tagging. Defaults to a normalized version based on the package name | +| `--release-type` | [`ReleaseType`](/docs/customizing.md#strategy-language-types-supported) | Language strategy that determines which files to update | +| `--initial-version` | `string` | Version string to set as the last released version of this package. Defaults to `0.0.0` | +| `--versioning-strategy` | [`VersioningStrategyType`](/docs/customizing.md#versioning-strategies) | Override method of determining SemVer version bumps based on commits. Defaults to `default` | +| `--bump-minor-pre-major` | `boolean` | Configuration option for the versioning strategy. If set, will bump the minor version for breaking changes for versions < 1.0.0 | +| `--bump-patch-for-minor-pre-major` | `boolean` | Configuration option for the versioning strategy. If set, will bump the patch version for features for versions < 1.0.0 | +| `--draft` | `boolean` | If set, create releases as drafts | +| `--draft-pull-request` | `boolean` | If set, create pull requests as drafts | +| `--label` | `string` | Comma-separated list of labels to apply to the release pull requests. Defaults to `autorelease: pending` | +| `--release-label` | `string` | Comma-separated list of labels to apply to the pull request after the release has been tagged. Defaults to `autorelease: tagged` | +| `--changelog-path` | `string` | Override the path to the managed CHANGELOG. Defaults to `CHANGELOG.md` | +| `--changelog-type` | [`ChangelogType`](/docs/customizing.md#changelog-types) | Strategy for building the changelog contents. Defaults to `default` | +| `--pull-request-title-pattern` | `string` | Override the pull request title pattern. Defaults to `chore${scope}: release${component} ${version}` | +| `--extra-files` | `string[]` | Extra file paths for the release strategy to consider | +| `--version-file` | `string` | Ruby only. Path to the `version.rb` file | + +## Creating/updating release PRs + +```bash +release-please release-pr + --token=$GITHUB_TOKEN \ + --repo-url=/ [extra options] +``` + +### With a manifest config + +If you have a manifest config in your repository, then the release +configurations are pulled from the manifest config file. + +Extra options: + +| Option | Type | Description | +| ------ | ---- | ----------- | +| `--config-file` | string | Override the path to the release-please config file. Defaults to `release-please-config.json` | +| `--manifest-file` | string | Override the path to the release-please manifest file. Defaults to `.release-please-manifest.json` | + +### Without a manifest config + +If you do not have a manifest config in your repository, then you will +need to specify your release options: + +| Option | Type | Description | +| ------ | ---- | ----------- | +| `--path` | string | Path for changes to consider part of this component's release. Defaults to `.` | +| `--package-name` | string | Name of the package being released. Defaults to a value determined by the configured release type | +| `--component` | string | Name of the component used for branch naming and release tagging. Defaults to a normalized version based on the package name | +| `--release-type` | ReleaseType | Language strategy that determines which files to update | +| `--initial-version` | string | Version string to set as the last released version of this package. Defaults to `0.0.0` | +| `--versioning-strategy` | VersioningStrategy | Override method of determining SemVer version bumps based on commits. Defaults to `default` | +| `--bump-minor-pre-major` | boolean | Configuration option for the versioning strategy. If set, will bump the minor version for breaking changes for versions < 1.0.0 | +| `--bump-patch-for-minor-pre-major` | boolean | Configuration option for the versioning strategy. If set, will bump the patch version for features for versions < 1.0.0 | +| `--draft-pull-request` | boolean | If set, create pull requests as drafts | +| `--label` | string | Comma-separated list of labels to apply to the release pull requests. Defaults to `autorelease: pending` |`autorelease: tagged` | +| `--monorepo-tags` | boolean | Add prefix to tags and branches, allowing multiple libraries to be released from the same repository | +| `--pull-request-title-pattern` | `string` | Override the pull request title pattern. Defaults to `chore${scope}: release${component} ${version}` | +| `--signoff` | string | Add [`Signed-off-by`](https://git-scm.com/docs/git-commit#Documentation/git-commit.txt---signoff) line at the end of the commit log message using the user and email provided. (format "Name \") | +| `--extra-files` | `string[]` | Extra file paths for the release strategy to consider | +| `--version-file` | `string` | Ruby only. Path to the `version.rb` file | + +## Creating a release on GitHub + +```bash +release-please github-release \ + --token=$GITHUB_TOKEN + --repo-url=/ [extra options] +``` + +### With a manifest config + +If you have a manifest config in your repository, then the release +configurations are pulled from the manifest config file. + +Extra options: + +| Option | Type | Description | +| ------ | ---- | ----------- | +| `--config-file` | string | Override the path to the release-please config file. Defaults to `release-please-config.json` | +| `--manifest-file` | string | Override the path to the release-please manifest file. Defaults to `.release-please-manifest.json` | + +### Without a manifest config + +If you do not have a manifest config in your repository, then you will +need to specify your release options: + +| Option | Type | Description | +| ------ | ---- | ----------- | +| `--path` | string | Path for changes to consider part of this component's release. Defaults to `.` | +| `--package-name` | string | Name of the package being released. Defaults to a value determined by the configured release type | +| `--component` | string | Name of the component used for branch naming and release tagging. Defaults to a normalized version based on the package name | +| `--release-type` | ReleaseType | Language strategy that determines which files to update | +| `--monorepo-tags` | boolean | Add prefix to tags and branches, allowing multiple libraries to be released from the same repository | +| `--pull-request-title-pattern` | `string` | Override the pull request title pattern. Defaults to `chore${scope}: release${component} ${version}` | +| `--draft` | `boolean` | If set, create releases as drafts | +| `--label` | `string` | Comma-separated list of labels to apply to the release pull requests. Defaults to `autorelease: pending` | +| `--release-label` | `string` | Comma-separated list of labels to apply to the pull request after the release has been tagged. Defaults to `autorelease: tagged` | + +## Create a manifest pull request [deprecated] + +This CLI command is deprecated in favor of `release-pr` which handles this path with the +same options. This command is preserved for backward compatibility and will be removed in the +next major version. + +This command can be run anytime and it will create or update a release PR. It +labels the PR as `"autorelease: pending"` (used by `manifest-release`). + +```bash +❯ release-please manifest-pr --help +release-please manifest-pr + +create a release-PR using a manifest file + +Options: + --help Show help [boolean] + --version Show version number [boolean] + --debug print verbose errors (use only for local debugging). + [boolean] [default: false] + --trace print extra verbose errors (use only for local + debugging). [boolean] [default: false] + --token GitHub token with repo write permissions + --api-url URL to use when making API requests + [string] [default: "https://api.github.com"] + --graphql-url URL to use when making GraphQL requests + [string] [default: "https://api.github.com"] + --default-branch The branch to open release PRs against and tag releases + on [deprecated: use --target-branch instead] [string] + --target-branch The branch to open release PRs against and tag releases + on [string] + --repo-url GitHub URL to generate release for [required] + --dry-run Prepare but do not take action[boolean] [default: false] + --label comma-separated list of labels to add to from release PR + [default: "autorelease: pending"] + --fork should the PR be created from a fork + [boolean] [default: false] + --draft-pull-request mark pull request as a draft [boolean] [default: false] + --signoff Add Signed-off-by line at the end of the commit log + message using the user and email provided. (format "Name + "). [string] + --config-file where can the config file be found in the project? + [default: "release-please-config.json"] + --manifest-file where can the manifest file be found in the project? + [default: ".release-please-manifest.json"] +``` + +### Create a manifest release [deprecated] + +This CLI command is deprecated in favor of `github-release` which handles this path with the +same options. This command is preserved for backward compatibility and will be removed in the +next major version. + +This command should run some time after a release PR has been merged and before +the next release PR is merged. It will create GitHub Releases based on the +last merged release PR it finds (which is why you don't want to let two release +PRs merge w/out running it). If successful it will remove the +`"autorelease: pending"` label and adds the `"autorelease: tagged"` label. +Creating all the releases is not transactional. If any fail to create the +command can be re-run safely to finish creating releases. + +```bash +❯ release-please manifest-release --help +release-please manifest-release + +create releases/tags from last release-PR using a manifest file + +Options: + --help Show help [boolean] + --version Show version number [boolean] + --debug print verbose errors (use only for local debugging). + [boolean] [default: false] + --trace print extra verbose errors (use only for local debugging). + [boolean] [default: false] + --token GitHub token with repo write permissions + --api-url URL to use when making API requests + [string] [default: "https://api.github.com"] + --graphql-url URL to use when making GraphQL requests + [string] [default: "https://api.github.com"] + --default-branch The branch to open release PRs against and tag releases on + [deprecated: use --target-branch instead] [string] + --target-branch The branch to open release PRs against and tag releases on + [string] + --repo-url GitHub URL to generate release for [required] + --dry-run Prepare but do not take action [boolean] [default: false] + --draft mark release as a draft. no tag is created but tag_name and + target_commitish are associated with the release for future + tag creation upon "un-drafting" the release. + [boolean] [default: false] + --label comma-separated list of labels to remove to from release PR + [default: "autorelease: pending"] + --release-label set a pull request label other than "autorelease: tagged" + [string] [default: "autorelease: tagged"] + --config-file where can the config file be found in the project? + [default: "release-please-config.json"] + --manifest-file where can the manifest file be found in the project? + [default: ".release-please-manifest.json"] +``` \ No newline at end of file diff --git a/docs/customizing.md b/docs/customizing.md new file mode 100644 index 000000000..8439aed47 --- /dev/null +++ b/docs/customizing.md @@ -0,0 +1,107 @@ +# Customizing Releases + +release-please provides several configuration options to allow customizing +your release process. + +## Strategy (Language) types supported + +Release Please automates releases for the following flavors of repositories: + +| release type | description +|-------------------|---------------------------------------------------------| +| `dart` | A repository with a pubspec.yaml and a CHANGELOG.md | +| `elixir` | A repository with a mix.exs and a CHANGELOG.md | +| `go` | A repository with a CHANGELOG.md | +| `helm` | A repository with a Chart.yaml and a CHANGELOG.md | +| `krm-blueprint` | [A kpt package, with 1 or more KRM files and a CHANGELOG.md](https://github.com/GoogleCloudPlatform/blueprints/tree/main/catalog/project) | +| `node` | [A Node.js repository, with a package.json and CHANGELOG.md](https://github.com/yargs/yargs) | +| `ocaml` | [An OCaml repository, containing 1 or more opam or esy files and a CHANGELOG.md](https://github.com/grain-lang/binaryen.ml) | +| `php` | A repository with a composer.json and a CHANGELOG.md | +| `python` | [A Python repository, with a setup.py, setup.cfg, CHANGELOG.md](https://github.com/googleapis/python-storage) and optionally a pyproject.toml and a <project>/\_\_init\_\_.py | +| `ruby` | A repository with a version.rb and a CHANGELOG.md | +| `rust` | A Rust repository, with a Cargo.toml (either as a crate or workspace) and a CHANGELOG.md | +| `simple` | [A repository with a version.txt and a CHANGELOG.md](https://github.com/googleapis/gapic-generator) | +| `terraform-module` | [A terraform module, with a version in the README.md, and a CHANGELOG.md](https://github.com/terraform-google-modules/terraform-google-project-factory) | + +### Adding additional strategy types + +To add a new release type, simply use the existing [strategies](https://github.com/googleapis/release-please/tree/main/src/strategies) and [updaters](https://github.com/googleapis/release-please/tree/main/src/updaters) +as a starting point. + +## Versioning Strategies + +A versioning strategy's job is to determine how to increment a SemVer +version given a list of parsed commits. + +| Versioning Strategy | Description | +| ------------------- | ----------- | +| `default` | Breaking changes bump the major version, features bump the minor version, bugfixes bump the patch version | +| `always-bump-patch` | Always bump patch version. This is useful for backporting bugfixes to previous major/minor release branches | +| `service-pack` | Designed for Java backport fixes. Uses Maven's specification for service pack versions (e.g. 1.2.3-sp.1) | + +### Adding additional versioning strategy types + +To add a new versiong strategy, create a new class that implements the +[`VersioningStrategy` interface](/src/versioning-strategy.ts). + +## Changelog Types + +A changelog type's job is to build the CHANGELOG notes given a list +of parsed commits. + +| Changelog Type | Description | +| -------------- | ----------- | +| `default` | Default CHANGELOG notes builder. Groups by commit type and links to pull requests and commits | +| `github` | Uses the GitHub API to generate notes | + +### Adding additional changelog types + +To add a new changelog type, create a new class that implements the +[`ChangelogNotes` interface](/src/changelog-notes.ts). + +## Pull Requests + +### Opening as a draft pull request + +If you would like to open the release pull request as a draft, you can +use the `--draft-pull-request` CLI flag or the `draft-pull-request` option +in the manifest configuration. + +### Pull Request Title + +If you would like to customize the pull request title, you can use the +`--pull-request-title-pattern` CLI option of the `pull-request-title-pattern` +option in the manifest configuration. + +The pattern uses string replacement and regular expressions to build and +parse the pull request title. Note that we must be able to parse out the +component and version from the pull request (either via the pull request +title or body format). + +The default pull request title uses this pattern: +`chore${scope}: release${component} ${version}` so a common release pull +request title would be `chore(main): release foo-bar v1.2.3`. + +| Pattern | Description | +| ------- | ----------- | +| `${scope}` | This pattern is used for specifying the conventional commit scope (e.g. `chore(scope): some message`). We expect that the target branch name is used for the scope value | +| `${component}` | The name of the component being released | +| `${version}` | The version of the component being released | +| `${branch?}` | The target branch of the pull request. If you have multiple release branches, this helps identify which release branch we are working on | + +## Release Lifecycle Labels + +By default, we open release pull requests with the `autorelease: pending` +label. This label along with the branch name of the release pull request +helps us identify merged release pull requests that need to be tagged with a +release. + +After we have tagged the release, we remove the `autorelease: pending` label +and add the `autorelease: tagged` label. + +You can customize the "pending" pull request label(s) via the `--label` CLI +option or the `label` option in the manifest configuration. + +You can customize the "tagged" pull request label(s) via the +`--release-label` CLI option or the `release-label` option in the manifest +configuration. diff --git a/docs/manifest-releaser.md b/docs/manifest-releaser.md index e6cef61b4..f7064e4ef 100644 --- a/docs/manifest-releaser.md +++ b/docs/manifest-releaser.md @@ -4,16 +4,40 @@ release-please can be setup to use source controlled files containing releaser specific configuration (the `release-please-config.json`) as well package version tracking (the `.release-please-manifest.json`). - The motivation of the manifest-based releaser is support for monorepos: * a combined [Release PR](https://github.com/googleapis/release-please#whats-a-release-pr) will be created for all configured packages. * release configuration for potentially hundreds of libraries is combined in two configuration files. -Note: currently only `node`, `python`, and `rust` release types are supported. +Although originally designed for repositories that contain multiple releasable artifacts, it also +supports single artifact workflows just as easily. ## Quick Start +### Bootstrap with CLI + +Step 1: Install release-please CLI + +```bash +npm i release-please -g +``` + +Step 2: Bootstrap a release configuration + +```bash +release-please bootstrap \ + --token=$GITHUB_TOKEN \ + --repo-url=/ \ + --release-type= [extra options] +``` + +This will open a pull request that configures the initial +`release-please-config.json` and `.release-please-manifest.json` files. + +For the full options, see the [CLI documentation](/docs/cli.md#bootstrapping). + +### Bootstrap manually + Create a minimal `release-please-config.json`, e.g., for a single JS package: ```js { @@ -26,12 +50,12 @@ Create a minimal `release-please-config.json`, e.g., for a single JS package: Create an empty `.release-please-manifest.json` Commit/push/merge these to your remote GitHub repo (using either the repo's -default branch or a test branch in which case you'll use the `--default-branch` +default branch or a test branch in which case you'll use the `--target-branch` flag in the next step). Run release-please: ```sh -release-please [--token=your/apikey.txt] [--default-branch=testing] manifest-pr +release-please [--token=your/apikey.txt] [--target-branch=testing] release-pr ``` The resulting PR will assume a default starting version for your package @@ -41,19 +65,22 @@ changelog generation. If that is not the desired behavior for your first release PR, read on! -### Bootstrapping +#### Bootstrapping + There are two items to consider when running release-please for the first time: 1. which commit to start at (i.e. how much to include in your next changelog entry) 2. what version release-please should propose in this first release PR -#### Starting commit +##### Starting commit + You can add a top level `"bootstrap-sha": ` key/value entry to the config which will cause release-please to stop there for collecting changelog commits (so choose one commit earlier than the first commit you want to include). Note: once a release-please generated PR has been merged, this config value will be ignored for all subsequent runs and can be removed. -#### Initial Version +# #### Initial Version + The simplest way to tell release-please the current version for a package it has never released before is to manually add an entry into `.release-please-manifest.json`. This change should be made directly on the @@ -216,13 +243,13 @@ documented in comments) ## Manifest -At a minimum, a manifest file must exist at the tip of the `--default-branch`. +At a minimum, a manifest file must exist at the tip of the `--target-branch`. It can be empty when release-please is run for the first time but it must exist. Manually editing the manifest is only appropriate in the bootstrap case outlined above. release-please will record a new version into the manifest file for each package it is configured to release. -Once the first release PR has been merged, subsequent `manifest-pr` runs will +Once the first release PR has been merged, subsequent `release-pr` runs will retrieve the content of the manifest at the commit corresponding to that merged PR. It will use this to find the last-released version for each package. It will only read the manifest versions at the tip of the default/configured branch if @@ -281,54 +308,10 @@ jobs: run: npx lerna publish from-package --no-push --no-private --yes ``` -## CLI usage -The commands available for this mode are `manifest-pr` and `manifest-release` - -They both take the following optional flags: -```sh -❯ release-please manifest-pr --help -release-please manifest-pr - -create a release-PR using a manifest file - -Options: - --help Show help [boolean] - --version Show version number [boolean] - --debug print verbose errors (use only for local - debugging). [boolean] [default: false] - --token GitHub token with repo write permissions - --api-url URL to use when making API requests - [string] [default: "https://api.github.com"] - --default-branch The branch to open release PRs against and tag - releases on [string] - --fork should the PR be created from a fork - [boolean] [default: false] - --repo-url GitHub URL to generate release for [required] - --config-file where can the config file be found in the - project? [default: "release-please-config.json"] - --manifest-file where can the manifest file be found in the - project? - [default: ".release-please-manifest.json"] -``` - -### `manifest-pr` - -This command can be run anytime and it will create or update a release PR. It -labels the PR as `"autorelease: pending"` (used by `manifest-release`). - -### `manifest-release` - -This command should run some time after a release PR has been merged and before -the next release PR is merged. It will create GitHub Releases based on the -last merged release PR it finds (which is why you don't want to let two release -PRs merge w/out running it). If successful it will remove the -`"autorelease: pending"` label and adds the `"autorelease: tagged"` label. -Creating all the releases is not transactional. If any fail to create the -command can be re-run safely to finish creating releases. - ### Releasing Root Path of Library (".") -One use-case that arose for [googleapis](https://github.com/googleapis/google-api-nodejs-client), was the need to publish individual libraries along +One use-case that arose for [googleapis](https://github.com/googleapis/google-api-nodejs-client), +was the need to publish individual libraries along with a combined version of the library, i.e., * an individual library for `@googleapis/youtube`, `@googleapis/sheets`, etc. @@ -355,15 +338,15 @@ plugin must already be implemented, see below) ### Plugin implementation A `ManifestPlugin` instance has these resources avilable: -- `this.gh`: a `GitHub` instance for any API operations it might want to perform -- `this.config`: a `Config` object representing all the packages configured for the monorepo +- `this.github`: a `GitHub` instance for any API operations it might want to perform +- `this.repositoryConfig`: a `RepositoryConfig` object representing all the packages + configured for the monorepo +- `this.targetBranch`: a `string` representing the target branch of the release -It must implement a `run` method which receives two arguments: -- the latest versions of all packages (ultimately be written to the manifest) -- an array of the mapping of package-to-currently-proposed-changes -and makes any modifications, additions, or deletions to either argument (in -addition to any other out-of-band side effect) and returns both (potentially -modified) arguments in a tuple. +It must implement a `run` method which receives one argument (an array containing the +candidate release pull requests) and returns an array of post-processed candidate +pull requests. The plugin may choose to merge multiple pull requests into an +aggregate pull request. For example, a very basic plugin that simply logs the number of packages currently appearing in the release written as `src/plugins/num-packages.ts`: @@ -374,21 +357,19 @@ import {CheckpointType} from '../util/checkpoint'; export default class LogNumberPkgsReleased extends ManifestPlugin { async run( - newManifestVersions: VersionsMap, - pkgsWithPRData: ManifestPackageWithPRData[] + pullRequests: CandidateReleasePullRequest[] ): Promise<[VersionsMap, ManifestPackageWithPRData[]]> { - this.log( - `Number of packages to release: ${pkgsWithPRData.length}`, - CheckpointType.Success + logger.info( + `Number of packages to release: ${pullRequests.length}` ); - return [newManifestVersions, pkgsWithPRData]; + return pullRequests; } } ``` The `num-packages` plugin is not very interesting. Also, if it is not last in the `"plugins"` configuration array, it might not be accurate (a subsequent -plugin could add or remove entries to/from `pkgsWithPRData`) +plugin could add or remove entries to/from `pullRequests`) However, one place a plugin has particular value is in a monorepo where local packages depend on the latest version of each other (e.g. yarn/npm workspaces diff --git a/package.json b/package.json index d5ef61885..c2332dca1 100644 --- a/package.json +++ b/package.json @@ -73,6 +73,7 @@ "conventional-changelog-conventionalcommits": "^4.6.0", "conventional-changelog-writer": "^5.0.0", "conventional-commits-filter": "^2.0.2", + "detect-indent": "^6.1.0", "figures": "^3.0.0", "js-yaml": "^4.0.0", "node-html-parser": "^5.0.0", @@ -82,8 +83,7 @@ "typescript": "^3.8.3", "unist-util-visit": "^2.0.3", "unist-util-visit-parents": "^3.1.1", - "yargs": "^17.0.0", - "detect-indent": "^6.1.0" + "yargs": "^17.0.0" }, "engines": { "node": ">=12.18.0" diff --git a/src/bin/release-please.ts b/src/bin/release-please.ts index 387cef061..0fffba24e 100644 --- a/src/bin/release-please.ts +++ b/src/bin/release-please.ts @@ -591,8 +591,10 @@ const bootstrapCommand: yargs.CommandModule<{}, BootstrapArgs> = { command: 'bootstrap', describe: 'configure release manifest', builder(yargs) { - return manifestOptions( - releaseOptions(pullRequestStrategyOptions(gitHubOptions(yargs))) + return manifestConfigOptions( + manifestOptions( + releaseOptions(pullRequestStrategyOptions(gitHubOptions(yargs))) + ) ) .option('initial-version', { description: 'current version',