From e62cfa08a88310ffdcff2258eb137314687b56fd Mon Sep 17 00:00:00 2001 From: Natalia Luzuriaga Date: Thu, 13 Feb 2025 12:56:50 -0800 Subject: [PATCH 1/3] Updated codejson cookiecutter Signed-off-by: Natalia Luzuriaga --- .DS_Store | Bin 0 -> 6148 bytes .github/codejson/hooks/post_gen_project.py | 132 ++++++++++++++++++ .../{{cookiecutter.project_name}}/code.json | 44 ++++++ .github/repometrics/cookiecutter.json | 16 --- .github/repometrics/hooks/post_gen_project.sh | 33 ----- .../{{cookiecutter.project_type}}/code.json | 10 -- 6 files changed, 176 insertions(+), 59 deletions(-) create mode 100644 .DS_Store create mode 100644 .github/codejson/hooks/post_gen_project.py create mode 100644 .github/codejson/{{cookiecutter.project_name}}/code.json delete mode 100644 .github/repometrics/cookiecutter.json delete mode 100644 .github/repometrics/hooks/post_gen_project.sh delete mode 100644 .github/repometrics/{{cookiecutter.project_type}}/code.json diff --git a/.DS_Store b/.DS_Store new file mode 100644 index 0000000000000000000000000000000000000000..96f314a69332f044406dc40dc4bf994285429569 GIT binary patch literal 6148 zcmeHK%}T>S5T32UM)c5&KgS%r2qM&@2Z<$~J@f@6t+s`PM6ox8;1l=&K9ArFc=t{G zW@l})jq#?4%)soonVs30d5t+e!+$ZW0Q3z%1Y+(38c%8K&9cS4B8r~zD^oOG& zFB_g}_^S-?vkT~mCN!fv@A;YM!}?lYBuSbTDQw~BVrTo|^ySQ7AAh@EPHXSRI=^q! z{me^Knp5g!r{mYAN4=6JMz-$F``)>z~*Z_I=Wx!`(O)h)f|Igdc|9+5ODFe#Dzhb}y$uJq Date: Thu, 13 Feb 2025 12:57:56 -0800 Subject: [PATCH 2/3] Updated workflows Signed-off-by: Natalia Luzuriaga --- .DS_Store | Bin 6148 -> 0 bytes .github/workflows/auto-changelog.yml | 15 +++ .github/workflows/contributors.yml | 130 +++++++++++++------------ .github/workflows/gitleaks.yml | 15 +++ .github/workflows/repoHygieneCheck.yml | 80 +++++++++++++++ 5 files changed, 180 insertions(+), 60 deletions(-) delete mode 100644 .DS_Store create mode 100644 .github/workflows/auto-changelog.yml create mode 100644 .github/workflows/gitleaks.yml create mode 100644 .github/workflows/repoHygieneCheck.yml diff --git a/.DS_Store b/.DS_Store deleted file mode 100644 index 96f314a69332f044406dc40dc4bf994285429569..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 6148 zcmeHK%}T>S5T32UM)c5&KgS%r2qM&@2Z<$~J@f@6t+s`PM6ox8;1l=&K9ArFc=t{G zW@l})jq#?4%)soonVs30d5t+e!+$ZW0Q3z%1Y+(38c%8K&9cS4B8r~zD^oOG& zFB_g}_^S-?vkT~mCN!fv@A;YM!}?lYBuSbTDQw~BVrTo|^ySQ7AAh@EPHXSRI=^q! z{me^Knp5g!r{mYAN4=6JMz-$F``)>z~*Z_I=Wx!`(O)h)f|Igdc|9+5ODFe#Dzhb}y$uJq> $GITHUB_OUTPUT + - # Update contributor count - - name: Checkout repository - uses: actions/checkout@v4 + - name: Update MAINTAINERS.md + run: | + {% raw %} + CONTRIBUTORS="${{ steps.get_contributors.outputs.contributors }}" + {% endraw %} - - name: Pull changes from contributors-readme-action - run: | - git pull + perl -i -pe 's/().*?()/$1 '"$CONTRIBUTORS"' $2/' MAINTAINERS.md - - name: Get repository contributors count - id: get_contributors - # https://docs.github.com/en/rest/repos/repos?apiVersion=2022-11-28#list-repository-contributors - # https://docs.github.com/en/graphql/reference/objects#repositorycollaboratorconnection - # https://docs.github.com/en/graphql/guides/forming-calls-with-graphql#communicating-with-graphql - # CANNOT have newlines! - run: | - {% raw %} - OWNER=$(echo $GITHUB_REPOSITORY | cut -d'/' -f1) - REPO=$(echo $GITHUB_REPOSITORY | cut -d'/' -f2) - QUERY='query { repository(owner: \"'"$OWNER"'\", name: \"'"$REPO"'\") { collaborators { totalCount } } }' - CONTRIBUTORS=$(curl -s -X POST -H "Authorization: bearer ${{ secrets.GITHUB_TOKEN }}" -H "Content-Type: application/json" -d "{\"query\": \"$QUERY\"}" https://api.github.com/graphql | jq -r '.data.repository.collaborators.totalCount') - echo "Total contributors: $CONTRIBUTORS" - echo "contributors=$CONTRIBUTORS" >> $GITHUB_OUTPUT - {% endraw %} + git config user.name 'github-actions[bot]' + git config user.email 'github-actions[bot]@users.noreply.github.com' + git add MAINTAINERS.md + git commit -m "update contributors count to $CONTRIBUTORS" || exit 0 - - name: Replace slug in MAINTAINERS.md with number of contributors - # https://stackoverflow.com/questions/10613643/replace-a-unknown-string-between-two-known-strings-with-sed - run: | - {% raw %} - CONTRIBUTORS=${{ steps.get_contributors.outputs.contributors }} - sed -i 's/.*/ '"$CONTRIBUTORS"' /g' MAINTAINERS.md - {% endraw %} + - name: Push protected + uses: CasperWA/push-protected@v2 + with: + {% raw %} + token: ${{ secrets.PUSH_TO_PROTECTED_BRANCH }} + {% endraw %} - - name: Commit and push changes - # https://github.com/orgs/community/discussions/26560#discussioncomment-3531273 - # commit changes, but if no changes exist, then exit cleanly - run: | - git config user.name 'github-actions[bot]' - git config user.email 'github-actions[bot]@users.noreply.github.com' - git add MAINTAINERS.md - git commit -m "BOT: Update contributors info in MAINTAINERS.md" || exit 0 - git push + branch: main \ No newline at end of file diff --git a/.github/workflows/gitleaks.yml b/.github/workflows/gitleaks.yml new file mode 100644 index 0000000..94ae3f0 --- /dev/null +++ b/.github/workflows/gitleaks.yml @@ -0,0 +1,15 @@ +name: Check for Secrets +on: + pull_request: + push: + +jobs: + scan-for-secrets: + name: Run gitleaks + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + with: {fetch-depth: 0} + + - name: Check for GitLeaks + uses: gacts/gitleaks@v1 \ No newline at end of file diff --git a/.github/workflows/repoHygieneCheck.yml b/.github/workflows/repoHygieneCheck.yml new file mode 100644 index 0000000..043e706 --- /dev/null +++ b/.github/workflows/repoHygieneCheck.yml @@ -0,0 +1,80 @@ +name: "Repository Hygiene Check" +on: + push: + branches: + - 'main' + workflow_dispatch: + +jobs: + check-first-run: + name: Check For First Run + runs-on: ubuntu-latest + outputs: + {% raw %} + should_run: ${{ steps.check.outputs.should_run }} + {% endraw %} + permissions: + contents: read + pull-requests: write + steps: + - uses: actions/checkout@v4 + - id: check + run: | + # If manually triggered, always run + {% raw %} + if [[ "${{ github.event_name }}" == "workflow_dispatch" ]]; then + {% endraw %} + echo "should_run=true" >> $GITHUB_OUTPUT + exit 0 + fi + + # Check if initialization label exists + has_label=$(gh label list --json name | jq '.[] | select(.name=="repolinter-initialized")') + + if [[ -z "$has_label" ]]; then + # First time - create label and allow run + gh label create repolinter-initialized --description "Marks repo as having run initial repolinter check" + echo "should_run=true" >> $GITHUB_OUTPUT + else + echo "should_run=false" >> $GITHUB_OUTPUT + fi + env: + {% raw %} + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + {% endraw %} + + resolve-repolinter-json: + name: Get Repolinter Config + needs: check-first-run + {% raw %} + if: needs.check-first-run.outputs.should_run == 'true' + {% endraw %} + uses: DSACMS/repo-scaffolder/.github/workflows/extendJSONFile.yml@main + with: + url_to_json: 'https://raw.githubusercontent.com/DSACMS/repo-scaffolder/main/tier3/%7B%7Bcookiecutter.project_slug%7D%7D/repolinter.json' + + repolinter-checks: + name: Tier 3 Checks + needs: [check-first-run, resolve-repolinter-json] + {% raw %} + if: needs.check-first-run.outputs.should_run == 'true' + {% endraw %} + runs-on: ubuntu-latest + permissions: + contents: write + pull-requests: write + env: + {% raw %} + RAW_JSON: ${{ needs.resolve-repolinter-json.outputs.raw-json }} + {% endraw %} + steps: + - uses: actions/checkout@v4 + - run: echo $RAW_JSON > repolinter.json + - uses: DSACMS/repolinter-action@main + with: + config_file: 'repolinter.json' + output_type: 'pull-request' + pull_request_labels: 'repolinter-initialized, cms-oss, cms-gov' + {% raw %} + token: ${{ secrets.REPOLINTER_AUTO_TOKEN }} + {% endraw %} \ No newline at end of file From b18dd40782ca6152df9c9096694b3d79d259edb4 Mon Sep 17 00:00:00 2001 From: Natalia Luzuriaga Date: Thu, 13 Feb 2025 13:02:33 -0800 Subject: [PATCH 3/3] Update docs Signed-off-by: Natalia Luzuriaga --- CONTRIBUTING.md | 6 +- MAINTAINERS.md | 251 ++++++++++++++++++++++++++++++++++++++++++++++-- README.md | 6 +- 3 files changed, 247 insertions(+), 16 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4a5c79f..787a9f0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -153,7 +153,9 @@ authorship metadata will be preserved. ## Documentation @@ -174,7 +176,7 @@ questions, just [shoot us an email](mailto:opensource@cms.hhs.gov). ### Security and Responsible Disclosure Policy -*Submit a vulnerability:* Vulnerability reports can be submitted through [Bugcrowd](https://bugcrowd.com/cms-vdp). Reports may be submitted anonymously. If you share contact information, we will acknowledge receipt of your report within 3 business days. +_Submit a vulnerability:_ Vulnerability reports can be submitted through [Bugcrowd](https://bugcrowd.com/cms-vdp). Reports may be submitted anonymously. If you share contact information, we will acknowledge receipt of your report within 3 business days. For more information about our Security, Vulnerability, and Responsible Disclosure Policies, see [SECURITY.md](SECURITY.md). diff --git a/MAINTAINERS.md b/MAINTAINERS.md index db8132d..97ea8fa 100644 --- a/MAINTAINERS.md +++ b/MAINTAINERS.md @@ -1,27 +1,260 @@ # Maintainers + + This is a list of maintainers for this project. See [CODEOWNERS.md](./CODEOWNERS.md) for list of reviewers for different parts of the codebase. Team members include: ## Maintainers: + -- + +- ## Approvers: -- + +- ## Reviewers: -- -| Roles | Responsibilities| Requirements | Defined by| -| -------------|:---------------|:-------------|:-------------| -| member | active contributor in the community | multiple contributions to the project. | PROJECT GitHub org Committer Team| -| reviewer | review contributions from other members | history of review and authorship in a sub-project | MAINTAINERS file reviewer entry, and GitHub Org Triage Team| -| approver | approve accepting contributions | highly experienced and active reviewer + contributor to a sub-project | MAINTAINERS file approver entry and GitHub Triage Team | -| lead | set direction and priorities for a sub-project | demonstrated responsibility and excellent technical judgement for the sub-project | MAINTAINERS file owner entry and GitHub Org Admin Team| +- + +| Roles | Responsibilities | Requirements | Defined by | +| -------- | :--------------------------------------------- | :-------------------------------------------------------------------------------- | :---------------------------------------------------------- | +| member | active contributor in the community | multiple contributions to the project. | PROJECT GitHub org Committer Team | +| reviewer | review contributions from other members | history of review and authorship in a sub-project | MAINTAINERS file reviewer entry, and GitHub Org Triage Team | +| approver | approve accepting contributions | highly experienced and active reviewer + contributor to a sub-project | MAINTAINERS file approver entry and GitHub Triage Team | +| lead | set direction and priorities for a sub-project | demonstrated responsibility and excellent technical judgement for the sub-project | MAINTAINERS file owner entry and GitHub Org Admin Team | ## Contributors + + Total number of contributors: + +# Tier 3 Release Guidelines + +{{ cookiecutter.project_repo_name }} will see regular updates and new releases. This document describes the general guidelines around how and when a new release is cut. + +## Table of Contents + +- [Versioning](#versioning) + + - [Ongoing version support](#ongoing-version-support) +- [Release Process](#release-process) + - [Goals](#goals) + - [Schedule](#schedule) + - [Communication and Workflow](#communication-and-workflow) + +- [Preparing a Release Candidate](#preparing-a-release-candidate) + - [Incorporating feedback from review](#incorporating-feedback-from-review) +- [Making a Release](#making-a-release) +- [Auto Changelog](#auto-changelog) +- [Hotfix Releases](#hotfix-releases) + +## Versioning + +{{ cookiecutter.project_repo_name }} uses [Semantic Versioning](https://semver.org/). Each release is associated with a [`git tag`](github.com/{{ cookiecutter.project_org }}/{{ cookiecutter.project_repo_name }}/tags) of the form `X.Y.Z`. + +Given a version number in the `MAJOR.MINOR.PATCH` (eg., `X.Y.Z`) format, here are the differences in these terms: + +- **MAJOR** version - make breaking/incompatible API changes +- **MINOR** version - add functionality in a backwards compatible manner +- **PATCH** version - make backwards compatible bug fixes + + + + + +### Ongoing version support + + + + + +## Release Process + +The sections below define the release process itself, including timeline, roles, and communication best practices. + +### Goals + + + +. + +### Schedule + + + +### Communication and Workflow + + + + + +## Preparing a Release Candidate + +The following steps outline the process to prepare a Release Candidate of {{ cookiecutter.project_repo_name }}. This process makes public the intention and contents of an upcoming release, while allowing work on the next release to continue as usual in `dev`. + +1. Create a _Release branch_ from the tip of `dev` named `release-x.y.z`, where `x.y.z` is the intended version of the release. This branch will be used to prepare the Release Candidate. For example, to prepare a Release Candidate for `0.5.0`: + + ```bash + git fetch + git checkout origin/dev + git checkout -b release-0.5.0 + git push -u origin release-0.5.0 + ``` + + Changes generated by the steps below should be committed to this branch later. + +2. Create a tag like `x.y.z-rcN` for this Release Candidate. For example, for the first `0.5.0` Release Candidate: + + ```bash + git fetch + git checkout origin/release-0.5.0 + git tag 0.5.0-rc1 + git push --tags + ``` + +3. Publish a [pre-Release in GitHub](proj-releases-new): + + ```md + Tag version: [tag you just pushed] + Target: [release branch] + Release title: [X.Y.Z Release Candidate N] + Description: [copy in ReleaseNotes.md created earlier] + This is a pre-release: Check + ``` + +4. Open a Pull Request to `main` from the release branch (eg. `0.5.0-rc1`). This pull request is where review comments and feedback will be collected. + +5. Conduct Review of the Pull Request that was opened. + +### Incorporating feedback from review + +The review process may result in changes being necessary to the release candidate. + +For example, if the second Release Candidate for `0.5.0` is being prepared, after committing necessary changes, create a tag on the tip of the release branch like `0.5.0-rc2` and make a new [GitHub pre-Release](proj-releases-new) from there: + +```bash +git fetch +git checkout origin/release-0.5.0 +# more commits per OMF review +git tag 0.5.0-rc2 +git push --tags +``` + +Repeat as-needed for subsequent Release Candidates. Note the release branch will be pushed to `dev` at key points in the approval process to ensure the community is working with the latest code. + +## Making a Release + +The following steps describe how to make an approved [Release Candidate](#preparing-a-release-candidate) an official release of {{ cookiecutter.project_repo_name }}: + +1. **Approved**. Ensure review has been completed and approval granted. + +2. **Main**. Merge the Pull Request created during the Release Candidate process to `main` to make the release official. + +3. **Dev**. Open a Pull Request from the release branch to `dev`. Merge this PR to ensure any changes to the Release Candidate during the review process make their way back into `dev`. + +4. **Release**. Publish a [Release in GitHub](proj-releases-new) with the following information + + - Tag version: [X.Y.Z] (note this will create the tag for the `main` branch code when you publish the release) + - Target: main + - Release title: [X.Y.Z] + - Description: copy in Release Notes created earlier + - This is a pre-release: DO NOT check + +5. **Branch**. Finally, keep the release branch and don't delete it. This allows easy access to a browsable spec. + +## Auto Changelog + +It is recommended to use the provided auto changelog github workflow to populate the project’s CHANGELOG.md file: + +```yml +name: Changelog +on: + release: + types: + - created +jobs: + changelog: + runs-on: ubuntu-latest + steps: + - name: "Auto Generate changelog" + uses: heinrichreimer/action-github-changelog-generator@v2.3 + with: + {% raw %} + token: ${{{{ secrets.GITHUB_TOKEN }}}} + {% endraw %} +``` + +This provided workflow will automatically populate the CHANGELOG.md with all of the associated changes created since the last release that are included in the current release. + +This workflow will be triggered when a new release is created. + +If you do not wish to use automatic changelogs, you can delete the workflow and update the CHANGELOG.md file manually. Although, this is not recommended. + +## Hotfix Releases + +In rare cases, a hotfix for a prior release may be required out-of-phase with the normal release cycle. For example, if a critical bug is discovered in the `0.3.x` line after `0.4.0` has already been released. + +1. Create a _Support branch_ from the tag in `main` at which the hotfix is needed. For example if the bug was discovered in `0.3.2`, create a branch from this tag: + + ```bash + git fetch + git checkout 0.3.2 + git checkout -b 0.3.x + git push -u origin 0.3.x + ``` + +2. Merge (or commit directly) the hotfix work into this branch. + +3. Tag the support branch with the hotfix version. For example if `0.3.2` is the version being hotfixed: + + ```bash + git fetch + git checkout 0.3.x + git tag 0.3.3 + git push --tags + ``` + +4. Create a [GitHub Release](proj-releases-new) from this tag and the support branch. For example if `0.3.3` is the new hotfix version: + + ```md + Tag version: 0.3.3 + Target: 0.3.x + Release title: 0.3.3 + Description: [copy in ReleaseNotes created earlier] + This is a pre-release: DO NOT check + ``` + +[proj-releases-new]: https://github.com/{{ cookiecutter.project_org }}/{{ cookiecutter.project_repo_name }}/releases/new diff --git a/README.md b/README.md index 7af2bfc..704b652 100644 --- a/README.md +++ b/README.md @@ -33,11 +33,7 @@ An up-to-date list of core team members can be found in [MAINTAINERS.md](MAINTAI ## Repository Structure - -```plaintext -. -``` - + **{list directories and descriptions}**