You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/source/get_started/making_release_from_releaser.md
+18Lines changed: 18 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -11,9 +11,13 @@ already uses Jupyter Releaser.
11
11
## Set up
12
12
13
13
- Fork `jupyter_releaser`
14
+
14
15
- 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
16
+
15
17
- 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.
18
+
16
19
- 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.
20
+
17
21
- You can store the token as `PYPI_TOKEN` in your fork's `Secrets`.
18
22
19
23
- 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:
@@ -35,8 +39,11 @@ already uses Jupyter Releaser.
35
39
## Prep Release
36
40
37
41
- Go to the "Actions" tab in your fork of `jupyter_releaser`
42
+
38
43
- Select the "Step 1: Prep Release" workflow on the left
44
+
39
45
- Click on the "Run workflow" dropdown button on the right
- Review the contents, fixing typos or otherwise editing as necessary.
72
+
65
73
- 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.
66
74
67
75
## Publish Release
68
76
69
77
- Return to your fork of `jupyter_releaser`
78
+
70
79
- Click on the "Actions" tab
80
+
71
81
- Select the "Publish Release" workflow on the left
82
+
72
83
- Click on the "Run workflow" button on the right
84
+
73
85
- Fill in the target repository
86
+
74
87
- (Optional) Fill in draft GitHub Release URL given by the Changelog PR.
75
88
If you leave it blank it will use the most recent draft GitHub release.
- The workflow will finish the GitHub release and publish assets to the appropriate registries.
93
+
80
94
- 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.
95
+
81
96
- 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.
82
97
83
98
84
99
85
100
- **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
86
101
and move into asset publish.
102
+
87
103
- **Note** GitHub Actions caches the secrets used on a given workflow run. So if you run into an auth issue, you'll
88
104
need to run a new workflow instead of re-running the existing workflow.
105
+
89
106
- Review and merge the forward-port PR if applicable
- The "New Version Spec" will usually be the full version (e.g. 0.7.1). Repos using `tbump` can also use:
24
+
21
25
- "next" or "patch" option, which will bump the micro version (or the build version in the case of a prerelease).
22
26
Note: The "next" and "patch" options are not available when using dev versions, you must use explicit versions
23
27
instead.
24
28
- "minor" option, which will bump to the next minor version directly.
25
29
- "release" option, which will start making prereleases (a0, a1...)
30
+
26
31
- Use the "since" field to select PRs prior to the latest tag to include in the release
32
+
27
33
- Type "true" in the "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.
34
+
28
35
- The additional "Post Version Spec" field should be used if your repo uses a dev version (e.g. 0.7.0.dev0)
36
+
29
37
- The workflow will use the GitHub API to find the relevant pull requests and make an appropriate changelog entry.
38
+
30
39
- The workflow will create a draft GitHub release to the target
31
40
repository and branch, with the draft changelog contents.
32
41
@@ -39,27 +48,36 @@ already uses Jupyter Releaser using workflows on its own repository.
- Review the contents, fixing typos or otherwise editing as necessary.
51
+
42
52
- 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.
43
53
44
54
## Publish Release
45
55
46
56
- Return to "Actions" tab for the repository
57
+
47
58
- Select the "Publish Release" workflow on the left
59
+
48
60
- Click on the "Run workflow" button on the right
61
+
49
62
- (Optional) Fill in draft GitHub Release URL given by the Changelog PR.
50
63
If you leave it blank it will use the most recent draft GitHub release.
- The workflow will finish the GitHub release and publish assets to the appropriate registries.
68
+
55
69
- 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.
70
+
56
71
- 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.
57
72
58
73
59
74
60
75
-**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
61
76
and move into asset publish.
77
+
62
78
-**Note** GitHub Actions caches the secrets used on a given workflow run. So if you run into an auth issue, you'll
63
79
need to run a new workflow instead of re-running the existing workflow.
80
+
64
81
- Review and merge the forward-port PR if applicable
Copy file name to clipboardExpand all lines: docs/source/how_to_guides/convert_repo_from_releaser.md
+9-7Lines changed: 9 additions & 7 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -17,13 +17,15 @@ See checklist below for details:
17
17
A. Prep the `jupyter_releaser` fork:
18
18
19
19
-[ ] Clone this repository onto your GitHub user account.
20
+
20
21
-[ ] Add a GitHub [personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) with access to target GitHub repo to run
21
-
GitHub Actions, saved as `ADMIN_GITHUB_TOKEN` in the
The token will need "public_repo", and "repo:status" permissions.
25
+
24
26
-[ ] Add access token for the [PyPI registry](https://packaging.python.org/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/#saving-credentials-on-github) stored as `PYPI_TOKEN`.
25
-
_Note_ For security reasons, it is recommended that you scope the access
26
-
to a single repository, and use a variable called `PYPI_TOKEN_MAP` that is formatted as follows:
27
+
_Note_ For security reasons, it is recommended that you scope the access
28
+
to a single repository, and use a variable called `PYPI_TOKEN_MAP` that is formatted as follows:
27
29
28
30
```text
29
31
owner1/repo1,token1
@@ -47,7 +49,7 @@ B. Prep target repository:
47
49
- Note that [directives](https://myst-parser.readthedocs.io/en/latest/using/syntax.html#syntax-directives) can still be used
48
50
-[ ] Add HTML start and end comment markers to Changelog file - see example in [CHANGELOG.md](https://github.com/jupyter-server/jupyter_releaser/blob/main/CHANGELOG.md) (view in raw mode)
49
51
-[ ] We recommend using [hatch](https://hatch.pypa.io/latest/) for your
50
-
build system and for version handling.
52
+
build system and for version handling.
51
53
- If previously providing `version_info` like `version_info = (1, 7, 0, '.dev', '0')`, use a pattern like the one below in your version file:
52
54
53
55
```toml
@@ -94,7 +96,7 @@ version_info = tuple(parts)
94
96
````
95
97
96
98
- [ ] Add a workflow that uses the [`enforce-label`](https://github.com/jupyterlab/maintainer-tools#enforce-labels) action from `jupyterlab/maintainer-tools` to ensure that all PRs have on of the triage labels used to
97
-
categorize the changelog.
99
+
categorize the changelog.
98
100
99
101
- [ ] Update or add `RELEASE.md` that describes the onboarding and release process, e.g. [jupyter_server](https://github.com/jupyter-server/jupyter_server/blob/main/RELEASE.md).
Copy file name to clipboardExpand all lines: docs/source/how_to_guides/convert_repo_from_repo.md
+16-16Lines changed: 16 additions & 16 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,7 +4,7 @@ Follow the steps below to convert a repository to use Jupyter Releaser for relea
4
4
5
5
## Prerequisites
6
6
7
-
See [hecklist below for details:
7
+
See \[hecklist below for details:
8
8
9
9
- Markdown changelog
10
10
- Bump version configuration (if using Python), for example [hatch](https://hatch.pypa.io/latest/)
@@ -15,28 +15,28 @@ See [hecklist below for details:
15
15
## Checklist for Adoption
16
16
17
17
-[ ] Add a GitHub [personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token), preferably from a "machine user" GitHub
18
-
account that has admin access to the repository. The token itself will
19
-
need "public_repo", and "repo:status" permissions. Save the token as
20
-
`ADMIN_GITHUB_TOKEN`
21
-
in the [repository secrets](https://docs.github.com/en/actions/reference/encrypted-secrets#creating-encrypted-secrets-for-a-repository). We need this
22
-
access token to allow for branch protection rules, which block the pushing
23
-
of commits when using the `GITHUB_TOKEN`, even when run from an admin user
24
-
account.
18
+
account that has admin access to the repository. The token itself will
19
+
need "public_repo", and "repo:status" permissions. Save the token as
20
+
`ADMIN_GITHUB_TOKEN`
21
+
in the [repository secrets](https://docs.github.com/en/actions/reference/encrypted-secrets#creating-encrypted-secrets-for-a-repository). We need this
22
+
access token to allow for branch protection rules, which block the pushing
23
+
of commits when using the `GITHUB_TOKEN`, even when run from an admin user
24
+
account.
25
25
-[ ] Add access token for the [PyPI registry](https://packaging.python.org/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/#saving-credentials-on-github) stored as `PYPI_TOKEN`.
26
-
_Note_ For security reasons, it is recommended that you scope the access
27
-
to a single repository. Additionally, this token should belong to a
28
-
machine account and not a user account.
26
+
_Note_ For security reasons, it is recommended that you scope the access
27
+
to a single repository. Additionally, this token should belong to a
28
+
machine account and not a user account.
29
29
-[ ] If needed, add access token for [npm](https://docs.npmjs.com/creating-and-viewing-access-tokens), saved as `NPM_TOKEN`. Again this should
30
-
be created using a machine account that only has publish access.
30
+
be created using a machine account that only has publish access.
31
31
-[ ] Ensure that only trusted users with 2FA have admin access to the
32
-
repository, since they will be able to trigger releases.
32
+
repository, since they will be able to trigger releases.
33
33
-[ ] Switch to Markdown Changelog
34
34
- We recommend [MyST](https://myst-parser.readthedocs.io/en/latest/?badge=latest), especially if some of your docs are in reStructuredText.
35
35
- Can use `pandoc -s changelog.rst -o changelog.md` and some hand edits as needed.
36
36
- Note that [directives](https://myst-parser.readthedocs.io/en/latest/using/syntax.html#syntax-directives) can still be used
37
37
-[ ] Add HTML start and end comment markers to Changelog file - see example in [CHANGELOG.md](https://github.com/jupyter-server/jupyter_releaser/blob/main/CHANGELOG.md) (view in raw mode)
38
38
-[ ] We recommend using [hatch](https://hatch.pypa.io/latest/) for your
39
-
build system and for version handling.
39
+
build system and for version handling.
40
40
- If previously providing `version_info` like `version_info = (1, 7, 0, '.dev', '0')`, use a pattern like the one below in your version file:
41
41
42
42
```toml
@@ -81,7 +81,7 @@ version_info = tuple(parts)
81
81
```
82
82
83
83
- [ ] Add a workflow that uses the [`enforce-label`](https://github.com/jupyterlab/maintainer-tools#enforce-labels) action from `jupyterlab/maintainer-tools` to ensure that all PRs have on of the triage labels used to
84
-
categorize the changelog.
84
+
categorize the changelog.
85
85
86
86
- [ ] Update or add `RELEASE.md` that describes the onboarding and release process, e.g. [jupyter_server](https://github.com/jupyter-server/jupyter_server/blob/main/RELEASE.md).
87
87
@@ -96,7 +96,7 @@ version_info = tuple(parts)
96
96
- [ ] Try out the `Prep Release` and `Publish Release` process against a fork of the target repo first so you don't accidentally push tags and GitHub releases to the source repository. Set the `TWINE_REPOSITORY_URL` environment variable to `https://test.pypi.org/legacy/` in the "Finalize Release" action part of the workflow
97
97
98
98
- [ ] Try the `Publish Release` process using a prerelease version on the main
0 commit comments