[DOCS] Better Section Names

Release v1.14.1-dev
boromir674 · Feb 19, 2024 · a3dbcc5 · a3dbcc5
2 parents 5786e8c + 35d409b
commit a3dbcc5
Show file tree

Hide file tree

Showing 13 changed files with 138 additions and 41 deletions.
diff --git a/.github/workflows/labeler.yaml b/.github/workflows/labeler.yaml
@@ -9,17 +9,30 @@ jobs:
       contents: read
       pull-requests: write
     runs-on: ubuntu-latest
+    # This Job behaves as a Listener to PR events, and each step is a Handler
     steps:
+      # HANDLER 1: Label PR, given file changes and Labeling Rules '.github/labeler.yml'
       - uses: actions/labeler@v5
+        with:
+          # Our PAT gives permission for label creation events to trigger listeners
+          repo-token: ${{ secrets.GH_TOKEN }}
 
-      # PR targeting 'boarding-auto' branch, needs to run CI Tests, given labels
-      ######## Merge ########
+      # checkout repo to Enable Handlers 2 and 3 to edit (write permission) PRs
+      - name: Checkout Repository
+        uses: actions/checkout@v4
+
+      # HANDLER 2: Enable 'Auto Merge', if PR targets 'boarding-auto', after labeling
+      # - name: Enable 'Auto Merge', if PR targets 'boarding-auto'
+      #   # WHEN PR  <Head>  -->  boarding-auto
+      #   if: contains(github.event.pull_request.base.ref, 'boarding-auto')
+      #   run: gh pr merge ${{ github.event.number }} --auto --merge
+      #   env:
+      #     GH_TOKEN: ${{ secrets.GH_TOKEN }}
+
+      # HANDLER 3: Enable PR 'Auto Merge', if changes come from 'boarding-auto' branch
       - name: "Merge PR, Signaling what Automated Tests to run"
+        # WHEN PR  boarding-auto  -->  <Base>
         if:  startsWith(github.head_ref, 'boarding-auto')
-        run: gh pr merge ${{ github.event.number }} --auto
+        run: gh pr merge ${{ github.event.number }} --auto --merge
         env:
           GH_TOKEN: ${{ secrets.GH_TOKEN }}
-
-      # - name: "Label PR with 'boarding-auto' label"
-      #   if: github.event_name == 'pull_request_target' && contains(github.event.pull_request.base.ref, 'boarding-auto')
-      #   run: gh pr edit ${{ github.event.number }} --add-label 'boarding-auto'
diff --git a/.github/workflows/merge-rt-in-release.yml b/.github/workflows/merge-rt-in-release.yml
@@ -95,4 +95,4 @@ jobs:
 
       ############## Merge ##############
       - name: 'Merge PR   ${{ env.TRAIN }}  -->  ${{ env.RELEASE_BR }}'
-        run: gh pr merge "${{ env.TRAIN }}" --auto --delete-branch --squash
+        run: gh pr merge "${{ env.TRAIN }}" --auto --delete-branch --merge
diff --git a/.github/workflows/merge-to-boarding.yml b/.github/workflows/merge-to-boarding.yml
@@ -3,6 +3,7 @@ on:
   pull_request:
     types: [labeled]
 
+
 jobs:
   boarding_train:
     if: github.event.label.name == 'boarding_auto'
@@ -23,28 +24,28 @@ jobs:
       - name: 'Check PR Target Branch'
         run: |
           if [ "${{ env.BASE_BR }}" != 'boarding-auto' ]; then
-            echo "[WARNING] PR is not targeted to 'boarding-auto' branch. Skipping Auto Merge, making sure Jogb is green"
+            echo "[WARNING] PR is not targeted to 'boarding-auto' branch. Skipping Auto Merge, making sure Job is green"
             exit 1
           fi
         shell: bash
       - if: ${{ failure() }}
         run: echo "Exiting gracefully"
 
-      - name: Find PR Labels
-        run: echo PR_LABELS="$(gh pr view ${{ github.event.pull_request.number }} --json labels --jq '.labels[].name')" >> $GITHUB_ENV
-
       - run: echo "TOPICAL_BR=${{ github.event.pull_request.head.ref }}" >> $GITHUB_ENV
 
       ## Derive Merge Message given PR labels
