Merge pull request #104 from ASFHyP3/develop

Release v0.5.1

Author: jtherrmann

CHANGELOG.md

@@ -6,6 +6,21 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [PEP 440](https://www.python.org/dev/peps/pep-0440/) 
 and uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.1]
+
+### Added
+- Added `permissions` field for every GitHub Actions job in the cookiecutter template, to address https://github.com/ASFHyP3/actions/issues/220
+
+### Changed
+- Upgraded `ASFHyP3/actions` reusable actions to `v0.18.1`.
+
+### Removed
+- Removed the `sync_pr_label` input from the call to `reusable-release.yml`, so that the default value will be used.
+
+### Fixed
+- Updated README instructions for creating a HyP3 plugin. In particular, added instructions for granting the GitHub user account (e.g. `tools-bot` for `ASFHyP3` repos) sufficient permissions for performing releases.
+- The `python_version` parameter is now provided to `reusable-version-info.yml` in the `test-and-build.yml` template.
+- Changed the value of the `user` parameter for `reusable-docker-ghcr.yml` from `{{ cookiecutter.github_username }}` to `{{ '${{ github.actor }}' }}`, to match the example given by the [actions README](https://github.com/ASFHyP3/actions/blob/v0.18.0/README.md#reusable-docker-ghcryml).
 
 ## [0.5.0]
 ### Added

README.md

@@ -14,7 +14,7 @@ To create a new plugin, you'll first need to run [`cookiecutter`](https://cookie
 mamba install cookiecutter
 ```
 
- or [`pip`](https://packaging.python.org/en/latest/tutorials/installing-packages/#use-pip-for-installing):
+or [`pip`](https://packaging.python.org/en/latest/tutorials/installing-packages/#use-pip-for-installing):
 
 ```bash
 python -m pip install cookiecutter
@@ -113,44 +113,54 @@ git push -u origin develop
 
 Once the zeroth release is pushed to GitHub, we need to configure the GitHub repository settings.
 The settings detailed here are not required, but we **STRONGLY** recommend them as they make it much
- easier for others to collaborate on your project, and for you to control how the collaboration
-occurs.
-
-Go to your repository in GitHub and on the right, click "Settings", then:
-1. In main page:
-   * In the "Pull Requests" section
-     * un-click "Allow squash merging"
-     * Make sure "Automatically delete head branches" is clicked
-     * See [Pull Request section screenshot](#pr-rules) for configuration image
-2. In "Branches":
-   * make sure the default branch is "develop"
-   * Add a "Branch protection rule" for:
-     * main:
-       * set "Branch name pattern" to "main"
-       * click "Require pull request review before merging"
-       * click "Dismiss stale pull request approvals when new commits are pushed"
-       * click "Require status checks to pass before merging"
-       * click "Do not allow bypassing of the above settings"
-       * click "Restrict who can push to matching branches"
-       * Create
-       * See [Main branch rules section screenshot](#main-branch-rules) for configuration image
-     * develop:
-       * set "Branch name pattern" to "develop"
-       * click "Require pull request review before merging"
-       * click "Require status checks to pass before merging"
-       * click "Do not allow bypassing of the above settings"
-       * Create
-       * See [Develop branch rules section screenshot](#develop-branch-rules) for configuration image
-
-For both the `main` and `develop` you can restrict who can push to the branch.
-In the same page where you set the above options, you can also click "Restrict
-who can push to matching branches", then search and add the desired people/organizations
-who are allowed to push. If you set this, make sure you include the owner of your
-repository in this list - other your GitHub Actions won't work!
+easier for others to collaborate on your project, and for you to control how the collaboration occurs.
+
+Go to your repository in GitHub and click "Settings", then:
+1. In "General":
+   * Change the "Default branch" to `develop`
+   * In the "Pull Requests" section:
+     * disable "Allow squash merging"
+     * enable "Always suggest updating pull request branches"
+     * enable "Allow auto-merge"
+     * enable "Automatically delete head branches"
+2. In "Collaborators and teams":
+   * If the user you provided for the `github_username` prompt when running the cookiecutter
+     does not already have access to all repos at the organization level,
+     add the user under "Direct access" with `Role: write`.
+     For https://github.com/ASFHyP3 repos, you should add the `ASFHyP3/automation` team here,
+     which includes the `tools-bot` user.
+3. In "Branches", add a "classic branch protection rule" for:
+   * `main`:
+     * set "Branch name pattern" to `main`
+     * enable "Require a pull request before merging"
+       * enable "Require approvals"
+       * enable "Dismiss stale pull request approvals when new commits are pushed"
+     * enable "Require status checks to pass before merging"
+       * enable "Require branches to be up to date before merging"
+       * specify the status checks that you want to be required before merging
+     * enable "Do not allow bypassing the above settings"
+     * enable "Restrict who can push to matching branches"
+       * confirm that this defaults to "Organization administrators, repository administrators, and users with the Maintain role."
+   * `develop`:
+     * set "Branch name pattern" to `develop`
+     * enable "Require a pull request before merging"
+       * enable "Require approvals"
+       * enable "Dismiss stale pull request approvals when new commits are pushed"
+       * enable "Allow specified actors to bypass required pull requests"
+         * Add the user that you provided for the `github_username` prompt when running the cookiecutter.
+           This is required for allowing the [`reusable-release.yml`](https://github.com/ASFHyP3/actions/#reusable-releaseyml)
+           workflow to merge `main` back into `develop` after a release.
+           For https://github.com/ASFHyP3 repos, you should add the `ASFHyP3/automation` team here,
+           which includes the `tools-bot` user.
+     * enable "Do not allow bypassing the above settings"
+     * enable "Restrict who can push to matching branches"
+       * confirm that this defaults to "Organization administrators, repository administrators, and users with the Maintain role."
+       * Add the user that you provided for the `github_username` prompt when running the cookiecutter.
+         For https://github.com/ASFHyP3 repos, you should add the `ASFHyP3/automation` team here,
+         which includes the `tools-bot` user.
 
 For more information on how to contribute to repositories set up in this manner,
-check out GitHub's [GitHub flow](https://docs.github.com/en/get-started/quickstart/github-flow)
-article
+check out GitHub's [GitHub flow](https://docs.github.com/en/get-started/quickstart/github-flow) article.
 
 ### 6. Create a personal access key for GitHub Actions
 
@@ -184,15 +194,9 @@ So, if it doesn't already exist, we will need to  create the token.
 This access token will regularly expire unless you set them to last forever (which we don't recommend)
 so make sure to keep the token current and the secret up to date!
 
-### 7. Restart the GitHub Actions
+### 7. Make HyP3 plugin container public
 
-Now you're all setup! You should be able to navigate to your repository "Actions",
-restart the failed Workflows on `develop`, and watch it create minimal HyP3 plugin 
-container for your process.
-
-### 8. Make HyP3 plugin container public
-
-Once the Actions have successfully run, a containerized version of your plugin will be
+Once the "Test and build" GitHub Actions workflow has successfully run, a containerized version of your plugin will be
 available in the GitHub Container Registry (GHCR). You can find this plugin in the "Packages"
 section of your GitHub user/organization account. You can also `pull` it to your local
 machine for use using the command:
@@ -203,16 +207,14 @@ GHCR containers are private by default. You'll need to manually change the visib
 your container to "Public" so that HyP3 can access it. See this [GitHub Documentation](https://docs.github.com/en/packages/learn-github-packages/configuring-a-packages-access-control-and-visibility#configuring-visibility-of-packages-for-your-personal-account)
 for a step-by-step guide.
 
-## Screenshots
+### 8. Initial release
 
-### PR Rules
-![PR Rules screenshot](assets/PR_rules.png)
+After you've developed the basic functionality of your plugin,
+perform an initial release by opening and merging a PR from `develop` to `main`.
+This should create a `v0.1.0` release, assuming you did not change the `[0.1.0]` heading
+in the [CHANGELOG](./{{cookiecutter.__project_name}}/CHANGELOG.md).
 
-### Main Branch Rules
-![Main Branch Rules screenshot](assets/main_rules.png)
-
-### Develop Branch Rules
-![Develop Branch Rules screenshot](assets/develop_rules.png)
+## Screenshots
 
 ### GITHUB_PAK Permissions
 ![GITHUB_PAK Permissions screenshot](assets/PAK_permissions.png)

assets/PR_rules.png

@@ -14,4 +14,6 @@ on:
 jobs:
   call-changelog-check-workflow:
     # Docs: https://github.com/ASFHyP3/actions
-    uses: ASFHyP3/actions/.github/workflows/[email protected]
+    uses: ASFHyP3/actions/.github/workflows/[email protected]
+    permissions:
+      contents: read

assets/develop_rules.png

@@ -13,4 +13,6 @@ on:
 jobs:
   call-labeled-pr-check-workflow:
     # Docs: https://github.com/ASFHyP3/actions
-    uses: ASFHyP3/actions/.github/workflows/[email protected]
+    uses: ASFHyP3/actions/.github/workflows/[email protected]
+    permissions:
+      pull-requests: read

assets/main_rules.png

@@ -8,9 +8,9 @@ on:
       - main
 
 jobs:
-  call-release-workflow:
+  call-release-checklist-workflow:
     # Docs: https://github.com/ASFHyP3/actions
-    uses: ASFHyP3/actions/.github/workflows/[email protected].0
+    uses: ASFHyP3/actions/.github/workflows/[email protected].1
     permissions:
       pull-requests: write
     secrets:

{{cookiecutter.__project_name}}/.github/workflows/changelog.yml

@@ -8,11 +8,11 @@ on:
 jobs:
   call-release-workflow:
     # Docs: https://github.com/ASFHyP3/actions
-    uses: ASFHyP3/actions/.github/workflows/[email protected]
+    uses: ASFHyP3/actions/.github/workflows/[email protected]
+    permissions: {}
     with:
       release_prefix: {{ cookiecutter.__project_title }}
       release_branch: main
       develop_branch: develop
-      sync_pr_label: actions-bot
     secrets:
       USER_TOKEN: {{ cookiecutter.__user_github_token }}

{{cookiecutter.__project_name}}/.github/workflows/labeled-pr.yml

@@ -5,12 +5,18 @@ on: push
 jobs:
   call-secrets-analysis-workflow:
     # Docs: https://github.com/ASFHyP3/actions
-    uses: ASFHyP3/actions/.github/workflows/[email protected]
+    uses: ASFHyP3/actions/.github/workflows/[email protected]
+    permissions:
+      contents: read
 
   call-ruff-workflow:
     # Docs: https://github.com/ASFHyP3/actions
-    uses: ASFHyP3/actions/.github/workflows/[email protected]
+    uses: ASFHyP3/actions/.github/workflows/[email protected]
+    permissions:
+      contents: read
 
   call-mypy-workflow:
     # Docs: https://github.com/ASFHyP3/actions
-    uses: ASFHyP3/actions/.github/workflows/[email protected]
+    uses: ASFHyP3/actions/.github/workflows/[email protected]
+    permissions:
+      contents: read