Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: add troubleshooting page (#1752)
* docs: add troubleshooting page * docs: add link to personal access token * docs: add install command
- Loading branch information
Showing
2 changed files
with
113 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,109 @@ | ||
# 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](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} \ | ||
--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. |