-      - name: 'Derive Merge Message, given PR labels'
+      - name: 'Derive Merge Message, from PR labels'
       # Recognized labels: ['business_logic', 'test', 'docs']
       # if 'docs' label -> Docs Tests
       # if 'business_logic' or 'test' label -> Cross-Platform Tests
+        env:
+          GH_TOKEN: ${{ secrets.GH_TOKEN }}
         run: |
           DISTRO="Distro"
           DOCS="Docs"
           buffer_string=""
 
+          PR_LABELS=$(gh pr view ${{ github.event.pull_request.number }} --json labels --jq '.labels[].name')
           for label in ${PR_LABELS}; do
             if { [ "$label" == "business_logic" ] || [ "$label" == "test" ]; } && ! [[ $buffer_string =~ $DISTRO ]]; then
               buffer_string="${buffer_string} ${DISTRO}"
@@ -54,14 +55,28 @@ jobs:
           done
 
           buffer_string=$(echo $buffer_string | sed 's/ / AND /g')
-          MERGE_MSG="Auto Merging '${TOPICAL_BR}' carrying '${buffer_string}' Changes"
+
+          if [ -z "$buffer_string" ]; then
+            echo "[WARNING] No recognized labels found."
+            echo "[DEBUG] Labels of PR:"
+            echo "$PR_LABELS"
+            echo
+            echo [INFO] Using fallback default commit message
+            MERGE_MSG="Auto Merging '${TOPICAL_BR}'"
+          else
+            MERGE_MSG="Auto Merging '${TOPICAL_BR}' carrying '${buffer_string}' Changes"
+          fi
+          echo
+          echo " ---> COMMIT MSG <---"
+          echo
+          echo "${MERGE_MSG}"
           echo "MERGE_MSG=${MERGE_MSG}" >> $GITHUB_OUTPUT
         id: merge_msg
       ############## Auto Merge ##############
       - run: echo "PR_ID=${{ github.event.pull_request.number }}" >> $GITHUB_ENV
 
       - name: 'Auto Merge PR   ${{ env.TOPICAL_BR }}  -->  ${{ env.BASE_BR }}'
-        run: "gh pr merge \"${{ env.PR_ID }}\" --auto --text \"${{ env.BOARDING_MSG }}\""
+        run: "gh pr merge \"${{ env.PR_ID }}\" --auto --merge --subject \"${{ env.BOARDING_MSG }}\""
         env:
           GH_TOKEN: ${{ secrets.GH_TOKEN }}
           BOARDING_MSG: ${{ steps.merge_msg.outputs.MERGE_MSG }}
diff --git a/.github/workflows/merge-to-train.yml b/.github/workflows/merge-to-train.yml
@@ -7,7 +7,8 @@ on:
     types: [closed]
     branches:  # ALLOWED Base Branches
       - boarding-auto
-
+# Listens to Event fired: When PR is Closed, and PR targets 'boarding-auto' branch
+# Case GITOPS: Trigger when Auto Merge PR 'User Branch' --> 'boarding-auto'
 jobs:
   merge_rt_in_release:
     if: github.event.pull_request.merged == true
@@ -16,23 +17,53 @@ jobs:
       GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
       TRAIN: 'release-train'
       RELEASE_BR: 'release'
-      BOARDING: ${{ github.event.ref == 'refs/tags/auto-release' && 'boarding-auto' || 'boarding' }}
+      # BOARDING: ${{ github.event.pull_request.base.ref == 'boarding-auto' && 'boarding-auto' || 'boarding' }}
+      BOARDING: ${{ (github.event.pull_request.base.ref == 'boarding-auto' || github.event.ref == 'refs/tags/auto-release') && 'boarding-auto' || 'boarding' }}
       MAIN_BR: 'master'
     steps:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0  # 0 indicates all history for all branches and tags.
           set-safe-directory: ''  # `git config --global --add safe.directory <path>`
           token: '${{ secrets.GH_TOKEN }}'
+
+      - name: "Ensure Upstream '${{ env.MAIN_BR }}' is tracked (has local counterpart)"
+        run: git branch --track "${{ env.MAIN_BR }}" "origin/${{ env.MAIN_BR }}" || echo "[WARNING] Branch '${{ env.MAIN_BR }}' already exists locally"
 
