[DEV] Py Pkg Gen v2.2.1-dev1 Release

Release Version '' into 'master' Branch
boromir674 · Mar 13, 2024 · b7ec981 · b7ec981
2 parents cb22a11 + cf582ca
commit b7ec981
Show file tree

Hide file tree

Showing 14 changed files with 210 additions and 33 deletions.
diff --git a/.github/labeler.yml b/.github/labeler.yml
@@ -136,6 +136,7 @@ release:
 # [GITOPS]: This should act as a signal, ie for a Listener Workflow to Merge the PR
 boarding_auto:
   - base-branch: ['^boarding-auto', 'boarding-auto']
+  - base-branch: ['^board-n-release', 'board-n-release']
 
 
 # Add 'feature' label to any PR where the head branch name starts with

diff --git a/.github/workflows/merge-rt-in-release.yml b/.github/workflows/merge-rt-in-release.yml
@@ -10,20 +10,26 @@ name: Merge RT in Release
 #  - test-distro-docs
 #  - direct-onboarding
 
+# OR
+
+# WHEN a tag 'start-train' is pushed t branch 'release-train'
+
 # THEN
 #   1. Open PR: 'release-train' --> 'release'
 #   2. Enable PR "Auto Merge"
 
 on:
+  push:
+    tags:
+      - start-train
   pull_request:
     # When a pull request merges, the pull request is automatically closed.
     # https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#running-your-pull_request-workflow-when-a-pull-request-merges
     types: [closed]
     branches:  # ALLOWED Base Branches
       - release-train
-  push:
-    tags:
-      - start-train
+env:
+  TRAIN: 'release-train'   # MUST match value from above: on.pull_request.branches.0
 
 jobs:
   # RUN Job when 'sth' --> 'release-train' PR is merged
@@ -35,7 +41,6 @@ jobs:
     env:
       GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
       MAIN_BR: 'master'
-      TRAIN: 'release-train'
       RELEASE_BR: 'release'
     steps:
       - uses: actions/checkout@v4
@@ -49,6 +54,21 @@ jobs:
           (git branch --track "${{ env.RELEASE_BR }}" "origin/${{ env.RELEASE_BR }}" && git rebase ${{ env.MAIN_BR }} && git push) || echo "Branch '${{ env.RELEASE_BR }}' does NOT exist in remote Origin"
           git checkout ${{ env.RELEASE_BR }} || (git checkout -b ${{ env.RELEASE_BR }} ${{ env.MAIN_BR }} && git push origin -u ${{ env.RELEASE_BR }})
 
+      # if triggered by pushed tag then make sure tag was pushed to release-train
+      - name: "Find whether '${{ github.ref }}' tag is on '${{ env.TRAIN }}' branch"
+        if: github.event_name == 'push'
+        uses: rickstaa/action-contains-tag@v1
+        id: tag_on_release_train
+        with:
+          reference: ${{ env.TRAIN }}
+          tag: "${{ github.ref }}"
+
+      - name: Abort if pushed tag in NOT on '${{ env.TRAIN }}' branch
+        if: github.event_name == 'push' && steps.tag_on_release_train.outputs.retval != 'true'
+        run: |
+            echo "[ERROR] Tag '${{ github.ref }}' was pushed, but not on '${{ env.TRAIN }}' branch. Aborting Workflow.."
+            exit 1
+
       ####### PR: Train --> Release #######
       - name: "Create PR  'head': ${{ env.TRAIN }}  -->  'base': ${{ env.RELEASE_BR }}"
         run: |

diff --git a/.github/workflows/merge-to-boarding.yml b/.github/workflows/merge-to-boarding.yml
@@ -4,15 +4,18 @@ on:
   pull_request:  # PR:  <Head Branch>  -->  <Base Branch>
     types: [labeled]
     branches:   # Base Branches (aka Target)
-      - boarding-auto
+      - boarding-auto  # signals automatic release immediately after boarding
+      - boarding-auto*
+      - board-n-release  # signals to just board train (potentially along with others)
+      - board-n-release*
 
 
 jobs:
   boarding_train:
     if: github.event.label.name == 'boarding_auto'
     runs-on: ubuntu-latest
     env:
-      MAIN_BRANCH: ${{ vars.MAIN_BRANCH || 'master' }}
+      MAIN_BRANCH: ${{ vars.MAIN_BRANCH || 'main' }}
       DIRECT_ONBOARDING_BR: direct-onboarding
     steps:
       - uses: actions/checkout@v4
@@ -116,7 +119,11 @@ jobs:
         run: "gh pr merge \"${{ env.PR_ID }}\" --merge --subject \"${{ env.BOARDING_MSG }}\""
 
       # DETERMINES what will the Required Checks be, while PR is on `Auto Merge`
