Skip to content

Commit 47c293c

Browse files
author
Steven Silvester
authored
Merge pull request #171 from blink1073/organize-docs
Reorganize docs
2 parents 9c9902b + 0f3098b commit 47c293c

33 files changed

+435
-180
lines changed

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -133,3 +133,6 @@ dmypy.json
133133

134134
# macOS
135135
.DS_Store
136+
137+
# Copied changelog
138+
docs/source/**/changelog.md

‎README.md‎

Lines changed: 0 additions & 175 deletions
Original file line numberDiff line numberDiff line change
@@ -1,105 +1,7 @@
11
# Jupyter Releaser
22

3-
** Experimental! **
4-
53
**Jupyter Releaser** contains a set of helper scripts and GitHub Actions to aid in automated releases of Python and npm packages.
64

7-
## Motivation
8-
9-
This project should help maintainers reduce toil and save time in the release process by enforcing best practices to:
10-
11-
- Automate a changelog for every release
12-
- Pre-publish to test server and verify the install and import of dist asset(s)
13-
- Commit a message with hashes of dist file(s)
14-
- Annotate the git tag in standard format
15-
- Create a GitHub release with changelog entry
16-
- Verify url links in markdown and reStructuredText files
17-
- Verify integrity of Python manifest
18-
- Forward port changelog entries into default branch
19-
- Dry run publish on CI
20-
- Revert to Dev version after release (optional)
21-
22-
## Prerequisites
23-
24-
See [checklist](#Checklist-for-Adoption) below for details:
25-
26-
- Markdown changelog
27-
- Bump version configuration (if using Python), for example [tbump](https://github.com/dmerejkowsky/tbump)
28-
- [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.
29-
- 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)
30-
- If needed, access token for [npm](https://docs.npmjs.com/creating-and-viewing-access-tokens).
31-
32-
## Typical Workflow
33-
34-
When ready to make a release:
35-
36-
1. Fork the `jupyter-releaser` repo and go to the Actions panel
37-
2. Select the `Draft Changelog` workflow
38-
3. Run the workflow with the version spec (usually the new version number). If making a final release after
39-
a prerelease series, you may wish to use the "until" parameter to include all the PRs since the last final release.
40-
41-
<p align="center">
42-
<img src="media/draft_changelog_workflow.png" alt="Draft Changelog Workflow"
43-
title="Draft Changelog Workflow" width="50%"/>
44-
</p>
45-
46-
4. When the run completes, review the changelog PR that was opened and make any desired edits.
47-
48-
<p align="center">
49-
<img src="media/draft_changelog_next_step.png" alt="Draft Changelog Next Step"
50-
title="Draft Changelog Next Step" width="50%"/>
51-
</p>
52-
53-
<p align="center">
54-
<img src="media/draft_changelog_pr.png" alt="Draft Changelog Pull Request"
55-
title="Draft Changelog Pull Request" width="50%"/>
56-
</p>
57-
58-
5. Merge the PR
59-
6. Return to the Actions panel in the `jupyter-releaser` fork
60-
7. Select the `Draft Release` workflow
61-
62-
<p align="center">
63-
<img src="media/draft_release_workflow.png" alt="Draft Release Workflow"
64-
title="Draft Release Workflow" width="50%"/>
65-
</p>
66-
67-
8. Run the workflow with the same version spec as before, and optionally, a post version spec if you want to go back to a dev version in the target branch. Make sure to use the same "until" parameter used in "Draft Changelog", if applicable.
68-
9. When the workflow completes, go to the releases page in the target repository and verify that the new draft release is there with the correct changelog and dist files.
69-
70-
<p align="center">
71-
<img src="media/draft_release_next_step.png" alt="Draft Release Next Step"
72-
title="Draft Release Workflow" width="50%"/>
73-
</p>
74-
75-
<p align="center">
76-
<img src="media/draft_github_release.png" alt="Draft GitHub Release"
77-
title="Draft GitHub Release" width="50%"/>
78-
</p>
79-
80-
10. Copy the url of the draft release.
81-
11. Run the `Publish Release` workflow from the `jupyter-releaser` fork.
82-
83-
<p align="center">
84-
<img src="media/publish_release_workflow.png" alt="Publish Release Workflow"
85-
title="Publish Release Workflow" width="50%"/>
86-
</p>
87-
88-
<p align="center">
89-
<img src="media/publish_release_next_step.png" alt="Publish Release Next Step"
90-
title="Publish Release Next Step" width="50%"/>
91-
</p>
92-
93-
<p align="center">
94-
<img src="media/final_github_release.png" alt="Final GitHub Release"
95-
title="Final GitHub Release" width="50%"/>
96-
</p>
97-
98-
12. If the release was on a backport branch, a forward port PR will have been opened against
99-
the default branch with the new changelog entry. Review and merge this PR.
100-
101-
<!-- TODO: Add forward port PR image here -->
102-
1035
## Installation
1046

1057
To install the latest release locally, make sure you have
@@ -117,83 +19,6 @@ To install the latest release locally, make sure you have
11719
jupyter-releaser check-links --help
11820
```
11921

120-
## Configuration
121-
122-
### Command Options and Environment Variables
123-
124-
All of the commands support CLI and Environment Variable Overrides.
125-
The environment variables are defined by the `envvar` parameters in the
126-
command options in `cli.py`. The environment variables unique to
127-
`jupyter-releaser` are prefixed with `RH_`. A list of all env variables can be seen
128-
by running `jupyter-releaser list-envvars`.
129-
130-
### Default Values, Options, Skip, and Hooks
131-
132-
The default values can also be overriden using a config file.
133-
134-
Options can be overridden using the `options` section.
135-
136-
You can skip one or more commands using a `skip` section, which is a list of
137-
commands to skip.
138-
139-
You can also define hooks to run before and after
140-
commands in a `hooks` section. Hooks can be a shell command to run or
141-
a list of shell commands, and are specified to run `before-` or `after-`
142-
a command.
143-
Note: the only unusable hook names are `before-prep-git` and `before-extract-release`, since a checkout of the target repository is not yet available at that point.
144-
145-
### Configuration File Priority
146-
147-
This is where `jupyter-releaser` looks for configuration (first one found is used):
148-
149-
```code
150-
.jupyter-releaser.toml
151-
pyproject.toml (in the tools.jupyter-releaser section )
152-
package.json (in the jupyter-releaser property)
153-
```
154-
155-
Example `.jupyter-releaser.toml`:
156-
157-
```toml
158-
[options]
159-
dist_dir = "mydist"
160-
161-
skip = ["check-links"]
162-
163-
[hooks]
164-
before-tag-version = "npm run pre:tag:script"
165-
```
166-
167-
Example `pyproject.toml` section:
168-
169-
```toml
170-
[tools.jupyter-releaser.options]
171-
dist_dir = "mydist"
172-
173-
[tools.jupyter-releaser]
174-
skip = ["check-links"]
175-
176-
[tools.jupyter-releaser.hooks]
177-
after-build-python = ["python scripts/cleanup.py", "python scripts/send_email.py"]
178-
```
179-
180-
Example `package.json`:
181-
182-
```json
183-
{
184-
"name": "my-package",
185-
"jupyter-releaser": {
186-
"options": {
187-
"dist_dir": "mydist"
188-
},
189-
"skip": ["check-manifest"],
190-
"hooks": {
191-
"before-publish-dist": "npm run pre:publish:dist"
192-
}
193-
}
194-
}
195-
```
196-
19722
## Checklist for Adoption
19823

19924
A. Prep the `jupyter_releaser` fork:

‎docs/source/background/index.rst‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
Background
2+
==========
3+
Explanation. Clarification and discussion of key topics.
4+
5+
.. toctree::
6+
:maxdepth: 1
7+
:caption: Contents:
8+
9+
theory

‎docs/source/background/theory.md‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
# Theory
2+
3+
## Motivation
4+
5+
This project should help maintainers reduce toil and save time in the release process by enforcing best practices to:
6+
7+
- Automate a changelog for every release
8+
- Pre-publish to test server and verify the install and import of dist asset(s)
9+
- Commit a message with hashes of dist file(s)
10+
- Annotate the git tag in standard format
11+
- Create a GitHub release with changelog entry
12+
- Verify url links in markdown and reStructuredText files
13+
- Verify integrity of Python manifest
14+
- Forward port changelog entries into default branch
15+
- Dry run publish on CI
16+
- Revert to Dev version after release (optional)
17+
18+
## Workflow Details
19+
20+
Detailed workflows are available to draft a changelog, draft a release, publish a release, and check a release.
21+
22+
### Draft ChangeLog Workflow
23+
24+
- Manual Github workflow
25+
- Inputs are the target repo, branch, and the version spec
26+
- Bumps the version
27+
- By default, uses [tbump](https://github.com/tankerhq/tbump) or [bump2version](https://github.com/c4urself/bump2version) to bump the version based on presence of config files
28+
- We recommend `tbump` instead of `bump2version` for most cases because it does not handle patch releases well when using [prereleases](https://github.com/c4urself/bump2version/issues/190).
29+
- Prepares the environment
30+
- Sets up git config and branch
31+
- Generates a changelog (using [github-activity](https://github.com/executablebooks/github-activity)) using the PRs since the last tag on this branch.
32+
- Gets the current version and then does a git checkout to clear state
33+
- Adds a new version entry using a HTML comment markers in the changelog file
34+
- Optionally resolves [meeseeks](https://github.com/MeeseeksBox/MeeseeksDev) backport PRs to their original PR
35+
- Creates a PR with the changelog changes
36+
- Can be re-run using the same version spec. It will add new entries but preserve existing ones (in case they have been hand modified).
37+
- Note: Pre-release changelog sections are not automatically combined,
38+
but you may wish to do so manually.
39+
40+
### Draft Release Workflow
41+
42+
- Manual Github workflow
43+
- Inputs are target repository, branch, version spec and optional post version spec
44+
- Bumps version using the same method as the changelog action
45+
- Prepares the environment using the same method as the changelog action
46+
- Checks the changelog entry
47+
- Looks for the current entry using the HTML comment markers
48+
- Gets the expected changelog values using `github-activity`
49+
- Ensures that all PRs are the same between the two
50+
- For Python packages:
51+
- Builds the wheel and source distributions if applicable
52+
- Makes sure Python dists can be installed and imported in a virtual environment
53+
- For npm package(s) (including workspace support):
54+
- Builds tarball(s) using `npm pack`
55+
- Make sure tarball(s) can be installed and imported in a new npm package
56+
- Checks the package manifest using [`check-manifest`](https://github.com/mgedmin/check-manifest)
57+
- Checks the links in Markdown and reStructuredText files
58+
- Adds a commit that includes the hashes of the dist files
59+
- Creates an annotated version tag in standard format
60+
- If given, bumps the version using the post version spec
61+
- Pushes the commits and tag to the target `branch`
62+
- Publishes a draft GitHub release for the tag with the changelog entry as the text
63+
64+
### Publish Release Workflow
65+
66+
- Manual Github workflow
67+
- Input is the url of the draft release
68+
- Downloads the dist assets from the release
69+
- Verifies shas and integrity of release assets
70+
- Publishes assets to appropriate registries
71+
- If the tag is on a backport branch, makes a forwardport PR for the changelog entry
72+
73+
### Check Release Workflow
74+
75+
- Runs on CI in the target repository to verify compatibility and release-ability.
76+
- Runs the `Draft Changelog` and `Draft Release` actions in dry run mode
77+
- Publishes to the local PyPI server and/or dry-run `npm publish`.
78+
- Does not make PRs or push git changes

‎docs/source/conf.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -72,5 +72,5 @@
7272

7373

7474
def setup(app):
75-
dest = osp.join(HERE, "changelog.md")
75+
dest = osp.join(HERE, "reference", "changelog.md")
7676
shutil.copy(osp.join(HERE, "..", "..", "CHANGELOG.md"), dest)

‎docs/source/get_started/generate_changelog.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Generating a Manual Changelog Entry
2+
3+
The "Generate Changelog" workflow is useful for repositories or branches that do not yet use Jupyter Releaser.
4+
5+
You can generate a markdown or reStructuredText changelog entry and manually apply it to the repo.
6+
7+
The workflow does not require any credentials.
8+
9+
To run the workflow:
10+
11+
- Go to the "Actions" tab on the source repository or your fork.
12+
13+
- Click on "Generate Changelog" on the left navigation bar
14+
15+
- Click the "Run workflow" dropdown button on the right and fill in the appropriate values
16+
17+
![Generate Changelog Workflow Dialog](../images/generate_changelog.png)
18+
19+
- Write "true" for "Whether to convert to RST" if the target repo uses a reStructuredText changelog
20+
21+
- The last two fields can be used to constrain the changelog entries to a set of tags or other references
22+
23+
- When the job finishes, download and extract the generated changelog

‎docs/source/get_started/index.rst‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
Getting Started
2+
===============
3+
Tutorials. A hands-on introduction to Jupyter Releaser for maintainers.
4+
5+
.. toctree::
6+
:maxdepth: 1
7+
:caption: Contents:
8+
9+
making_first_release
10+
generate_changelog

0 commit comments

Comments
 (0)