docs: improve release_steps.py usage documentation and help messages
diff --git a/doc/dev/release_checklist.md b/doc/dev/release_checklist.md index 7680d0c..f6adc42 100644 --- a/doc/dev/release_checklist.md +++ b/doc/dev/release_checklist.md
@@ -41,6 +41,10 @@ - In order to have the access rights to push to these repositories and merge PRs, you will need to be a member of the `lean-release-managers` team at both `leanprover-community` and `leanprover`. Contact Kim Morrison (@kim-em) to arrange access. + - There is an experimental script that will guide you through the steps for each of the repositories below. + The script should be invoked as + `script/release_steps.py vx.y.x <repo>` where `<repo>` is a case-insensitive substring of the repo name. + For example: `script/release_steps.py v4.6.0 batt` will guide you through the steps for the Batteries repository. - For each of the repositories listed below: - Make a PR to `master`/`main` changing the toolchain to `v4.6.0` - The usual branch name would be `bump_to_v4.6.0`.
diff --git a/script/release_steps.py b/script/release_steps.py index d6449f9..74ff3e7 100755 --- a/script/release_steps.py +++ b/script/release_steps.py
@@ -1,5 +1,32 @@ #!/usr/bin/env python3 +""" +Generate release steps script for Lean4 repositories. + +This script helps automate the release process for Lean4 and its dependent repositories +by generating step-by-step instructions for updating toolchains, creating tags, +and managing branches. + +Usage: + python3 release_steps.py <version> <repo> + +Arguments: + version: The version to set in the lean-toolchain file (e.g., v4.6.0) + repo: A substring of the repository name as specified in release_repos.yml + +Example: + python3 release_steps.py v4.6.0 mathlib + python3 release_steps.py v4.6.0 batt + +The script reads repository configurations from release_repos.yml in the same directory. +Each repository may have specific requirements for: +- Branch management +- Toolchain updates +- Dependency updates +- Tagging conventions +- Stable branch handling +""" + import argparse import yaml import os @@ -84,9 +111,23 @@ return "\n".join(script_lines) def main(): - parser = argparse.ArgumentParser(description="Generate release steps script.") - parser.add_argument("version", help="The version to set in the lean-toolchain file.") - parser.add_argument("repo", help="A substring of the repository name as specified in the YAML config.") + parser = argparse.ArgumentParser( + description="Generate release steps script for Lean4 repositories.", + formatter_class=argparse.RawDescriptionHelpFormatter, + epilog=""" +Examples: + %(prog)s v4.6.0 mathlib Generate steps for updating Mathlib to v4.6.0 + %(prog)s v4.6.0 batt Generate steps for updating Batteries to v4.6.0 + +The script will generate shell commands to: +1. Update the lean-toolchain file +2. Create appropriate branches and commits +3. Create pull requests +4. Create version tags +5. Update stable branches where applicable""" + ) + parser.add_argument("version", help="The version to set in the lean-toolchain file (e.g., v4.6.0)") + parser.add_argument("repo", help="A substring of the repository name as specified in release_repos.yml") args = parser.parse_args() config_path = os.path.join(os.path.dirname(__file__), "release_repos.yml")