Add silent option (#526)

* Add silent option

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Add action and workflow to remove changelog silent entry

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Make the CI happier

* Add unit test for remove placeholder

* Fix typing

* TO REMOVE point to the current branch

* Fix logic to silent the entry in the changelog only when releasing

* Don't get the changelog for silent GH release in populate release

* Debug populate-release

* Don't request metadata uselessly

* Ignore release missing known tagged released

* Fix removing placeholder in changelong

* Remove debug log

* Revert "TO REMOVE point to the current branch"

This reverts commit 7531de1.

* Add documentation

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Don't print the changelog in the job log if the release is silent

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Fix mypy errors

* Add ruff exception

* [skip ci] Comment new flag silent

* [skip ci] Comment new flag in example

* Fix doc

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Steven Silvester <[email protected]>

Author: 3 people

.github/actions/prep-release/action.yml

@@ -21,6 +21,10 @@ inputs:
     description: "If set, do not make a PR"
     default: "false"
     required: false
+  silent:
+    description: "Set a placeholder in the changelog and don't publish the release."
+    required: false
+    type: boolean
   since:
     description: "Use PRs with activity since this date or git reference"
     required: false
@@ -55,6 +59,7 @@ runs:
         export RH_VERSION_SPEC=${{ inputs.version_spec }}
         export RH_POST_VERSION_SPEC=${{ inputs.post_version_spec }}
         export RH_DRY_RUN=${{ inputs.dry_run }}
+        export RH_SILENT=${{ inputs.silent }}
         export RH_SINCE=${{ inputs.since }}
         export RH_SINCE_LAST_STABLE=${{ inputs.since_last_stable }}
 

.github/actions/publish-changelog/action.yml

@@ -0,0 +1,49 @@
+name: "Publish Changelog"
+description: "Remove silent placeholder entries in the changelog file."
+inputs:
+  token:
+    description: "GitHub access token"
+    required: true
+  target:
+    description: "The owner/repo GitHub target"
+    required: true
+  branch:
+    description: "The branch to target"
+    required: false
+  dry_run:
+    description: "If set, do not make a PR"
+    default: "false"
+    required: false
+outputs:
+  pr_url:
+    description: "The html URL of the draft GitHub release"
+    value: ${{ steps.publish-changelog.outputs.pr_url }}
+runs:
+  using: "composite"
+  steps:
+    - name: install-releaser
+      shell: bash -eux {0}
+      run: |
+        # Install Jupyter Releaser from git unless we are testing Releaser itself
+        if ! command -v jupyter-releaser &> /dev/null
+        then
+            pip install -q git+https://github.com/jupyter-server/jupyter_releaser.git@v2
+        fi
+
+    - id: publish-changelog
+      shell: bash -eux {0}
+      run: |
+        export GITHUB_ACCESS_TOKEN=${{ inputs.token }}
+        export GITHUB_ACTOR=${{ github.triggering_actor }}
+        export RH_REPOSITORY=${{ inputs.target }}
+        if [ ! -z ${{ inputs.branch }} ]; then
+          export RH_BRANCH=${{ inputs.branch }}
+        fi
+        export RH_DRY_RUN=${{ inputs.dry_run }}
+
+        python -m jupyter_releaser.actions.publish_changelog
+
+    - shell: bash -eux {0}
+      run: |
+        echo "## Next Step" >> $GITHUB_STEP_SUMMARY
+        echo "Merge the changelog update PR: ${{ steps.publish-changelog.outputs.pr_url }}" >> $GITHUB_STEP_SUMMARY

.github/workflows/prep-release.yml

@@ -15,6 +15,10 @@ on:
       post_version_spec:
         description: "Post Version Specifier"
         required: false
+      silent:
+        description: "Set a placeholder in the changelog and don't publish the release."
+        required: false
+        type: boolean
       since:
         description: "Use PRs with activity since this date or git reference"
         required: false
@@ -41,6 +45,7 @@ jobs:
           post_version_spec: ${{ github.event.inputs.post_version_spec }}
           target: ${{ github.event.inputs.target }}
           branch: ${{ github.event.inputs.branch }}
+          silent: ${{ github.event.inputs.silent }}
           since: ${{ github.event.inputs.since }}
           since_last_stable: ${{ github.event.inputs.since_last_stable }}
 

.github/workflows/publish-changelog.yml

@@ -0,0 +1,35 @@
+name: "Publish Changelog"
+on:
+  workflow_dispatch:
+    inputs:
+      token:
+        description: "GitHub access token"
+        required: true
+      target:
+        description: "The owner/repo GitHub target"
+        required: true
+      branch:
+        description: "The branch to target"
+        required: false
+
+jobs:
+  publish_changelog:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: jupyterlab/maintainer-tools/.github/actions/base-setup@v1
+      - name: Install Dependencies
+        shell: bash
+        run: |
+          pip install -e .
+      - name: Publish changelog
+        id: publish-changelog
+        uses: jupyter-server/jupyter_releaser/.github/actions/publish-changelog@v2
+        with:
+          token: ${{ secrets.ADMIN_GITHUB_TOKEN }}
+          target: ${{ github.event.inputs.target }}
+          branch: ${{ github.event.inputs.branch }}
+
+      - name: "** Next Step **"
+        run: |
+          echo "Merge the changelog update PR: ${{ steps.publish-changelog.outputs.pr_url }}"

docs/source/get_started/making_release_from_releaser.md

@@ -70,10 +70,22 @@ already uses Jupyter Releaser.
     to the next minor version directly. Note: The "next" and "patch" options
     are not available when using dev versions, you must use explicit versions
     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.
+
+  - Check "Use PRs with activity 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.
+
+  - Check "Set a placeholder in the changelog and don't publish the release" if
+    you want to carry a silent release (e.g. in case of a security release).
+    That option will change the default behavior by keeping the version
+    changelog only in the GitHub release and keeping it private (aka in _Draft_
+    state). The changelog file will only contains a placeholder to be replaced
+    by the release body once the maintainers have chosen to publish the release.
+
   - 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 draft GitHub release to the target
     repository and branch, with the draft changelog contents.
 

docs/source/get_started/making_release_from_repo.md

@@ -30,10 +30,17 @@ already uses Jupyter Releaser using workflows on its own repository.
 
 - 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.
+- Check "Use PRs with activity 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)
 
+- Check "Set a placeholder in the changelog and don't publish the release" if
+  you want to carry a silent release (e.g. in case of a security release).
+  That option will change the default behavior by keeping the version
+  changelog only in the GitHub release and keeping it private (aka in _Draft_
+  state). The changelog file will only contains a placeholder to be replaced
+  by the release body once the maintainers have chosen to publish the release.
+
 - The workflow will use the GitHub API to find the relevant pull requests and make an appropriate changelog entry.
 
 - The workflow will create a draft GitHub release to the target

docs/source/how_to_guides/convert_repo_from_releaser.md

@@ -69,7 +69,7 @@ B. Prep target repository:
   build system and for version handling.
   - If previously providing `version_info` like `version_info = (1, 7, 0, '.dev', '0')`, use a pattern like the one below in your version file:
 
-```toml
+```python
 import re
 from typing import List
 

docs/source/how_to_guides/convert_repo_from_repo.md

@@ -58,7 +58,7 @@ See checklist below for details:
   build system and for version handling.
   - If previously providing `version_info` like `version_info = (1, 7, 0, '.dev', '0')`, use a pattern like the one below in your version file:
 
-```toml
+```python
 import re
 from typing import List