-      # Track the remote branches
-      - run: git branch --track "${{ env.BOARDING }}" "origin/${{ env.BOARDING }}" || echo "Branch '${{ env.BOARDING }}' already exists"
-      - run: git branch --track "${{ env.TRAIN }}" "origin/${{ env.TRAIN }}" || echo "Branch '${{ env.TRAIN }}' already exists"
+      - name: "Ensure Upstream '${{ env.BOARDING }}' is tracked (has local counterpart)"
+        run: git branch --track "${{ env.BOARDING }}" "origin/${{ env.BOARDING }}" || echo "[WARNING] Branch '${{ env.BOARDING }}' already exists locally"
+
+      # either create a Train branch on top of master unless its Upstream exists (just track it)
+      - run: git branch --track "${{ env.TRAIN }}" "origin/${{ env.TRAIN }}" || true
+
+      - name: "Search for '${{ env.TRAIN }}' in local Branches"
+        run: |
+          LOCAL_TRAIN=$(git branch --list ${{ env.TRAIN }})
+          echo "[DEBUG] LOCAL_TRAIN:"
+          echo "${LOCAL_TRAIN}"
+          echo "LOCAL_TRAIN=${LOCAL_TRAIN}" >> $GITHUB_ENV
+
+      - run: echo "TRAIN_EXISTS=${{ env.LOCAL_TRAIN == '' && 'false' || 'true' }}" >> $GITHUB_ENV
+
+      - if: ${{ env.TRAIN_EXISTS == 'false' }}
+        run: |
+          echo "[INFO] Branch '${{ env.TRAIN }}' does not exist. Creating it .."
+          git checkout -b ${{ env.TRAIN }} ${{ env.MAIN_BR }}
+          git push origin ${{ env.TRAIN }}
 
       ############## PR ##############
-      - name: 'Create PR   ${{ env.BOARDING }}  -->  ${{ env.TRAIN }}'
-        # --head is the branch where the changes were developed
-        # --base is the branch you want to merge the changes into
+      - name: Sanity Check that '${{ env.BOARDING }}' and '${{ env.TRAIN }}' branches exist
+        run: |
+          if [ -z "$(git branch --list ${BOARDING})" ]; then
+            echo "[ERROR] Branch '${BOARDING}' does not exist. Exiting .."
+            exit 1
+          fi
+          if [ -z "$(git branch --list ${TRAIN})" ]; then
+            echo "[ERROR] Branch '${TRAIN}' does not exist. Exiting .."
+            exit 1
+          fi
+
+      - name: "Create PR  Head: '${{ env.BOARDING }}''  -->  Base: '${{ env.TRAIN }}'"
         env:
           GITHUB_TOKEN: ${{ secrets.GH_TOKEN }}
         run: |
@@ -65,7 +96,7 @@ jobs:
 
       ############## Merge ##############
       - name: 'Merge PR   ${{ env.BOARDING }}  -->  ${{ env.TRAIN }}'
-        run: gh pr merge "${{ env.BOARDING }}" --auto
+        run: gh pr merge "${{ env.BOARDING }}" --auto --merge
         # --delete-branch --squash
         env:
           GH_TOKEN: ${{ secrets.GH_TOKEN }}

diff --git a/.github/workflows/pr-to-boarding.yml b/.github/workflows/pr-to-boarding.yml
@@ -27,7 +27,7 @@ jobs:
       - name: Discover User's Branch Name
         id: user_branch
         run: |
-          name=$(git branch -a --contains "$(git rev-parse HEAD)" | sed -n '2p' | sed 's/.*remotes\///')
+          name=$(git branch -a --contains "$(git rev-parse HEAD)" | sed -n '2p' | sed 's/.*origin\///')
           echo "NAME:" $name
           echo USER_BRANCH=$name >> $GITHUB_OUTPUT
 
@@ -38,8 +38,12 @@ jobs:
       ### Put User Branch on Boarding Branch to Test before merging to Release Train
       # Create Upstream 'Boarding' Branch
       - run: git checkout ${{ env.MAIN_BR }}
