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_news_filepath	Get the NEWS filepath for an R package.
get_r_dev_version	Get the next R package development version.
get_release_version	Get the next release version based on manual input or conventional commit history.
is_r_package	Detect whether this repository appears to be an R package.
is_strict_semver	Check whether a version string fully matches semantic versioning.
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.
regenerate_citation_from_description	Regenerate CITATION.cff from DESCRIPTION using cffr.
set_release_version	Set the next release version for GitHub Actions based on manual input or conventional commit history.
write_description_version	Update Version in an R DESCRIPTION file.
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_news_filepath

release.get_news_filepath()

Get the NEWS filepath for an R package.

Returns

Name	Type	Description
str		“NEWS.md” if it exists, else “NEWS” if it exists, otherwise “NEWS.md”.

get_r_dev_version

release.get_r_dev_version(version)

Get the next R package development version.

Parameters

Name	Type	Description	Default
version	str	Current released version, with or without leading ‘v’.	required

Returns

Name	Type	Description
str		R package development version in the form X.Y.Z.9000.

Raises

Name	Type	Description
	ValueError	If version is not in X.Y.Z semantic version format.

Examples

>>> get_r_dev_version("0.2.0")
'0.2.0.9000'

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'

is_r_package

release.is_r_package(description_filepath='DESCRIPTION')

Detect whether this repository appears to be an R package.

Parameters

Name	Type	Description	Default
description_filepath	str	Path to the R DESCRIPTION file.	'DESCRIPTION'

Returns

Name	Type	Description
bool		True if the DESCRIPTION file exists and includes Package and Version keys.

is_strict_semver

release.is_strict_semver(version_str, with_leading_v=False)

Check whether a version string fully matches semantic versioning.

Parameters

Name	Type	Description	Default
version_str	str	Version string to validate.	required
with_leading_v	bool	Whether the version must include a leading ‘v’.	False

Returns

Name	Type	Description
bool	bool	True if the entire string matches semantic versioning.

Examples

>>> is_strict_semver("v1.2.3", with_leading_v=True)
True
>>> is_strict_semver("v1.2.3.9000", with_leading_v=True)
False

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',
    description_filepath='DESCRIPTION',
    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’| | description_filepath | [str](str) | Path to the R DESCRIPTION file for R packages (default is "DESCRIPTION"). |‘DESCRIPTION’| | debug | [bool](bool) | If True, print debug information instead of executing commands (default is False). |False`

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 }}',
    description_filepath='DESCRIPTION',
    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
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 }}‘| | changelog_filepath | [str](str) | The path to the changelog file (default is "CHANGELOG.md"). |’CHANGELOG.md’| | dev_header | [str](str) | The header for the development version section in the changelog (default is "development version"). |‘development version’| | release_notes_filepath | [str](str) | The path to the release notes file (default is ".github/latest-release.md"). |‘.github/latest-release.md’| | 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’| | release_branch | [str](str) | The name of the release branch (default is "release-draft"). |‘release-draft’| | pr_ref_name | [str](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 }}'
description_filepath	str	Path to the R DESCRIPTION file for R packages (default is “DESCRIPTION”).	'DESCRIPTION'
debug	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_draft_release()
>>> prepare_draft_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

regenerate_citation_from_description

release.regenerate_citation_from_description(
    citation_filepath='CITATION.cff',
    description_filepath='DESCRIPTION',
    debug=False,
)

Regenerate CITATION.cff from DESCRIPTION using cffr.

Preserves custom fields (e.g., identifiers) from the existing CITATION.cff file.

Parameters

Name	Type	Description	Default
citation_filepath	str	Path to output CITATION.cff.	'CITATION.cff'
description_filepath	str	Path to DESCRIPTION file.	'DESCRIPTION'
debug	bool	If True, print command instead of running it.	False

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_description_version

release.write_description_version(
    description_filepath='DESCRIPTION',
    version='0.0.0',
    debug=False,
)

Update Version in an R DESCRIPTION file.

Parameters

Name	Type	Description	Default
description_filepath	str	Path to DESCRIPTION file.	'DESCRIPTION'
version	str	Version string to write.	'0.0.0'
debug	bool	If True, print updates instead of writing to file.	False

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’