# Making Your First Release from Jupyter Releaser
This guide covers creating your first release on a repository that
already uses Jupyter Releaser.
## Prerequisites
- Write access to the target repository
- Publish access to PYPI and/or npm assets associated with the repo
## Set up
- Fork `jupyter_releaser`
- Generate a [GitHub Access token](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) with access to target GitHub repo to run GitHub Actions
- Add the token as `ADMIN_GITHUB_TOKEN` in the [repository secrets](https://docs.github.com/en/actions/reference/encrypted-secrets#creating-encrypted-secrets-for-a-repository) of your fork. The token must have `repo` and `workflow` scopes.
- Set up PyPI:
Using PyPI token (legacy way)
- If the repo generates PyPI release(s), create a scoped PyPI [token](https://packaging.python.org/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/#saving-credentials-on-github). We recommend using a scoped token for security reasons.
- You can store the token as `PYPI_TOKEN` in your fork's `Secrets`.
- Advanced usage: if you are releasing multiple repos, you can create a secret named `PYPI_TOKEN_MAP` instead of `PYPI_TOKEN` that is formatted as follows:
```text
owner1/repo1,token1
owner2/repo2,token2
```
If you have multiple Python packages in the same repository, you can point to them as follows:
```text
owner1/repo1/path/to/package1,token1
owner1/repo1/path/to/package2,token2
```
Using PyPI trusted publisher (modern way)
- Set up your PyPI project by [adding a trusted publisher](https://docs.pypi.org/trusted-publishers/adding-a-publisher/)
- if you use the example workflows, the _workflow name_ is `publish-release.yml` (or `full-release.yml`) and the
_environment_ should be left blank.
- Ensure the publish release job as `permissions`: `id-token : write` (see the [documentation](https://docs.pypi.org/trusted-publishers/using-a-publisher/))
- If the repo generates npm release(s), add access token for [npm](https://docs.npmjs.com/creating-and-viewing-access-tokens), saved as `NPM_TOKEN` in "Secrets".
> If you want to set _provenance_ on your package, you need to ensure the publish release job as `permissions`: `id-token : write` (see the [documentation](https://docs.npmjs.com/generating-provenance-statements#publishing-packages-with-provenance-via-github-actions)).
## Prep Release
- Go to the "Actions" tab in your fork of `jupyter_releaser`
- Select the "Step 1: Prep Release" workflow on the left
- Click on the "Run workflow" dropdown button on the right
- Fill in the appropriate parameters
![Prep Release Workflow Dialog](../images/prep_release.png)
- The "New Version Spec" will usually be the full version (e.g. 0.7.1). Repos using `tbump` can also use the "next" or "patch"
option, which will bump the micro version (or the build version in the case of a prerelease). The "minor" option allows projects using "tbump" to bump
to the next minor version directly. Note: The "next" and "patch" options
are not available when using dev versions, you must use explicit versions
instead.
- Use the "since" field to select PRs prior to the latest tag to include in the release
- Check "Use PRs with activity since the last stable git tag" if you would like to include PRs since the last non-prerelease version tagged on the target repository and branch.
- Check "Set a placeholder in the changelog and don't publish the release" if
you want to carry a silent release (e.g. in case of a security release).
That option will change the default behavior by keeping the version
changelog only in the GitHub release and keeping it private (aka in _Draft_
state). The changelog file will only contains a placeholder to be replaced
by the release body once the maintainers have chosen to publish the release.
- The additional "Post Version Spec" field should be used if your repo uses a dev version (e.g. 0.7.0.dev0)
- The workflow will use the GitHub API to find the relevant pull requests and make an appropriate changelog entry.
- The workflow will create a draft GitHub release to the target
repository and branch, with the draft changelog contents.
![Prep Release Changelog Workflow Next Step](../images/prep_release_next_step.png)
## Review Changelog
- Go to the draft GitHub Release created by the "Prep Release" workflow
![Draft GitHub Release](../images/draft_github_release.png)
- Review the contents, fixing typos or otherwise editing as necessary.
- If there is a section called "Other Merged PRs", it means those PRs did not have one of the appropriate labels. If desired, you can go label those PRs and then re-run the workflow, or move the entries manually to the desired section. The appropriate labels are: bug, maintenance, enhancement, feature, and documentation.
## Publish Release
- Return to your fork of `jupyter_releaser`
- Click on the "Actions" tab
- Select the "Publish Release" workflow on the left
- Click on the "Run workflow" button on the right
- Fill in the target repository
- (Optional) Fill in draft GitHub Release URL given by the Changelog PR.
If you leave it blank it will use the most recent draft GitHub release.
![Publish Release Workflow Dialog](../images/publish_release.png)
- The workflow will finish the GitHub release and publish assets to the appropriate registries.
- If the workflow is not targeting the default branch, it will also generate a forward-port pull request for the changelog entry to the default branch.
- When the workflow finishes it will print a link to the GitHub release and the forward-port PR (if appropriate) in the "\*\* Next Step \*\*" output.
![Publish Release Workflow Next Step](../images/publish_release_next_step.png)
- **Note** If the publish portion fails you can attempt to publish the draft GitHub release given by the URL in the "\*\* Failure Message \*\*" using the "Publish Release" workflow again. It will skip past the asset creation phase
and move into asset publish.
- **Note** GitHub Actions caches the secrets used on a given workflow run. So if you run into an auth issue, you'll
need to run a new workflow instead of re-running the existing workflow.
- Review and merge the forward-port PR if applicable
- Announce the release on appropriate channels