-      - run: echo TARGET_BRANCH="${{ steps.merge_msg.outputs.TARGET_BRANCH }}-${{ env._USER_BR }}" >> $GITHUB_ENV
+      - if: startsWith(env._BOARDING_BR, 'boarding-auto')
+        run: echo TARGET_BRANCH="${{ steps.merge_msg.outputs.TARGET_BRANCH }}-${{ env._USER_BR }}" >> $GITHUB_ENV
+
+      - if: startsWith(env._BOARDING_BR, 'board-n-release')
+        run: echo TARGET_BRANCH="${{ steps.merge_msg.outputs.TARGET_BRANCH }}" >> $GITHUB_ENV
 
       - name: Ensure '${{ env.TARGET_BRANCH }}' Branch is on Remote origin
         run: git branch --track ${{ env.TARGET_BRANCH }} "origin/${{ env.TARGET_BRANCH }}" || git checkout -b ${{ env.TARGET_BRANCH }} "origin/${{ env.MAIN_BRANCH }}" && git push origin ${{ env.TARGET_BRANCH }}
@@ -127,11 +134,25 @@ jobs:
           GITHUB_TOKEN: ${{ secrets.GH_TOKEN }}
         run: |
           gh pr create --head "${{ env._BOARDING_BR }}" --base "${{ env.TARGET_BRANCH }}" \
-            --title "Identifying and running Required Checks, before being accepted into Release Train" \
-            --body "Merging into ${{ env.TARGET_BRANCH }}, to run Required Checks before being accepted into the Release Train.
+            --title "Dynamic Automated Checks: Merging '${{ env._BOARDING_BR }}' into '${{ env.TARGET_BRANCH }}' Branch" \
+            --body "## :test_tube: Dynamic Automated Checks :test_tube:
+
+          This PR is automatically generated by a GitHub Action workflow. It's part of the process of 'Testing before Accepting onto the Train', setting the stage for the next steps in our GitOps journey.
+
+          ### What's Happening Here?
+
+          - We're merging changes from `${{ env._BOARDING_BR }}` into the `${{ env.TARGET_BRANCH }}` branch.
+          - The Head branch '${{ env._BOARDING_BR }}' commit message, was derived from the PR labels of previous GitOps PR (aka phase).
+          - This message dynamically configure the CI/CD Pipeline
+
+          - The Base branch ${{ env.TARGET_BRANCH }} was derived from the PR labels of previous GitOps PR (aka phase).
+          - This PR expects the Head branch to have a set of Required Checks, as per GitHub Protection Rules.
+
+          ### :white_check_mark: Automatic Merging :white_check_mark:
 
-            The Required Checks are defined in the Protection Rules of '${{ env.TARGET_BRANCH }}' branch.
-            "
+          - This PR is designed to **automatically merge** once all CI checks pass.
+          - The assumption is that the CI/CD Pipeline will run the same set of checks as the Required Checks on the Target Branch!
+          "
 
       ## Auto Merge PR 'boarding-auto'  -->  env.TARGET_BRANCH  Branch with `Required Checks` ##
       - name: 'Enable Auto Merge'

diff --git a/.github/workflows/merge-to-train.yml b/.github/workflows/merge-to-train.yml
@@ -69,7 +69,7 @@ jobs:
           GITHUB_TOKEN: ${{ secrets.GH_TOKEN }}
         run: |
           gh pr create --head "${{ env.INCOMING_BR }}" --base "${{ env.TRAIN }}" \
-            --title "Merging '${{ env.INCOMING_BR }}', carrying '${{ steps.user_branch.outputs.USER_BRANCH }}', into '${{ env.TRAIN }}'" \
+            --title "Merging '${{ env.INCOMING_BR }}', into '${{ env.TRAIN }}'" \
             --body "## :train: Boarding onto the Release Train :train:
 
           This PR is automatically generated by a GitHub Action workflow. It's part of the process of boarding changes onto the **Release Train** branch, setting the stage for the next steps in our GitOps journey.

diff --git a/.github/workflows/pr-to-boarding.yml b/.github/workflows/pr-to-boarding.yml
@@ -8,12 +8,14 @@ on:
   push:
     tags:
       - board-request
+      - board-n-release
 
 jobs:
   pr_to_boarding:
     uses: boromir674/automated-workflows/.github/workflows/go-pr-to-boarding.yml@test
     with:
-      boarding_branch: ${{ vars.BOARDING_BRANCH || 'boarding-auto' }}
-      main_branch: ${{ vars.MAIN_BRANCH || 'master' }}
+      # pass tag to PR from <user_branch>  -->  <github.ref>-<user_branch>
+      board_tag: "${{ github.ref }}"
+      main_branch: ${{ vars.MAIN_BRANCH || 'main' }}
     secrets:
       github_pat: ${{ secrets.GH_TOKEN }}
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
@@ -2,6 +2,27 @@
 Changelog
 =========
 