-      - run: git checkout -b ${{ env.BOARDING_BR }}
-      - run: git push origin --delete ${{ env.BOARDING_BR }} || echo "Remote Branch    '${{ env.BOARDING_BR }}' does not exist"
+      - run: git branch --track "origin/${{ env.BOARDING_BR }}" || echo "Remote Branch '${{ env.BOARDING_BR }}' does not exist"
+      - run: git checkout -b ${{ env.BOARDING_BR }} || git checkout ${{ env.BOARDING_BR }}
+
+      - run: git checkout ${{ steps.user_branch.outputs.USER_BRANCH }}
+      - run: git rebase ${{ env.BOARDING_BR }}
+      - run: git push -u origin ${{ steps.user_branch.outputs.USER_BRANCH }}
 
       - run: git config --global user.email "[email protected]"
       - run: git config --global user.name "Konstantinos Lampridis"

diff --git a/.github/workflows/test.yaml b/.github/workflows/test.yaml
@@ -56,6 +56,7 @@ env:
   # 2nd level override
   ALWAYS_DOCS: "false"
   DOCS_JOB_POLICY: '2'  # {2, 3}
+  PY_VERSION: "3.11"
 
   #### STATIC CODE ANALYSIS Job ####
   ALWAYS_LINT: "false"
@@ -116,6 +117,7 @@ jobs:
           echo "TESTS_ENABLED=$RUN_UNIT_TESTS" >> $GITHUB_OUTPUT
           echo "PUBLISH_ON_PYPI=$PUBLISH_ON_PYPI" >> $GITHUB_OUTPUT
           echo "PIPE_DOCS_POLICY=$PIPE_DOCS_POLICY" >> $GITHUB_OUTPUT
+          echo "PIPE_DOCS_PY=$PY_VERSION" >> $GITHUB_OUTPUT
       ## Docker - Pipeline Settings ##
       - id: derive_docker_policy
         run: echo "POL=${{ (env.DOCKER_JOB_ON != 'true' && '0') || (env.ALWAYS_BUILD_N_PUBLISH_DOCKER == 'true' && '1') || (env.DOCKER_JOB_POLICY == 'CDeployment' && '2') || (env.DOCKER_JOB_POLICY == 'CDelivery' && '3') }}" >> $GITHUB_OUTPUT
@@ -135,6 +137,7 @@ jobs:
       PUBLISH_ON_PYPI: ${{ steps.pass-env-to-output.outputs.PUBLISH_ON_PYPI }}
     ## DOCS - Pipeline Settings ##
       PIPE_DOCS_POLICY: ${{ steps.pass-env-to-output.outputs.PIPE_DOCS_POLICY }}
+      PIPE_DOCS_PY: ${{ steps.pass-env-to-output.outputs.PIPE_DOCS_PY }}
     ## Docker - Pipeline Settings ##
       PIPE_DOCKER_POLICY: ${{ steps.derive_docker_policy.outputs.POL }}
     ## Static Code Analysis - Pipeline Settings ##
@@ -362,7 +365,7 @@ jobs:
     with:
       run_policy: '${{ needs.set_github_outputs.outputs.PIPE_DOCS_POLICY }}'
       python_version: ${{ needs.set_github_outputs.outputs.PIPE_DOCS_PY }}
-      command: "tox -e pin-docs,docs --sitepackages -vv -s false"
+      command: "tox -e pin-deps -- -E docs && tox -e docs --sitepackages -vv -s false"
 
 ### STATIC CODE ANALYSIS & LINTING ###
   lint:

diff --git a/CHANGELOG.rst b/CHANGELOG.rst
@@ -2,6 +2,38 @@
 Changelog
 =========
 
