From e6776b9a27572f5a74284b31ca580d1937f1ddbd Mon Sep 17 00:00:00 2001 From: egrace479 Date: Fri, 1 May 2026 18:04:57 -0400 Subject: [PATCH 1/7] Create new heading with ref pages --- mkdocs.yaml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/mkdocs.yaml b/mkdocs.yaml index bea96ce..1475ce1 100644 --- a/mkdocs.yaml +++ b/mkdocs.yaml @@ -131,7 +131,9 @@ nav: - "About Templates": wiki-guide/About-Templates.md - "Dataset Card Template": wiki-guide/HF_DatasetCard_Template_mkdocs.md - "Model Card Template": wiki-guide/HF_ModelCard_Template_mkdocs.md - - Command Line Cheat Sheet: wiki-guide/Command-Line-Cheat-Sheet.md + - Quick References: + - "Command Line Cheat Sheet": wiki-guide/Command-Line-Cheat-Sheet.md + - "GitHub-PyPI-Zenodo Versioning": wiki-guide/GitHub-PyPI-Zenodo-Integration.md - Code of Conduct: CODE_OF_CONDUCT.md - Digital Product Policy: - "About Digital Product Policies": wiki-guide/About-Digital-Product-Policies.md From ddb88cb2ab0cdbb25a9bce227840194ee6f8fa9f Mon Sep 17 00:00:00 2001 From: egrace479 Date: Tue, 5 May 2026 15:53:12 -0400 Subject: [PATCH 2/7] Add quick reference page for auto release to pypi and zenodo --- .../GitHub-PyPI-Zenodo-Integration.md | 148 ++++++++++++++++++ 1 file changed, 148 insertions(+) create mode 100644 docs/wiki-guide/GitHub-PyPI-Zenodo-Integration.md diff --git a/docs/wiki-guide/GitHub-PyPI-Zenodo-Integration.md b/docs/wiki-guide/GitHub-PyPI-Zenodo-Integration.md new file mode 100644 index 0000000..c4c1078 --- /dev/null +++ b/docs/wiki-guide/GitHub-PyPI-Zenodo-Integration.md @@ -0,0 +1,148 @@ +# GitHub-PyPI-Zenodo Versioning and Release Version Guide + +This page is a quick reference for setting up a repository to automatically release to the [Python Package Index (PyPI)](https://pypi.org/) and [Zenodo](https://zenodo.org/) on a GitHub release. At the bottom of the page are [checklists](#release-checklist) for first-time releases, new releases, and post-release steps. These are set up to be copied into a relevant issue on your GitHub repository for easier tracking. + +!!! warning + Before setting a release, please review the [Digital Product Policy](About-Digital-Product-Policies.md) and check your repository against the [Code Repo Checklist](Code-Checklist.md). + +!!! note + Steps marked with an `*` need only be completed once (the first time this is set up). + +## Before Generating a Release + +### Set version in... + +- `__about__.py` file + - Version should be set *dynamically* in the `pyproject.toml` from this file.* +- [`CITATION.cff`](GitHub-Repo-Guide.md#citation-templates) +- [`.zenodo.json`](GitHub-Repo-Guide.md#zenodo-metadata) + +### Add/Update Citation and Zenodo Metadata Files + +Review or create both a [`CITATION.cff`](GitHub-Repo-Guide.md#citation) and [`.zenodo.json`](GitHub-Repo-Guide.md#zenodo-metadata) file following guide instructions. Be sure to include + +!!! tip "Pro tip" + Add this [test to validate the Zenodo metatdata file](https://github.com/Imageomics/Collaborative-distributed-science-guide/blob/main/.github/workflows/validate-zenodo.yaml).* It will run whenever the `.zenodo.json` or workflow file are edited, ensuring that your Zenodo integration will run smoothly. + +Before release, ensure that... + +- All authors are included and appropriately ordered. + - This list may or may not change, and may differ from an associated paper author list, as discussed in the [Digital Product Lifecycle](Digital-Product-Lifecycle.md#exploration-phase) and the [Imageomics Author Guide](https://docs.google.com/spreadsheets/d/1GwlCukfoQPL8JI2yyWRD3g4uiMTO3tlGNE_qeb_xBCs/edit?usp=sharing). +- All project keywords are listed, using quotes for multi-word tags. +- The release date in both files is correct. + + !!! info + This should be added in a PR as the last commit before a release, but check that the date matches, since these PRs sometimes are not merged on the day they are created. + +- Set [citation file identifiers](GitHub-Repo-Guide.md#__codelineno-1-8): + - Version tag link should match the updated version. The commit hash of the version will be filled in *after* release. + - DOI should be the *general software* DOI from Zenodo to avoid mis-matched version confusion (since it must be added ***after*** release).* + + !!! note + If you have not generated a release yet, then leave the `doi` key commented out; it will be added **after** release. + +### Automate publish to PyPI on release* + +Complete all steps below to automatically publish releases to PyPI. These steps need only be completed once before the first release; only dependencies and other keys in the `pyproject.toml` may need updating over time. + +- Set up a [`pyproject.toml`](https://packaging.python.org/en/latest/guides/writing-pyproject-toml/) with your project repo information and dependencies. + - Include your project keywords in `pyproject.toml` (no spaces, even within quotes). + - Version in `pyproject.toml` set *dynamically*. +- Add PyPI publication workflow*. See [pybioclip workflow](https://github.com/Imageomics/pybioclip/blob/main/.github/workflows/publish-to-pypi.yml) as an example.[^1] + - For this to work on upload, you must configure GitHub as a "pending" publisher on PyPI. See PyPI's ["pending" publisher docs](https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/) for instructions. + +### Update `README` Installation Instructions* + +Update the installation instructions in the `README` to `pip install ` instead of `pip install git+` right before the release and concurrent PyPI publication. + +### Turn Repository Sync on in your Zenodo Account* + +This must be set specifically for the target repo. See [Automatic DOI Generation with Zenodo](DOI-Generation.md#automatic-generation) for more information. + +## After a Release is Generated + +There are a few updates required after generating a release, though the last listed here is the only one that is required for each release. + +- Add DOI badge to `README`*. + - Make sure to use the *version-agnostic* DOI, used to reference all releases. The badge display will then auto-update with each release to match the DOI of *that* release. + - See [Add a Zenodo DOI Badge](DOI-Generation.md#add-a-zenodo-doi-badge) for instructions. +- Add PyPI badges to `README`*. +- Add *version-agnostic* DOI to `CITATION.cff`*. +- Add release commit hash to `CITATION.cff` [identifiers](GitHub-Repo-Guide.md#__codelineno-1-8). + +## Release Checklist + +!!! tip "Pro tip" + + Copy the markdown for the relevant checklist below into an issue on your GitHub [Repo](GitHub-Repo-Guide.md) or [Project](Guide-to-GitHub-Projects.md) so you can check the boxes as you complete each step to genearate a release for your GitHub repository. + +=== "First Release" + + ```Markdown + Set version in... + - [ ] `__about__.py` file (the only repeated PyPI update). + - Version should be set *dynamically* in the `pyproject.toml` from this file.* + - [ ] [`CITATION.cff`](GitHub-Repo-Guide.md#citation-templates). + - [ ] [`.zenodo.json`](GitHub-Repo-Guide.md#zenodo-metadata). + + Add/Update the [citation](GitHub-Repo-Guide.md#citation) and [Zenodo metadata](GitHub-Repo-Guide.md#zenodo-metadata) files. Ensure that... + - [ ] All authors are included and appropriately ordered. + - This list may or may not change, and may differ from an associated paper author list, as discussed in the [Digital Product Lifecycle](Digital-Product-Lifecycle.md#exploration-phase) and the [Imageomics Author Guide](https://docs.google.com/spreadsheets/d/1GwlCukfoQPL8JI2yyWRD3g4uiMTO3tlGNE_qeb_xBCs/edit?usp=sharing). + - [ ] All project keywords are listed, using quotes for multi-word tags. + - [ ] The release date in both files is correct. + + !!! info + This should be added in a PR as the last commit before a release, but check that the date matches, since these PRs sometimes are not merged on the day they are created. + + - Set [citation file identifiers](GitHub-Repo-Guide.md#__codelineno-1-8): + - [ ] Version tag link should match the updated version. The commit hash of the version will be filled in *after* release. + + !!! note + You have not generated a release yet, so leave the `doi` key commented out; it will be added **after** release. + + - [ ] Add [test to validate Zenodo file](https://github.com/Imageomics/Collaborative-distributed-science-guide/blob/main/.github/workflows/validate-zenodo.yaml).* + + Automate publish to PyPI on release: + - [ ] Set up a [`pyproject.toml`](https://packaging.python.org/en/latest/guides/writing-pyproject-toml/) with your project repo information and dependencies. + - [ ] Include your project keywords in `pyproject.toml` (no spaces, even within quotes). + - [ ] Version in `pyproject.toml` set *dynamically*. + - [ ] Add PyPI publication workflow*. See [pybioclip workflow](https://github.com/Imageomics/pybioclip/blob/main/.github/workflows/publish-to-pypi.yml) as an example.[^1] + - [ ] Configure GitHub as a "pending" publisher on PyPI. See PyPI's ["pending" publisher docs](https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/) for instructions.* + - [ ] Update installation instructions to reflect imminent release and PyPI publication:* + `pip install ` instead of `pip install git+`. + - [ ] Turn on repository sync in your Zenodo account; this must be set specifically for the target repo. See [Automatic DOI Generation with Zenodo](DOI-Generation.md#automatic-generation) for more information. + ``` + +=== "New Release" + + ```Markdown + Set version in... + - [ ] `__about__.py` file (the only repeated PyPI update). + - Version should be set *dynamically* in the `pyproject.toml` from this file.* + - [ ] [`CITATION.cff`](GitHub-Repo-Guide.md#citation-templates). + - [ ] [`.zenodo.json`](GitHub-Repo-Guide.md#zenodo-metadata). + + Update the [citation](GitHub-Repo-Guide.md#citation) and [Zenodo metadata](GitHub-Repo-Guide.md#zenodo-metadata) files. Ensure that... + - [ ] All authors are included and appropriately ordered. + - [ ] All project keywords are listed, using quotes for multi-word tags. + - [ ] The release date in both files is correct. + + !!! info + This should be added in a PR as the last commit before a release, but check that the date matches, since these PRs sometimes are not merged on the day they are created. + + - [ ] Set version tag in [citation file identifiers](GitHub-Repo-Guide.md#__codelineno-1-8) to match the updated version. The commit hash of the version will be filled in *after* release. + ``` + +=== "After Release" + + Only one step here is required for ***every release***: Add release commit hash to `CITATION.cff` [identifiers](GitHub-Repo-Guide.md#__codelineno-1-8). + + ```Markdown + - [ ] Add *version-agnostic* DOI badge to `README`*. + - See [Add a Zenodo DOI Badge](DOI-Generation.md#add-a-zenodo-doi-badge) for instructions. + - [ ] Add PyPI badges to `README`*. + - [ ] Add *version-agnostic* DOI to `CITATION.cff`*. + - [ ] ***Every release***: Add release commit hash to `CITATION.cff` [identifiers](GitHub-Repo-Guide.md#__codelineno-1-8). + ``` + +[^1]: Note that this follows the [PyPI Trusted Publishers docs](https://docs.pypi.org/trusted-publishers/using-a-publisher/) to remove the need for a token, though you must first configure GitHub as a ["pending" Trusted Publisher](https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/) for the project on PyPI. From 82963eec4dc7d883225c994283d5025a1157dce2 Mon Sep 17 00:00:00 2001 From: Elizabeth Campolongo <38985481+egrace479@users.noreply.github.com> Date: Tue, 5 May 2026 19:11:23 -0400 Subject: [PATCH 3/7] Improve phrasing and use more descriptive page title Co-authored-by: Hilmar Lapp Co-authored-by: Elizabeth Campolongo <38985481+egrace479@users.noreply.github.com> --- docs/wiki-guide/GitHub-PyPI-Zenodo-Integration.md | 6 +++--- mkdocs.yaml | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/wiki-guide/GitHub-PyPI-Zenodo-Integration.md b/docs/wiki-guide/GitHub-PyPI-Zenodo-Integration.md index c4c1078..5048df4 100644 --- a/docs/wiki-guide/GitHub-PyPI-Zenodo-Integration.md +++ b/docs/wiki-guide/GitHub-PyPI-Zenodo-Integration.md @@ -22,7 +22,7 @@ This page is a quick reference for setting up a repository to automatically rele Review or create both a [`CITATION.cff`](GitHub-Repo-Guide.md#citation) and [`.zenodo.json`](GitHub-Repo-Guide.md#zenodo-metadata) file following guide instructions. Be sure to include !!! tip "Pro tip" - Add this [test to validate the Zenodo metatdata file](https://github.com/Imageomics/Collaborative-distributed-science-guide/blob/main/.github/workflows/validate-zenodo.yaml).* It will run whenever the `.zenodo.json` or workflow file are edited, ensuring that your Zenodo integration will run smoothly. + Add this [test to validate the Zenodo metatdata file](https://github.com/Imageomics/Collaborative-distributed-science-guide/blob/main/.github/workflows/validate-zenodo.yaml). It will run whenever the `.zenodo.json` or workflow file are edited, ensuring that your Zenodo integration will run smoothly. Before release, ensure that... @@ -32,7 +32,7 @@ Before release, ensure that... - The release date in both files is correct. !!! info - This should be added in a PR as the last commit before a release, but check that the date matches, since these PRs sometimes are not merged on the day they are created. + This should be added in a PR as the last commit before a release, but check that the date matches, since these PRs may not necessarily be merged on the same day they are created. - Set [citation file identifiers](GitHub-Repo-Guide.md#__codelineno-1-8): - Version tag link should match the updated version. The commit hash of the version will be filled in *after* release. @@ -92,7 +92,7 @@ There are a few updates required after generating a release, though the last lis - [ ] The release date in both files is correct. !!! info - This should be added in a PR as the last commit before a release, but check that the date matches, since these PRs sometimes are not merged on the day they are created. + This should be added in a PR as the last commit before a release, but check that the date matches, since these PRs may not necessarily be merged on the same day they are created. - Set [citation file identifiers](GitHub-Repo-Guide.md#__codelineno-1-8): - [ ] Version tag link should match the updated version. The commit hash of the version will be filled in *after* release. diff --git a/mkdocs.yaml b/mkdocs.yaml index 1475ce1..1b59d87 100644 --- a/mkdocs.yaml +++ b/mkdocs.yaml @@ -133,7 +133,7 @@ nav: - "Model Card Template": wiki-guide/HF_ModelCard_Template_mkdocs.md - Quick References: - "Command Line Cheat Sheet": wiki-guide/Command-Line-Cheat-Sheet.md - - "GitHub-PyPI-Zenodo Versioning": wiki-guide/GitHub-PyPI-Zenodo-Integration.md + - "PyPI & Zenodo Release Automation": wiki-guide/GitHub-PyPI-Zenodo-Integration.md - Code of Conduct: CODE_OF_CONDUCT.md - Digital Product Policy: - "About Digital Product Policies": wiki-guide/About-Digital-Product-Policies.md From 1632b3ad5e329f7e05109db8b08395402b76ab36 Mon Sep 17 00:00:00 2001 From: egrace479 Date: Tue, 5 May 2026 19:12:58 -0400 Subject: [PATCH 4/7] Apply linting fix, ignore ellipsis for one header --- docs/wiki-guide/GitHub-PyPI-Zenodo-Integration.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/wiki-guide/GitHub-PyPI-Zenodo-Integration.md b/docs/wiki-guide/GitHub-PyPI-Zenodo-Integration.md index 5048df4..f12c394 100644 --- a/docs/wiki-guide/GitHub-PyPI-Zenodo-Integration.md +++ b/docs/wiki-guide/GitHub-PyPI-Zenodo-Integration.md @@ -10,16 +10,16 @@ This page is a quick reference for setting up a repository to automatically rele ## Before Generating a Release -### Set version in... +### Set version in... - `__about__.py` file - Version should be set *dynamically* in the `pyproject.toml` from this file.* - [`CITATION.cff`](GitHub-Repo-Guide.md#citation-templates) - [`.zenodo.json`](GitHub-Repo-Guide.md#zenodo-metadata) -### Add/Update Citation and Zenodo Metadata Files +### Add/Update Citation and Zenodo Metadata Files -Review or create both a [`CITATION.cff`](GitHub-Repo-Guide.md#citation) and [`.zenodo.json`](GitHub-Repo-Guide.md#zenodo-metadata) file following guide instructions. Be sure to include +Review or create both a [`CITATION.cff`](GitHub-Repo-Guide.md#citation) and [`.zenodo.json`](GitHub-Repo-Guide.md#zenodo-metadata) file following guide instructions. Be sure to include !!! tip "Pro tip" Add this [test to validate the Zenodo metatdata file](https://github.com/Imageomics/Collaborative-distributed-science-guide/blob/main/.github/workflows/validate-zenodo.yaml). It will run whenever the `.zenodo.json` or workflow file are edited, ensuring that your Zenodo integration will run smoothly. From 41cb19529c9de4a46460507567d5950fe6c4e01e Mon Sep 17 00:00:00 2001 From: egrace479 Date: Wed, 6 May 2026 09:39:06 -0400 Subject: [PATCH 5/7] Set up separate tab for first vs new release checklist --- docs/wiki-guide/GitHub-PyPI-Zenodo-Integration.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/docs/wiki-guide/GitHub-PyPI-Zenodo-Integration.md b/docs/wiki-guide/GitHub-PyPI-Zenodo-Integration.md index f12c394..6978658 100644 --- a/docs/wiki-guide/GitHub-PyPI-Zenodo-Integration.md +++ b/docs/wiki-guide/GitHub-PyPI-Zenodo-Integration.md @@ -133,16 +133,19 @@ There are a few updates required after generating a release, though the last lis - [ ] Set version tag in [citation file identifiers](GitHub-Repo-Guide.md#__codelineno-1-8) to match the updated version. The commit hash of the version will be filled in *after* release. ``` -=== "After Release" - - Only one step here is required for ***every release***: Add release commit hash to `CITATION.cff` [identifiers](GitHub-Repo-Guide.md#__codelineno-1-8). - +=== "After First Release" ```Markdown - [ ] Add *version-agnostic* DOI badge to `README`*. - See [Add a Zenodo DOI Badge](DOI-Generation.md#add-a-zenodo-doi-badge) for instructions. - [ ] Add PyPI badges to `README`*. - [ ] Add *version-agnostic* DOI to `CITATION.cff`*. - - [ ] ***Every release***: Add release commit hash to `CITATION.cff` [identifiers](GitHub-Repo-Guide.md#__codelineno-1-8). + - [ ] Add release commit hash to `CITATION.cff` [identifiers](GitHub-Repo-Guide.md#__codelineno-1-8). + ``` + +=== "After Release" + + ```Markdown + - [ ] Add release commit hash to `CITATION.cff` [identifiers](GitHub-Repo-Guide.md#__codelineno-1-8). ``` [^1]: Note that this follows the [PyPI Trusted Publishers docs](https://docs.pypi.org/trusted-publishers/using-a-publisher/) to remove the need for a token, though you must first configure GitHub as a ["pending" Trusted Publisher](https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/) for the project on PyPI. From b150c43f24a52a132cfd82381853631b09996021 Mon Sep 17 00:00:00 2001 From: egrace479 Date: Wed, 6 May 2026 11:59:58 -0400 Subject: [PATCH 6/7] Fix formatting in pre-and post-release tabs to render nicely in GitHub issue --- .../GitHub-PyPI-Zenodo-Integration.md | 95 ++++++++++--------- 1 file changed, 49 insertions(+), 46 deletions(-) diff --git a/docs/wiki-guide/GitHub-PyPI-Zenodo-Integration.md b/docs/wiki-guide/GitHub-PyPI-Zenodo-Integration.md index 6978658..7f75fdf 100644 --- a/docs/wiki-guide/GitHub-PyPI-Zenodo-Integration.md +++ b/docs/wiki-guide/GitHub-PyPI-Zenodo-Integration.md @@ -79,73 +79,76 @@ There are a few updates required after generating a release, though the last lis === "First Release" ```Markdown - Set version in... - - [ ] `__about__.py` file (the only repeated PyPI update). - - Version should be set *dynamically* in the `pyproject.toml` from this file.* - - [ ] [`CITATION.cff`](GitHub-Repo-Guide.md#citation-templates). - - [ ] [`.zenodo.json`](GitHub-Repo-Guide.md#zenodo-metadata). + ### Set version in... + - [ ] `__about__.py` file (the only repeated PyPI update). + - Version should be set *dynamically* in the `pyproject.toml` from this file.* + - [ ] [`CITATION.cff`](https://imageomics.github.io/Collaborative-distributed-science-guide/wiki-guide/GitHub-Repo-Guide/#citation-templates). + - [ ] [`.zenodo.json`](https://imageomics.github.io/Collaborative-distributed-science-guide/wiki-guide/GitHub-Repo-Guide/#zenodo-metadata). - Add/Update the [citation](GitHub-Repo-Guide.md#citation) and [Zenodo metadata](GitHub-Repo-Guide.md#zenodo-metadata) files. Ensure that... - - [ ] All authors are included and appropriately ordered. - - This list may or may not change, and may differ from an associated paper author list, as discussed in the [Digital Product Lifecycle](Digital-Product-Lifecycle.md#exploration-phase) and the [Imageomics Author Guide](https://docs.google.com/spreadsheets/d/1GwlCukfoQPL8JI2yyWRD3g4uiMTO3tlGNE_qeb_xBCs/edit?usp=sharing). - - [ ] All project keywords are listed, using quotes for multi-word tags. - - [ ] The release date in both files is correct. - - !!! info - This should be added in a PR as the last commit before a release, but check that the date matches, since these PRs may not necessarily be merged on the same day they are created. - - - Set [citation file identifiers](GitHub-Repo-Guide.md#__codelineno-1-8): - - [ ] Version tag link should match the updated version. The commit hash of the version will be filled in *after* release. - - !!! note - You have not generated a release yet, so leave the `doi` key commented out; it will be added **after** release. - - - [ ] Add [test to validate Zenodo file](https://github.com/Imageomics/Collaborative-distributed-science-guide/blob/main/.github/workflows/validate-zenodo.yaml).* - - Automate publish to PyPI on release: - - [ ] Set up a [`pyproject.toml`](https://packaging.python.org/en/latest/guides/writing-pyproject-toml/) with your project repo information and dependencies. - - [ ] Include your project keywords in `pyproject.toml` (no spaces, even within quotes). - - [ ] Version in `pyproject.toml` set *dynamically*. - - [ ] Add PyPI publication workflow*. See [pybioclip workflow](https://github.com/Imageomics/pybioclip/blob/main/.github/workflows/publish-to-pypi.yml) as an example.[^1] - - [ ] Configure GitHub as a "pending" publisher on PyPI. See PyPI's ["pending" publisher docs](https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/) for instructions.* - - [ ] Update installation instructions to reflect imminent release and PyPI publication:* - `pip install ` instead of `pip install git+`. - - [ ] Turn on repository sync in your Zenodo account; this must be set specifically for the target repo. See [Automatic DOI Generation with Zenodo](DOI-Generation.md#automatic-generation) for more information. + ### Add/Update the [citation](https://imageomics.github.io/Collaborative-distributed-science-guide/wiki-guide/GitHub-Repo-Guide/#citation) and [Zenodo metadata](https://imageomics.github.io/Collaborative-distributed-science-guide/wiki-guide/GitHub-Repo-Guide/#zenodo-metadata) files. + + Ensure that... + - [ ] All authors are included and appropriately ordered. + - This list may or may not change, and may differ from an associated paper author list, as discussed in the [Digital Product Lifecycle](https://imageomics.github.io/Collaborative-distributed-science-guide/wiki-guide/Digital-Product-Lifecycle/#exploration-phase) and the [Imageomics Author Guide](https://docs.google.com/spreadsheets/d/1GwlCukfoQPL8JI2yyWRD3g4uiMTO3tlGNE_qeb_xBCs/edit?usp=sharing). + - [ ] All project keywords are listed, using quotes for multi-word tags. + - [ ] The release date in both files is correct. + > [!IMPORTANT] + > This should be added in a PR as the last commit before a release, but check that the date matches, since these PRs may not necessarily be merged on the same day they are created. + - Set [citation file identifiers](https://imageomics.github.io/Collaborative-distributed-science-guide/wiki-guide/GitHub-Repo-Guide/#__codelineno-1-8): + - [ ] Version tag link should match the updated version. The commit hash of the version will be filled in *after* release. + > [!NOTE] + > You have not generated a release yet, so leave the `doi` key commented out; it will be added **after** release. + - [ ] Add [test to validate Zenodo file](https://github.com/Imageomics/Collaborative-distributed-science-guide/blob/main/.github/workflows/validate-zenodo.yaml).* + + ### Automate publish to PyPI on release: + - [ ] Set up a [`pyproject.toml`](https://packaging.python.org/en/latest/guides/writing-pyproject-toml/) with your project repo information and dependencies. + - [ ] Include your project keywords in `pyproject.toml` (no spaces, even within quotes). + - [ ] Version in `pyproject.toml` set *dynamically*. + - [ ] Add PyPI publication workflow*. See [pybioclip workflow](https://github.com/Imageomics/pybioclip/blob/main/.github/workflows/publish-to-pypi.yml) as an example.[^1] + - [ ] Configure GitHub as a "pending" publisher on PyPI. See PyPI's ["pending" publisher docs](https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/) for instructions.* + + ### Update installation instructions to reflect imminent release and PyPI publication:* + - [ ] `pip install ` instead of `pip install git+`. + + ### Zenodo Sync + - [ ] Turn on repository sync in your Zenodo account; this must be set specifically for the target repo. See [Automatic DOI Generation with Zenodo](https://imageomics.github.io/Collaborative-distributed-science-guide/wiki-guide/DOI-Generation/#automatic-generation) for more information. ``` === "New Release" ```Markdown - Set version in... - - [ ] `__about__.py` file (the only repeated PyPI update). - - Version should be set *dynamically* in the `pyproject.toml` from this file.* - - [ ] [`CITATION.cff`](GitHub-Repo-Guide.md#citation-templates). - - [ ] [`.zenodo.json`](GitHub-Repo-Guide.md#zenodo-metadata). + ### Set version in... + - [ ] `__about__.py` file (the only repeated PyPI update). + - Version should be set *dynamically* in the `pyproject.toml` from this file.* + - [ ] [`CITATION.cff`](https://imageomics.github.io/Collaborative-distributed-science-guide/wiki-guide/GitHub-Repo-Guide/#citation-templates). + - [ ] [`.zenodo.json`](https://imageomics.github.io/Collaborative-distributed-science-guide/wiki-guide/GitHub-Repo-Guide/#zenodo-metadata). + + ### Update the [citation](https://imageomics.github.io/Collaborative-distributed-science-guide/wiki-guide/GitHub-Repo-Guide/#citation) and [Zenodo metadata](https://imageomics.github.io/Collaborative-distributed-science-guide/wiki-guide/GitHub-Repo-Guide/#zenodo-metadata) files. - Update the [citation](GitHub-Repo-Guide.md#citation) and [Zenodo metadata](GitHub-Repo-Guide.md#zenodo-metadata) files. Ensure that... - - [ ] All authors are included and appropriately ordered. - - [ ] All project keywords are listed, using quotes for multi-word tags. - - [ ] The release date in both files is correct. + Ensure that... + - [ ] All authors are included and appropriately ordered. + - [ ] All project keywords are listed, using quotes for multi-word tags. + - [ ] The release date in both files is correct. - !!! info - This should be added in a PR as the last commit before a release, but check that the date matches, since these PRs sometimes are not merged on the day they are created. + > [!IMPORTANT] + > This should be added in a PR as the last commit before a release, but check that the date matches, since these PRs sometimes are not merged on the day they are created. - - [ ] Set version tag in [citation file identifiers](GitHub-Repo-Guide.md#__codelineno-1-8) to match the updated version. The commit hash of the version will be filled in *after* release. + - [ ] Set version tag in [citation file identifiers](https://imageomics.github.io/Collaborative-distributed-science-guide/wiki-guide/GitHub-Repo-Guide/#__codelineno-1-8) to match the updated version. The commit hash of the version will be filled in *after* release. ``` === "After First Release" ```Markdown - [ ] Add *version-agnostic* DOI badge to `README`*. - - See [Add a Zenodo DOI Badge](DOI-Generation.md#add-a-zenodo-doi-badge) for instructions. + - See [Add a Zenodo DOI Badge](https://imageomics.github.io/Collaborative-distributed-science-guide/wiki-guide/DOI-Generation/#add-a-zenodo-doi-badge) for instructions. - [ ] Add PyPI badges to `README`*. - [ ] Add *version-agnostic* DOI to `CITATION.cff`*. - - [ ] Add release commit hash to `CITATION.cff` [identifiers](GitHub-Repo-Guide.md#__codelineno-1-8). + - [ ] Add release commit hash to `CITATION.cff` [identifiers](https://imageomics.github.io/Collaborative-distributed-science-guide/wiki-guide/GitHub-Repo-Guide/#__codelineno-1-8). ``` === "After Release" ```Markdown - - [ ] Add release commit hash to `CITATION.cff` [identifiers](GitHub-Repo-Guide.md#__codelineno-1-8). + - [ ] Add release commit hash to `CITATION.cff` [identifiers](https://imageomics.github.io/Collaborative-distributed-science-guide/wiki-guide/GitHub-Repo-Guide/#__codelineno-1-8). ``` [^1]: Note that this follows the [PyPI Trusted Publishers docs](https://docs.pypi.org/trusted-publishers/using-a-publisher/) to remove the need for a token, though you must first configure GitHub as a ["pending" Trusted Publisher](https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/) for the project on PyPI. From d583789883a7325405118137f2cae09b380c6502 Mon Sep 17 00:00:00 2001 From: egrace479 Date: Wed, 6 May 2026 12:01:19 -0400 Subject: [PATCH 7/7] Match page heading to name in sidebar --- docs/wiki-guide/GitHub-PyPI-Zenodo-Integration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/wiki-guide/GitHub-PyPI-Zenodo-Integration.md b/docs/wiki-guide/GitHub-PyPI-Zenodo-Integration.md index 7f75fdf..7e598c8 100644 --- a/docs/wiki-guide/GitHub-PyPI-Zenodo-Integration.md +++ b/docs/wiki-guide/GitHub-PyPI-Zenodo-Integration.md @@ -1,4 +1,4 @@ -# GitHub-PyPI-Zenodo Versioning and Release Version Guide +# PyPI & Zenodo Release Automation This page is a quick reference for setting up a repository to automatically release to the [Python Package Index (PyPI)](https://pypi.org/) and [Zenodo](https://zenodo.org/) on a GitHub release. At the bottom of the page are [checklists](#release-checklist) for first-time releases, new releases, and post-release steps. These are set up to be copied into a relevant issue on your GitHub repository for easier tracking.