+2.2.1-dev1 (2024-03-13)
+=======================
+
+Changes
+^^^^^^^
+
+documentation
+"""""""""""""
+- update README to emphasize that our CI frontend is based on tox 3.x
+- fix example User Config YAML, in README quickstart section
+
+gitops
+""""""
+- allow on-demand merging of RT into Release
+- add GitOps Process supporting boarding multiple Topic Branches in RT, before Releasing
+
+build
+"""""
+- do poetry update
+
+
 2.2.1 (2024-03-11)
 ==================
 

diff --git a/README.rst b/README.rst
@@ -49,7 +49,7 @@ Link: https://github.com/boromir674/biskotaki/actions/runs/4157571651
    a. **Job Matrix**, spanning different `platform`'s and `python version`'s
 
       1. Platforms: `ubuntu-latest`, `macos-latest`
-      2. Python Interpreters: `3.6`, `3.7`, `3.8`, `3.9`, `3.10`
+      2. Python Interpreters: `3.7`, `3.8`, `3.9`, `3.10`, `3.11`, `3.12`
    b. **Parallel Job** execution, generated from the `matrix`, that runs the `Test Suite`
    c. **Artifact** store of **Source** and **Wheel** Distributions, factoring Platform and Python Version
 
@@ -88,7 +88,7 @@ Next, **create** a file, let's call it ``gen-config.yml``, with the following co
         email: john.doe@something.org
         github_username: john-doe
         project_short_description: 'Demo Generated Project Description'
-        initialize_git_repo: no
+        initialize_git_repo: 'no'
         interpreters: {"supported-interpreters": ["3.8", "3.9", "3.10", "3.11"]}
 
 
@@ -111,7 +111,7 @@ To leverage all out-of-the-box development operations (ie scripts), install `tox
 
 .. code-block:: shell
 
-    python3 -m pip install --user 'tox<4'
+    python3 -m pip install --user 'tox==3.27.1'
 
 To verify tox available in your environment, run: ``tox --version``
 
@@ -275,9 +275,9 @@ Free/Libre and Open Source Software (FLOSS)
 
 .. Github Releases & Tags
 
-.. |commits_since_specific_tag_on_master| image:: https://img.shields.io/github/commits-since/boromir674/cookiecutter-python-package/v2.2.1/master?color=blue&logo=github
+.. |commits_since_specific_tag_on_master| image:: https://img.shields.io/github/commits-since/boromir674/cookiecutter-python-package/v2.2.1-dev1/master?color=blue&logo=github
     :alt: GitHub commits since tagged version (branch)
-    :target: https://github.com/boromir674/cookiecutter-python-package/compare/v2.2.1..master
+    :target: https://github.com/boromir674/cookiecutter-python-package/compare/v2.2.1-dev1..master
 
 .. |commits_since_latest_github_release| image:: https://img.shields.io/github/commits-since/boromir674/cookiecutter-python-package/latest?color=blue&logo=semver&sort=semver
     :alt: GitHub commits since latest release (by SemVer)

diff --git a/docs/conf.py b/docs/conf.py
@@ -30,7 +30,7 @@
 author = 'Konstantinos Lampridis'
 
 # The full version, including alpha/beta/rc tags
-release = '2.2.1'
+release = '2.2.1-dev1'
 
 # -- General configuration ---------------------------------------------------
 
@@ -88,7 +88,9 @@
 on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
 
 # if not on_rtd:  # only set the theme if we're building docs locally
-#     html_theme = 'sphinx_rtd_theme'
+# html_theme = 'sphinx_rtd_theme'
+# html_theme = 'sphinx_material'
+# html_theme = 'sphinx_book_theme'
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,

diff --git a/docs/contents/35_development/gitops-multi-topics-cheatsheet.md b/docs/contents/35_development/gitops-multi-topics-cheatsheet.md
@@ -0,0 +1,106 @@
+
+# Board Train and Release - Cheatsheet
+
+**Requires:**
+- GITHUB **Auto Merge** is ON, for Repo
+
+*Assumes:*
+- the User / Developer made all their changes on a **`User Br`** branch
+- there is a dedicated **`master`** branch, for tagged production commits (public API)
+- Protection Rules, with suitable Required Checks for branches
+  - `master`
+  - `release-train`
+  - `test-distro`
+  - `test-docs`
+  - `test-distro-docs`
+
+**START**
+
+Running on **Linux shell.**
+
+```shell
+function git-tag { git tag -d "$1" || true; git tag "$1" && (git push origin -d "$1" || true); git push origin "$1"; }
+function parse-version { grep -E -o '^version\s*=\s*\".*\"' pyproject.toml | cut -d'"' -f2; }
+```
+
+REPEAT for all `Topical Branches`, branching off of **`master`:**
+
+```shell
+git-tag board-request
+```
+
+EVERY topic branch should now be in **`origin/release-train`.**
+
+```shell
+git fetch
+git checkout origin/release-train
+git-tag start-train
+```
+
+**Wait** for **PR** *opened* **'release' --> 'master'**
+- https://github.com/boromir674/cookiecutter-python-package/pulls?q=is%3Apr+is%3Aopen+base%3Amaster
+
+```shell
+git fetch && (git checkout release || git branch --track release origin/release) && git pull origin release
+```
+**`Sem Ver` + `Changelog`** updates on **release** branch
+
+- [OPT1]\: For **Public API** Releases
+
+    ```shell
+    ./scripts/auto-release.sh
+    ```
+
+- [OPT2]\: For **Internal** Releases
+
+    1. Do **Sem Ver** source updates and commits (1 or more files)
+    2. Do **Changelog** update and commit (1 file)
+    3. Run
+        ```shell
+        git push origin release
+        git-tag auto-prod
+        ```
+
+1. **Code Review PR on Github**
+
+    Go to PRs to 'master':  
+    https://github.com/boromir674/cookiecutter-python-package/pulls?q=is%3Apr+is%3Aopen+base%3Amaster
+
+Expect **PR Merge** to **`master`**, after all **Required Checks** Pass!
+**Git Tag** is automatically pushed after that!
+
+**Simply Wait** until that happens!
+
+Now, make a **new Release:**
+
+```shell
+git checkout master && git pull && git push
+export tt="v$(parse-version)"
+gh release create "$tt"
+```
+**--> !! DONE !! <--**
+
+Clean Origin Git with:
+
+```shell
+# Delete Git Ops TAGS
+git push origin -d board-request
+git push origin -d auto-prod
+
+# Delete Git Ops BRANCHES
+git push origin -d boarding-auto
+
+git push origin -d test-docs
+git push origin -d test-distro
+git push origin -d test-distro-docs
+git push origin -d direct-onboarding
+
+git push origin -d release-train
+git push origin -d release
+```
+
+Clean Local with:
+```shell
+git tag -d board-request
+git tag -d auto-prod
+```
diff --git a/docs/contents/35_development/gitops-v2-cheatsheet.md b/docs/contents/35_development/gitops-v2-cheatsheet.md
@@ -27,7 +27,7 @@ From your **`User Br`** Branch:
 
 ```shell
 git push
-git-tag board-request
+git-tag board-n-release
 ```
 
 **Wait** for **PR** *opened* **'release' --> 'master'**

diff --git a/docs/contents/35_development/index.rst b/docs/contents/35_development/index.rst
@@ -32,12 +32,16 @@ GitOps Guides
 
    <!-- TODO: style such as that at least 2 blocks can be allowed next to each other, when (responsive) space allows -->
    <!-- NEW -->
-      <div style="display: flex; flex-wrap: wrap; gap: 20px; justify-content: space-around;">
-         <div style="border: 1px solid #ddd; border-radius: 8px; box-shadow: 0 2px 4px rgba(0,0,0,0.1); width: 300px; padding: 20px; margin: 10px;">
-               <h3 style="color: #0056b3;"><a style="color: #0056b3;" href="gitops-v2.html">Publish my Branch</a></h3>
-               <p>Build, Stress Test, and Release in 4 Steps. <a style="color: #0056b3;" href="gitops-v2-cheatsheet.html">Cheat Sheet</a></p>
-         </div>
-    </div>
+   <div style="display: flex; flex-wrap: wrap; gap: 20px; justify-content: space-around;">
+      <div style="border: 2px solid #333; border-radius: 8px; box-shadow: 0 2px 4px rgba(0,0,0,0.2); width: 300px; padding: 20px; margin: 10px;">
+            <h3><a href="gitops-v2.html">Publish my Branch</a></h3>
+            <p>Build, Stress Test, and Release in 4 Steps.</p><p><a href="gitops-v2-cheatsheet.html">Cheat Sheet</a></p>
+      </div>
+      <div style="border: 2px solid #333; border-radius: 8px; box-shadow: 0 2px 4px rgba(0,0,0,0.2); width: 300px; padding: 20px; margin: 10px;">
+            <h3><a href="gitops-multi-topics-cheatsheet.html">Board Train and Release - Cheatsheet</a></h3>
+            <p>Build, Stress Test, and Release in 4 Steps.</p>
+      </div>
+   </div>
 
 
 .. Auto Publish