+1.14.1-dev (2024-02-19)
+=======================
+
+Changes
+^^^^^^^
+
+documentation
+"""""""""""""
+- rename Docs Page 'Usage' Section to shorter name
+
+development
+"""""""""""
+- improve tox envs
+
+ci
+""
+- fix build command we pass to Called Docs Workflow
+
+release
+"""""""
+- bump version to 1.14.1-dev
+
+gitops
+""""""
+- derive merge commit message from PR Labels
+- if release-train exists, then track Upstream, else automatically create on top of master
+- replace PR to train and release, squash with merge 'method'
+- use --merge method for 'Auto Merge'
+- enable Auto Merge on PRs targeting 'boarding-auto'
+- allow 'customly' prepared 'boarding' Branch
+
+
 1.14.0 (2024-02-18)
 ===================
 

diff --git a/README.rst b/README.rst
@@ -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/v1.14.0/master?color=blue&logo=github
+.. |commits_since_specific_tag_on_master| image:: https://img.shields.io/github/commits-since/boromir674/cookiecutter-python-package/v1.14.1-dev/master?color=blue&logo=github
     :alt: GitHub commits since tagged version (branch)
-    :target: https://github.com/boromir674/cookiecutter-python-package/compare/v1.14.0..master
+    :target: https://github.com/boromir674/cookiecutter-python-package/compare/v1.14.1-dev..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 = '1.14.0'
+release = '1.14.1-dev'
 
 # -- General configuration ---------------------------------------------------
 

diff --git a/docs/contents/30_usage/index.rst b/docs/contents/30_usage/index.rst
@@ -1,6 +1,6 @@
-===================================
-Generate New Python Package Project
-===================================
+=======================
+Generate Python Project
+=======================
 
 Our ``Python Generator`` **Project** was designed to be installable via *pip* and then invoked through
 the ``generate-python`` entrypoint to the CLI.

diff --git a/pyproject.toml b/pyproject.toml
@@ -10,7 +10,7 @@ build-backend = "poetry.core.masonry.api"
 ## Also renders on pypi as 'subtitle'
 [tool.poetry]
 name = "cookiecutter_python"
-version = "1.14.0"
+version = "1.14.1-dev"
 description = "1-click Generator of Python Project, from Template with streamlined \"DevOps\" using a powerful CI/CD Pipeline."
 authors = ["Konstantinos Lampridis <[email protected]>"]
 maintainers = ["Konstantinos Lampridis <[email protected]>"]

diff --git a/src/cookiecutter_python/__init__.py b/src/cookiecutter_python/__init__.py
@@ -1,3 +1,3 @@
-__version__ = '1.14.0'
+__version__ = '1.14.1-dev'
 
 from . import _logging  # noqa
diff --git a/tox.ini b/tox.ini
@@ -217,7 +217,7 @@ setenv =
     {[testenv]setenv}
     SPELLCHECK=1
 # tox -e pin-docs,docs
-# tox -e pin-docs -- docslive && tox -r -e live-html
+# tox -e pin-docs -- docslive && tox -r -e docs-live
 [testenv:pin-docs]
 description = 'Pin Docs Python Dependencies in requirements.txt type of format.'
 basepython = {env:TOXPYTHON:python3}
@@ -236,7 +236,7 @@ description = Populate rst files with directives to process docstrings. To force
     default filename 'modules', for the table of contents, you can use the --tocfile flag (takes 1 argument);
     eg command: tox -e apidoc -v -- --tocfile my_contents_filename
 basepython = {env:TOXPYTHON:python3}
-deps = -r req-docs.txt
+deps = -r {env:REQS_FILE:{env:DEFAULT_REQS_FILE:reqs-docs.txt}}
 skip_install = true
 commands = sphinx-apidoc -o docs/contents/33_refs/api/modules src/{env:PY_PACKAGE} {posargs}
 
@@ -248,8 +248,7 @@ description = Build the documentation. Read the source .rst and .py files and
     are checked.
 basepython = {env:TOXPYTHON:python3}
 setenv = {[docsenv]setenv}
-deps = -r req-docs.txt
-; skip_install = true
+deps = -r {env:REQS_FILE:{env:DEFAULT_REQS_FILE:reqs-docs.txt}}
 usedevelop = true
 changedir = {toxinidir}
 commands =
@@ -262,7 +261,7 @@ commands =
 
 ## SERVE LIVE DOCUMENTATION ##
 # export REQS_FILE=reqs-docslive.txt && tox -e pin-deps -- -E docslive && tox -r -e live-html
-[testenv:live-html]
+[testenv:docs-live]
 description = Rebuild Sphinx documentation on changes, with live-reload in the browser.
 basepython = {env:TOXPYTHON:python3}
 setenv = {[docsenv]setenv}