Prep 1.0.0 Update Docs and Dev Code to 2025 standards (#129)

* upgrade app and docs to 2025 dev standards

* docs clean ups

* fix ci and task files

* relock

* add readthedocs config

* fix readmine

* first pr review updates

* fix towncrier template name

* fix towncrier template name

Author: jeffkala

.bandit.yml

@@ -1,2 +1,2 @@
 # Default owner(s) of all files in this repository
-* @chadell @lvrfrc87 @scetron @pke11y @grelleum @jeffkala @pszulczewski
+* @lvrfrc87 @scetron @grelleum @jeffkala @pszulczewski

.flake8

@@ -4,7 +4,7 @@ about: Report a reproducible bug in the current release of jdiff
 ---
 
 ### Environment
-* Python version:  <!-- Example: 3.7.7 -->
+* Python version:  <!-- Example: 3.11.2 -->
 * jdiff version:  <!-- Example: 1.0.0 -->
 
 <!-- What did you expect to happen? -->

.github/CODEOWNERS

@@ -1,6 +1,9 @@
 ---
 name: "CI"
-on: # yamllint disable-line rule:truthy rule:comments
+concurrency:  # Cancel any existing runs of this workflow for this same PR
+  group: "${{ github.workflow }}-${{ github.ref }}"
+  cancel-in-progress: true
+on:  # yamllint disable-line rule:truthy rule:comments
   push:
     branches:
       - "main"
@@ -9,76 +12,72 @@ on: # yamllint disable-line rule:truthy rule:comments
       - "v*"
   pull_request: ~
 
+env:
+  INVOKE_JDIFF_IMAGE_NAME: "jdiff"
+  INVOKE_JDIFF_IMAGE_VER: "latest"
+
 jobs:
-  black:
-    runs-on: "ubuntu-24.04"
-    env:
-      INVOKE_LOCAL: "True"
-    steps:
-      - name: "Check out repository code"
-        uses: "actions/checkout@v4"
-      - name: "Setup environment"
-        uses: "networktocode/gh-action-setup-poetry-environment@v6"
-        with:
-          poetry-version: "1.8.5"
-      - name: "Linting: black"
-        run: "poetry run invoke black"
-  mypy:
+  ruff-format:
     runs-on: "ubuntu-24.04"
     env:
-      INVOKE_LOCAL: "True"
+      INVOKE_JDIFF_LOCAL: "True"
     steps:
       - name: "Check out repository code"
         uses: "actions/checkout@v4"
       - name: "Setup environment"
         uses: "networktocode/gh-action-setup-poetry-environment@v6"
         with:
           poetry-version: "1.8.5"
-      - name: "Linting: mypy"
-        run: "poetry run invoke mypy"
-  bandit:
+      - name: "Linting: ruff format"
+        run: "poetry run invoke ruff --action format"
+  ruff-lint:
     runs-on: "ubuntu-24.04"
     env:
-      INVOKE_LOCAL: "True"
+      INVOKE_JDIFF_LOCAL: "True"
     steps:
       - name: "Check out repository code"
         uses: "actions/checkout@v4"
       - name: "Setup environment"
         uses: "networktocode/gh-action-setup-poetry-environment@v6"
         with:
           poetry-version: "1.8.5"
-      - name: "Linting: bandit"
-        run: "poetry run invoke bandit"
-  pydocstyle:
+      - name: "Linting: ruff"
+        run: "poetry run invoke ruff --action lint"
+  # Temporarily disabled due to issues with the docs build and needing best practices for NTC python builds.
+  # check-docs-build:
+  #   runs-on: "ubuntu-24.04"
+  #   env:
+  #     INVOKE_JDIFF_LOCAL: "True"
+  #   steps:
+  #     - name: "Check out repository code"
+  #       uses: "actions/checkout@v4"
+  #     - name: "Setup environment"
+  #       uses: "networktocode/gh-action-setup-poetry-environment@v6"
+  #       with:
+  #         poetry-version: "1.8.5"
+  #     - name: "Check Docs Build"
+  #       run: "poetry run invoke build-and-check-docs"
+  poetry:
     runs-on: "ubuntu-24.04"
     env:
-      INVOKE_LOCAL: "True"
+      INVOKE_JDIFF_LOCAL: "True"
     steps:
       - name: "Check out repository code"
         uses: "actions/checkout@v4"
       - name: "Setup environment"
         uses: "networktocode/gh-action-setup-poetry-environment@v6"
         with:
           poetry-version: "1.8.5"
-      - name: "Linting: pydocstyle"
-        run: "poetry run invoke pydocstyle"
-  flake8:
-    runs-on: "ubuntu-24.04"
-    env:
-      INVOKE_LOCAL: "True"
-    steps:
-      - name: "Check out repository code"
-        uses: "actions/checkout@v4"
-      - name: "Setup environment"
-        uses: "networktocode/gh-action-setup-poetry-environment@v6"
-        with:
-          poetry-version: "1.8.5"
-      - name: "Linting: flake8"
-        run: "poetry run invoke flake8"
+      - name: "Checking: poetry lock file"
+        run: "poetry lock --check"
+    needs:
+      - "ruff-format"
+      - "ruff-lint"
+      - "yamllint"
   yamllint:
     runs-on: "ubuntu-24.04"
     env:
-      INVOKE_LOCAL: "True"
+      INVOKE_JDIFF_LOCAL: "True"
     steps:
       - name: "Check out repository code"
         uses: "actions/checkout@v4"
@@ -88,61 +87,106 @@ jobs:
           poetry-version: "1.8.5"
       - name: "Linting: yamllint"
         run: "poetry run invoke yamllint"
-  pylint:
     needs:
-      - "bandit"
-      - "pydocstyle"
-      - "flake8"
-      - "yamllint"
-      - "black"
-      - "mypy"
+      - "ruff-format"
+      - "ruff-lint"
+  pylint:
     runs-on: "ubuntu-24.04"
     strategy:
       fail-fast: true
       matrix:
-        python-version: ["3.8"]
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
     env:
       PYTHON_VER: "${{ matrix.python-version }}"
-      INVOKE_LOCAL: "True"
     steps:
       - name: "Check out repository code"
         uses: "actions/checkout@v4"
       - name: "Setup environment"
         uses: "networktocode/gh-action-setup-poetry-environment@v6"
+      - name: "Get image version"
+        run: "echo INVOKE_JDIFF_IMAGE_VER=`poetry version -s`-py${{ matrix.python-version }} >> $GITHUB_ENV"
+      - name: "Set up Docker Buildx"
+        id: "buildx"
+        uses: "docker/setup-buildx-action@b5ca514318bd6ebac0fb2aedd5d36ec1b5c232a2"  # v3.10.0
+      - name: "Build"
+        uses: "docker/build-push-action@ca052bb54ab0790a636c9b5f226502c73d547a25"  # v5.4.0
         with:
-          poetry-version: "1.8.5"
-          # Default install options is "--only dev", but we need to install all dependencies
-          poetry-install-options: ""
+          builder: "${{ steps.buildx.outputs.name }}"
+          context: "./"
+          push: false
+          load: true
+          tags: "${{ env.INVOKE_JDIFF_IMAGE_NAME }}:${{ env.INVOKE_JDIFF_IMAGE_VER }}"
+          file: "./Dockerfile"
+          cache-from: "type=gha,scope=${{ env.INVOKE_JDIFF_IMAGE_NAME }}-${{ env.INVOKE_JDIFF_IMAGE_VER }}-py${{ matrix.python-version }}"
+          cache-to: "type=gha,scope=${{ env.INVOKE_JDIFF_IMAGE_NAME }}-${{ env.INVOKE_JDIFF_IMAGE_VER }}-py${{ matrix.python-version }}"
+          build-args: |
+            PYTHON_VER=${{ env.PYTHON_VER }}
+      - name: "Debug: Show docker images"
+        run: "docker image ls"
       - name: "Linting: Pylint"
         run: "poetry run invoke pylint"
-  pytest:
     needs:
-      - "pylint"
+      - "poetry"
+  pytest:
     strategy:
       fail-fast: true
       matrix:
-        python-version: ["3.8", "3.9", "3.10", "3.11"]
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
     runs-on: "ubuntu-24.04"
     env:
       PYTHON_VER: "${{ matrix.python-version }}"
-      INVOKE_LOCAL: "True"
     steps:
       - name: "Check out repository code"
         uses: "actions/checkout@v4"
       - name: "Setup environment"
         uses: "networktocode/gh-action-setup-poetry-environment@v6"
+      - name: "Get image version"
+        run: "echo INVOKE_JDIFF_IMAGE_VER=`poetry version -s`-py${{ matrix.python-version }} >> $GITHUB_ENV"
+      - name: "Set up Docker Buildx"
+        id: "buildx"
+        uses: "docker/setup-buildx-action@b5ca514318bd6ebac0fb2aedd5d36ec1b5c232a2"  # v3.10.0
+      - name: "Build"
+        uses: "docker/build-push-action@ca052bb54ab0790a636c9b5f226502c73d547a25"  # v5.4.0
         with:
-          poetry-version: "1.8.5"
-          # Default install options is "--only dev", but we need to install all dependencies
-          poetry-install-options: ""
+          builder: "${{ steps.buildx.outputs.name }}"
+          context: "./"
+          push: false
+          load: true
+          tags: "${{ env.INVOKE_JDIFF_IMAGE_NAME }}:${{ env.INVOKE_JDIFF_IMAGE_VER }}"
+          file: "./Dockerfile"
+          cache-from: "type=gha,scope=${{ env.INVOKE_JDIFF_IMAGE_NAME }}-${{ env.INVOKE_JDIFF_IMAGE_VER }}-py${{ matrix.python-version }}"
+          cache-to: "type=gha,scope=${{ env.INVOKE_JDIFF_IMAGE_NAME }}-${{ env.INVOKE_JDIFF_IMAGE_VER }}-py${{ matrix.python-version }}"
+          build-args: |
+            PYTHON_VER=${{ env.PYTHON_VER }}
+      - name: "Debug: Show docker images"
+        run: "docker image ls"
       - name: "Run Tests"
         run: "poetry run invoke pytest"
-  publish_gh:
     needs:
-      - "pytest"
+      - "poetry"
+  changelog:
+    if: >
+      contains(fromJson('["develop"]'), github.base_ref) &&
+      (github.head_ref != 'main') && (!startsWith(github.head_ref, 'release'))
+    runs-on: "ubuntu-22.04"
+    steps:
+      - name: "Check out repository code"
+        uses: "actions/checkout@v4"
+        with:
+          fetch-depth: "0"
+      - name: "Setup environment"
+        uses: "networktocode/gh-action-setup-poetry-environment@v6"
+        with:
+          poetry-version: "1.8.5"
+      - name: "Check for changelog entry"
+        run: |
+          git fetch --no-tags origin +refs/heads/${{ github.base_ref }}:refs/remotes/origin/${{ github.base_ref }}
+          poetry run towncrier check --compare-with origin/${{ github.base_ref }}
+  publish_gh:
     name: "Publish to GitHub"
     runs-on: "ubuntu-24.04"
-    if: "startsWith(github.ref, 'refs/tags/v')"
+    # yamllint disable-line rule:quoted-strings
+    if: startsWith(github.ref, 'refs/tags/v')
     steps:
       - name: "Check out repository code"
         uses: "actions/checkout@v4"
@@ -156,22 +200,21 @@ jobs:
         run: "echo RELEASE_VERSION=${GITHUB_REF:10} >> $GITHUB_ENV"
       - name: "Run Poetry Version"
         run: "poetry version $RELEASE_VERSION"
+      - name: "Build Documentation"
+        run: "poetry run invoke build-and-check-docs"
       - name: "Run Poetry Build"
         run: "poetry build"
       - name: "Upload binaries to release"
-        uses: "svenstaro/upload-release-action@v2"
-        with:
-          repo_token: "${{ secrets.NTC_GITHUB_TOKEN }}"
-          file: "dist/*"
-          tag: "${{ github.ref }}"
-          overwrite: true
-          file_glob: true
-  publish_pypi:
+        run: "gh release upload ${{ github.ref_name }} dist/*.{tar.gz,whl}"
+        env:
+          GH_TOKEN: "${{ secrets.NTC_GITHUB_TOKEN }}"
     needs:
       - "pytest"
+  publish_pypi:
     name: "Push Package to PyPI"
     runs-on: "ubuntu-24.04"
-    if: "startsWith(github.ref, 'refs/tags/v')"
+    # yamllint disable-line rule:quoted-strings
+    if: startsWith(github.ref, 'refs/tags/v')
     steps:
       - name: "Check out repository code"
         uses: "actions/checkout@v4"
@@ -188,15 +231,16 @@ jobs:
       - name: "Run Poetry Build"
         run: "poetry build"
       - name: "Push to PyPI"
-        uses: "pypa/gh-action-pypi-publish@release/v1"
+        uses: "pypa/gh-action-pypi-publish@76f52bc884231f62b9a034ebfe128415bbaabdfc"  # v1.12.4
         with:
           user: "__token__"
           password: "${{ secrets.PYPI_API_TOKEN }}"
+    needs:
+      - "pytest"
   slack-notify:
     needs:
       - "publish_gh"
       - "publish_pypi"
-    name: "Send notification to the Slack"
     runs-on: "ubuntu-24.04"
     env:
       SLACK_WEBHOOK_URL: "${{ secrets.SLACK_WEBHOOK_URL }}"
@@ -209,8 +253,8 @@ jobs:
       - name: "Send a notification to Slack"
         # ENVs cannot be used directly in job.if. This is a workaround to check
         # if SLACK_WEBHOOK_URL is present.
-        if: "${{ env.SLACK_WEBHOOK_URL != '' }}"
-        uses: "slackapi/slack-github-action@v1.17.0"
+        if: "env.SLACK_WEBHOOK_URL != ''"
+        uses: "slackapi/slack-github-action@fcfb566f8b0aab22203f066d80ca1d7e4b5d05b3"  # v1.27.1
         with:
           payload: |
             {

.github/ISSUE_TEMPLATE/bug_report.md

@@ -297,6 +297,12 @@ fabric.properties
 
 # Rando
 creds.env
+development/*.txt
 
 # Invoke overrides
 invoke.yml
+
+# Docs
+docs/README.md
+docs/CHANGELOG.md
+public

.github/workflows/ci.yml

@@ -0,0 +1,24 @@
+---
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python in the build environment.
+build:
+  os: "ubuntu-22.04"
+  tools:
+    python: "3.10"
+
+mkdocs:
+  configuration: "mkdocs.yml"
+  # fail_on_warning: true
+
+# Use our docs/requirements.txt during installation.
+python:
+  install:
+    - requirements: "docs/requirements.txt"
+    - method: "pip"
+      path: "."

.gitignore

@@ -1,10 +1,13 @@
 ---
 extends: "default"
 rules:
-  comments: "enable"
+  comments:
+    min-spaces-from-content: 1
   empty-values: "enable"
   indentation:
     indent-sequences: "consistent"
   line-length: "disable"
   quoted-strings:
     quote-type: "double"
+ignore: |
+  .venv/