From b724f14e74204fec72eeb39fb79a40b3db97ab1d Mon Sep 17 00:00:00 2001 From: Jeff Ching Date: Tue, 15 Nov 2022 14:28:25 -0800 Subject: [PATCH 1/3] docs: add troubleshooting page --- README.md | 4 ++ docs/troubleshooting.md | 105 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 109 insertions(+) create mode 100644 docs/troubleshooting.md diff --git a/README.md b/README.md index 84a949f22..a9b1c3908 100644 --- a/README.md +++ b/README.md @@ -219,6 +219,10 @@ Contributions welcome! See the [Contributing Guide](https://github.com/googleapi For more information on the design of the library, see [design](https://github.com/googleapis/release-please/blob/main/docs/design.md). +## Troubleshooting + +For common issues and help troubleshooting your configuration, see [Troubleshooting](https://github.com/googleapis/release-please/blob/main/docs/troubleshooting.md). + ## License Apache Version 2.0 diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md new file mode 100644 index 000000000..f07b034ba --- /dev/null +++ b/docs/troubleshooting.md @@ -0,0 +1,105 @@ +# Troubleshooting + +## Debugging with the CLI + +The easiest way to debug your `release-please` configuration is to use the bundled +CLI. + +To use the CLI, you will need to use a GitHub personal access token: + +```bash +export GITHUB_TOKEN="my-access-token" +release-please release-pr \ + --token=${GITHUB_TOKEN} \ + --repo-url=my-owner/my-repo \ + --debug \ + --dry-run +``` + +The CLI provides a `--dry-run` mode which will tell you what it would do without +actually doing it (i.e. without opening a pull request or tagging releases). +Additionally, we provide log level options `--debug` or `--trace` which will +show more in-depth logging and should help give you insight into what `release-please` +is trying to do. + +### Testing in another branch + +When testing out a new change to the `release-please-config.json`, make the change +in a new branch on the actual repository (not a fork). `release-please` relies on +pull requests, releases, and tags which are not copied when you fork the original +repository. + +After pushing your change to the new branch, you can target the new branch using +the `--target-branch` option. + +```bash +export GITHUB_TOKEN="my-access-token" +release-please release-pr \ + --token=${GITHUB_TOKEN} \ + --repo-url=my-owner/my-repo \ + --target-branch=my-test-branch \ + --debug \ + --dry-run +``` + +## Frequently Asked Questions + +### What is a component? + +A component is an individually releasable artifact or group of +artifacts within a repository. + +The most common configuration is for a single repository to +release a single package. In this case, the releases and tags +with have simple versions like `v1.2.3`. In this case, you +will not need to configure a `component` in the configuration. + +In the case of a monorepo, you may have separate, independently +releaseable artifacts. In this case, the releases will use a +`component` prefix for the release and tag like +`my-component-v1.2.3`. This allows you to have separate releases +and tags for each component for version `1.2.3`. + +You will need to configure a `component` name in the manifest +config for each of your independent modules (separated by +code path): + +```json +{ + "packages": { + "path/to/pkg-a": { + "component": "pkg-a" + }, + "path/to/pkg-b": { + "component": "pkg-b" + } + } +} +``` + +### How does release-please determine the previous release? + +#### If you are using a manifest config (highly advised) + +`release-please` reads the latest released version from the +manifest file (`.release-please-manifest.json`). The file is a map +of component path to the latest release version. In a single +component setup, the path should be `.`. `release-please` tries to +identify the commit SHA of that release version by looking at +recent releases and falling back to looking at the expected tag name. + +#### If you are NOT using a manifest config + +`release-please` uses a few methods to try determine the latest +release. Note that this process can be fragile and will require +more API calls (which is one reason a manifest config is preferred). + +1. Iterate through the last 250 commits on the target branch and + look for an associated release pull request. If found, extract + the latest release version from that pull request. +2. Iterate through the latest releases and compare against commit + SHAs seen in the last 250 commits on the target branch. This + is to ensure that the release happened on this target branch. +3. Iterate through the latest tags and compare against commit + SHAs seen in the last 250 commits on the branch. This is to + ensure that the tag happened on this target branch. From eeae5ef591e020197c41fe4027e18cc006d3c535 Mon Sep 17 00:00:00 2001 From: Jeff Ching Date: Mon, 21 Nov 2022 13:24:48 -0800 Subject: [PATCH 2/3] docs: add link to personal access token --- docs/troubleshooting.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index f07b034ba..bdb44d3b7 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -5,7 +5,8 @@ The easiest way to debug your `release-please` configuration is to use the bundled CLI. -To use the CLI, you will need to use a GitHub personal access token: +To use the CLI, you will need to use a GitHub +[personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token): ```bash export GITHUB_TOKEN="my-access-token" From ce12253c22e4b6409e04b13982d5d043f648b2fa Mon Sep 17 00:00:00 2001 From: Jeff Ching Date: Mon, 21 Nov 2022 13:25:28 -0800 Subject: [PATCH 3/3] docs: add install command --- docs/troubleshooting.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index bdb44d3b7..ae436d190 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -9,6 +9,9 @@ To use the CLI, you will need to use a GitHub [personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token): ```bash +# install the release-please binary +npm install -g release-please + export GITHUB_TOKEN="my-access-token" release-please release-pr \ --token=${GITHUB_TOKEN} \