update docs

Author: blink1073

README.md

@@ -27,77 +27,4 @@ See the [adoption docs](https://jupyter-releaser.readthedocs.io/en/latest/how_to
 
 Detailed workflows are available to draft a changelog, draft a release, publish a release, and check a release.
 
-### Draft ChangeLog Workflow
-
-- Manual Github workflow
-  - Inputs are the target repo, branch, and the version spec
-- Bumps the version
-  - 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
-    - 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).
-- Prepares the environment
-  - Sets up git config and branch
-- Generates a changelog (using [github-activity](https://github.com/executablebooks/github-activity)) using the PRs since the last tag on this branch.
-  - Gets the current version and then does a git checkout to clear state
-  - Adds a new version entry using a HTML comment markers in the changelog file
-  - Optionally resolves [meeseeks](https://github.com/MeeseeksBox/MeeseeksDev) backport PRs to their original PR
-- Creates a PR with the changelog changes
-- 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).
-- Note: Pre-release changelog sections are not automatically combined,
-  but you may wish to do so manually.
-
-### Draft Release Workflow
-
-- Manual Github workflow
-  - Inputs are target repository, branch, version spec and optional post version spec
-- Bumps version using the same method as the changelog action
-- Prepares the environment using the same method as the changelog action
-- Checks the changelog entry
-  - Looks for the current entry using the HTML comment markers
-  - Gets the expected changelog values using `github-activity`
-  - Ensures that all PRs are the same between the two
-- For Python packages:
-  - Builds the wheel and source distributions if applicable
-  - Makes sure Python dists can be installed and imported in a virtual environment
-- For npm package(s) (including workspace support):
-  - Builds tarball(s) using `npm pack`
-  - Make sure tarball(s) can be installed and imported in a new npm package
-- Checks the package manifest using [`check-manifest`](https://github.com/mgedmin/check-manifest)
-- Checks the links in Markdown and reStructuredText files
-- Adds a commit that includes the hashes of the dist files
-- Creates an annotated version tag in standard format
-- If given, bumps the version using the post version spec. The post version
-  spec can also be given as a setting, see the [Write Releaser Config Guide](https://jupyter-releaser.readthedocs.io/en/latest/how_to_guides/write_config.html).
-- Pushes the commits and tag to the target `branch`
-- Publishes a draft GitHub release for the tag with the changelog entry as the text
-
-### Publish Release Workflow
-
-- Manual Github workflow
-  - Input is the url of the draft release
-- Downloads the dist assets from the release
-- Verifies shas and integrity of release assets
-- Publishes assets to appropriate registries
-- If the tag is on a backport branch, makes a forwardport PR for the changelog entry
-
-### Check Release Workflow
-
-- Runs on CI in the target repository to verify compatibility and release-ability.
-- Runs the `Draft Changelog` and `Draft Release` actions in dry run mode
-- Publishes to the local PyPI server and/or dry-run `npm publish`.
-- Does not make PRs or push git changes
-
-## FAQs
-
-### My changelog is out of sync
-
-Create a new manual PR to fix the PR and re-orient the changelog entry markers.
-
-### PR is merged to the target branch in the middle of a "Draft Release"
-
-The release will fail to push commits because it will not be up to date. Delete the pushed tags and re-start with "Draft Changelog" to
-pick up the new PR.
-
-## How to keep fork of Jupyter Releaser up to date
-
-The manual workflow files target the `@v1` actions in the source repository, which means that as long as
-the workflow files themselves are up to date, you will always be running the most up to date actions.
+See the [workflow details documentation](https://jupyter-releaser.readthedocs.io/en/latest/background/theory.html#workflow-details) for more information.

docs/source/background/theory.md

@@ -40,7 +40,8 @@ Detailed workflows are available to draft a changelog, draft a release, publish
 ### Draft Release Workflow
 
 - Manual Github workflow
-  - Inputs are target repository, branch, version spec and optional post version spec
+  - Input is the URL of the draft GitHub Release created in the Draft Changelog
+    workflow.
 - Bumps version using the same method as the changelog action
 - Prepares the environment using the same method as the changelog action
 - Checks the changelog entry
@@ -60,17 +61,23 @@ Detailed workflows are available to draft a changelog, draft a release, publish
 - If given, bumps the version using the post version spec. he post version
   spec can also be given as a setting, [Write Releaser Config Guide](../how_to_guides/write_config.html#automatic-dev-versions).
 - Pushes the commits and tag to the target `branch`
-- Publishes a draft GitHub release for the tag with the changelog entry as the text
+- Updates the draft GitHub release for the tag with the changelog entry as the text
 
 ### Publish Release Workflow
 
 - Manual Github workflow
-  - Input is the url of the draft release
+  - Input is the url of the draft GitHub release
 - Downloads the dist assets from the release
 - Verifies shas and integrity of release assets
 - Publishes assets to appropriate registries
 - If the tag is on a backport branch, makes a forwardport PR for the changelog entry
 
+### Full Release Workflow
+
+- Combines the Draft and Publish workflows into a single workflow.
+- If this workflow fails during the publish step, you can address any
+  credential errors and run the Publish Release Workflow to publish assets.
+
 ### Check Release Workflow
 
 - Runs on CI in the target repository to verify compatibility and release-ability.

docs/source/get_started/making_first_release.md

@@ -35,7 +35,7 @@ already uses Jupyter Releaser.
 ## Draft Changelog
 
 - Go to the "Actions" tab in your fork of `jupyter_releaser`
-- Select the "Draft Changelog" workflow on the left
+- Select the "Step 1: Draft Changelog" workflow on the left
 - Click on the "Run workflow" dropdown button on the right
 - Fill in the appropriate parameters
 
@@ -48,6 +48,7 @@ already uses Jupyter Releaser.
     instead.
   - Use the "since" field to select PRs prior to the latest tag to include in the release
   - 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.
+  - 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 pull request to the target
     repository and branch. It will print the link in the "\*\* Next Step \*\*" job step.
@@ -72,13 +73,11 @@ already uses Jupyter Releaser.
 - Click on the "Actions" tab
 - Select the "Full Release" workflow on the left
 - Click on the "Run workflow" button on the right
-- Fill in the entries as prompted by the automated changelog text
+- Fill in draft GitHub Release URL given by the Changelog PR.
 
   ![Full Release Workflow Dialog](../images/draft_release.png)
 
-  - 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 draft a GitHub release, publish assets to the appropriate registries.
+- 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.