release
release
Helpers for drafting releases and cleaning up after releases are published.
Functions
| Name | Description |
|---|---|
| create_release_draft | Create a draft release on GitHub. |
| get_changelog_lines | Prepare the changelog to draft a release. |
| get_release_version | Get the next release version based on manual input or conventional commit history. |
| post_release_cleanup | Perform post-release cleanup tasks. |
| prepare_draft_release | Prepare the release by updating version, changelog, and release notes. |
| push_release_draft_branch | Pushes a release draft branch to the remote repository. |
| set_release_version | Set the next release version for GitHub Actions based on manual input or conventional commit history. |
| write_lines | Write lines to a file or return them as a string for debugging. |
create_release_draft
release.create_release_draft(
release_branch='release-draft',
next_version='${{ steps.release.outputs.NEXT_VERSION }}',
release_notes_filepath='.github/latest-release.md',
release_target=get_current_hash(),
repo='${{ github.repository }}',
debug=False,
)Create a draft release on GitHub.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| release_branch | str | The name of the release branch. Defaults to “release-draft”. | 'release-draft' |
| next_version | str | The next version of the release. Defaults to “\({{ steps.release.outputs.NEXT_VERSION }}". | `'\){{ steps.release.outputs.NEXT_VERSION }}‘| | release_notes_filepath | [str](str) | The file path to the release notes. Defaults to ".github/latest-release.md". |’.github/latest-release.md’| | release_target | [str](str) | The target commit hash for the release. Defaults to the current commit hash. |get_current_hash()| | repo | [str](str) | The GitHub repository in the format "owner/repo". Defaults to "${{ github.repository }}". |‘${{ github.repository }}’| | debug | [bool](bool) | If True, print the command instead of executing it. Defaults to False. |False` |
Returns
| Name | Type | Description |
|---|---|---|
| str | The URL of the created release draft, or an empty string if in debug mode. |
get_changelog_lines
release.get_changelog_lines(
latest_version_strict,
next_version_strict,
changelog_filepath='CHANGELOG.md',
dev_header='development version',
)Prepare the changelog to draft a release.
This function reads the changelog file and prepares it for the next release by replacing the development version header with the next version string and collecting lines for the next release.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| latest_version_strict | str | The latest version string that follows semantic versioning. | required |
| next_version_strict | str | The next version string that follows semantic versioning. | required |
| changelog_filepath | str | The path to the changelog file. Defaults to “CHANGELOG.md”. | 'CHANGELOG.md' |
| dev_header | str | The header used for the development version in the changelog. Defaults to “development version”. | 'development version' |
Returns
| Name | Type | Description |
|---|---|---|
| tuple | A tuple containing two lists: - changelog_lines (list): The complete list of lines from the changelog file with the development version header replaced. - next_release_lines (list): The list of lines that pertain to the next release. |
Raises
| Name | Type | Description |
|---|---|---|
| ValueError | If any of the provided version strings do not match the semantic versioning pattern. |
get_release_version
release.get_release_version(
next_version_manual=None,
next_version_convco=None,
current_version=None,
gh_event_name=None,
with_leading_v=True,
)Get the next release version based on manual input or conventional commit history.
If a manual version is provided, it is used regardless of the conventional commit history.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| next_version_manual | str | The manually specified next version (default is None). | None |
| next_version_convco | str | The next version determined by conventional commit history (default is None). | None |
| current_version | str | The current version of the project (default is None). | None |
| gh_event_name | str | The name of the GitHub event triggering the release (default is None). | None |
| with_leading_v | bool | Whether to include a leading ‘v’ in the version string (default is True). | True |
Returns
| Name | Type | Description |
|---|---|---|
| str | The next release version. |
Raises
| Name | Type | Description |
|---|---|---|
| Warning | If the manual version does not match the version determined by conventional commit history. |
Examples
>>> get_release_version(next_version_manual="1.2.0")
'1.2.0'
>>> get_release_version(next_version_convco="1.2.1", current_version="1.2.0")
'1.2.1'post_release_cleanup
release.post_release_cleanup(
changelog_filepath='CHANGELOG.md',
repo='${{ github.repository }}',
release_tag='${{ github.ref_name }}',
pr_branch='${{ inputs.branch }}',
pr_reviewer='${{ github.triggering_actor }}',
draft_branch='release-draft',
dev_header='development version',
version_filepath='VERSION',
citation_filepath='CITATION.cff',
debug=False,
)Perform post-release cleanup tasks.
This function performs cleanup tasks after a release has been created. It updates the changelog, resets the version file, and creates a pull request to merge the changes back into the main branch.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| changelog_filepath | str | The path to the changelog file (default is “CHANGELOG.md”). | 'CHANGELOG.md' |
| repo | str | The GitHub repository (default is “\({{ github.repository }}"). | `'\){{ github.repository }}‘| | release_tag | [str](str) | The tag of the release (default is "${{ github.ref_name }}"). |’\({{ github.ref_name }}'` |
| pr_branch | [str](`str`) | The branch for the pull request (default is "\){{ inputs.branch }}”). |
'${{ inputs.branch }}' |
| pr_reviewer | str | The reviewer for the pull request (default is “\({{ github.triggering_actor }}"). | `'\){{ github.triggering_actor }}‘| | draft_branch | [str](str) | The name of the draft branch (default is "release-draft"). |’release-draft’| | dev_header | [str](str) | The header for the development version section in the changelog (default is "development version"). |‘development version’| | version_filepath | [str](str) | The path to the version file (default is "VERSION"). |‘VERSION’| | citation_filepath | [str](str) | The path to the citation file (default is "CITATION.cff"). |‘CITATION.cff’` |
Examples
>>> post_release_cleanup()
>>> post_release_cleanup(changelog_filepath="docs/CHANGELOG.md", pr_branch="main")prepare_draft_release
release.prepare_draft_release(
next_version_manual='${{ github.event.inputs.version_tag }}',
next_version_convco='${{ steps.semver.outputs.next }}',
current_version='${{ steps.semver.outputs.current }}',
gh_event_name='${{ github.event_name }}',
changelog_filepath='CHANGELOG.md',
dev_header='development version',
release_notes_filepath='.github/latest-release.md',
version_filepath='VERSION',
citation_filepath='CITATION.cff',
release_branch='release-draft',
pr_ref_name='${{ github.ref_name }}',
repo='${{ github.repository }}',
debug=False,
)Prepare the release by updating version, changelog, and release notes.
This function prepares the release by resolving file paths, determining the next version, updating the changelog and release notes, and setting the next version as an output.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| dev_header | str | The header for the development version section in the changelog (default is “development version”). | 'development version' |
| release_notes_filepath | str | The path to the release notes file (default is “.github/latest-release.md”). | '.github/latest-release.md' |
| version_filepath | str | The path to the version file (default is “VERSION”). | 'VERSION' |
| citation_filepath | str | The path to the citation file (default is “CITATION.cff”). | 'CITATION.cff' |
| release_branch | str | The name of the release branch (default is “release-draft”). | 'release-draft' |
| pr_ref_name | str | The reference name of the pull request (default is “\({{ github.ref_name }}"). | `'\){{ github.ref_name }}‘| | repo | [str](str) | The GitHub repository (default is "${{ github.repository }}"). |’${{ github.repository }}’| | debug | [bool](bool) | If True, print debug information instead of writing to files (default is False). |False` |
Raises
| Name | Type | Description |
|---|---|---|
| AssertionError | If the changelog or version file does not exist. |
Examples
>>> prepare_release()
>>> prepare_release(dev_header="dev version", debug=True)push_release_draft_branch
release.push_release_draft_branch(
release_branch='release-draft',
pr_ref_name='${{ github.ref_name }}',
next_version=None,
files=['CHANGELOG.md', 'VERSION', 'CITATION.cff'],
debug=False,
)Pushes a release draft branch to the remote repository.
This function creates or switches to a specified release branch, merges changes from a pull request reference, stages specified files, commits the changes with a message indicating the next version, and pushes the branch to the remote repository. If the branch already exists, it will be deleted before creating a new one.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| release_branch | str | The name of the release branch to create or switch to. Defaults to “release-draft”. | 'release-draft' |
| pr_ref_name | str | The reference name of the pull request to merge. Defaults to “\({{ github.ref_name }}". | `'\){{ github.ref_name }}’| | next_version | [str](str) | The next version number to include in the commit message. Defaults to None. |None| | files | [list](list) | A list of files to stage and commit. Defaults to ["CHANGELOG.md", "VERSION", "CITATION.cff"]. |[‘CHANGELOG.md’, ‘VERSION’, ‘CITATION.cff’]| | debug | [bool](bool) | If True, prints the generated git commands instead of executing them. Defaults to False. |False` |
Returns
| Name | Type | Description |
|---|---|---|
| None |
set_release_version
release.set_release_version(
next_version_manual='${{ github.event.inputs.version_tag }}',
next_version_convco='${{ steps.semver.outputs.next }}',
current_version='${{ steps.semver.outputs.current }}',
gh_event_name='${{ github.event_name }}',
)Set the next release version for GitHub Actions based on manual input or conventional commit history.
This function determines and sets the next release version for GitHub Actions. It uses either a manually specified version or a version determined by conventional commit history. The determined version is then set as an output for use in subsequent GitHub Actions steps.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| next_version_manual | str | The manually specified next version (default is “\({{ github.event.inputs.version_tag }}"). | `'\){{ github.event.inputs.version_tag }}‘| | next_version_convco | [str](str) | The next version determined by conventional commit history (default is "${{ steps.semver.outputs.next }}"). |’\({{ steps.semver.outputs.next }}'` |
| current_version | [str](`str`) | The current version of the project (default is "\){{ steps.semver.outputs.current }}”). |
'${{ steps.semver.outputs.current }}' |
| gh_event_name | str | The name of the GitHub event triggering the release (default is “\({{ github.event_name }}"). | `'\){{ github.event_name }}’` |
Examples
>>> set_release_version()
>>> set_release_version(next_version_manual="1.2.0")write_lines
release.write_lines(filepath, lines, debug=False)Write lines to a file or return them as a string for debugging.
This function writes the provided lines to a specified file. If debugging is enabled,
it returns the lines as a single string instead of writing to the file.
Args:
filepath (str): The path to the file where the lines should be written.
lines (list of str): The lines to write to the file.
debug (bool): If True, return the lines as a single string instead of writing to the file (default is False).
Returns:
str: The lines as a single string if debugging is enabled, otherwise None.
Examples:
>>> write_lines("output.txt", ["line 1“,”line 2 “])
>>> write_lines("output.txt", ["line 1“,”line 2 “], debug=True) ‘line 1 line 2’