Pull version from VCS to simplify release and build dynamic docs via mkdocs plugin (#1130)

Co-authored-by: Jason Lam <[email protected]>

Author: gaborbernat

.github/workflows/tests.yml

@@ -1,6 +1,7 @@
 name: tests
 
 on:
+  workflow_dispatch:
   push:
   pull_request:
   schedule:
@@ -41,12 +42,26 @@ jobs:
       - name: Install nox
         run: python -m pip install nox
       - name: Execute Tests
-        run: nox --non-interactive --session tests-${{ matrix.python-version }}
+        run: nox --error-on-missing-interpreters --non-interactive --session tests-${{ matrix.python-version }}
+  man:
+    name: Build man page
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ env.default-python }}
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ env.default-python }}
+          cache: "pip"
+      - name: Install nox
+        run: python -m pip install nox
+      - name: Build man page
+        run: nox --error-on-missing-interpreters --non-interactive --session build_man
+      - name: Show man page
+        run: man -l pipx.1
 
-  pypi-publish:
-    name: Publish pipx to PyPI on release
-    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags')
-    needs: [tests]
+  zipapp:
+    name: Build zipapp
     runs-on: ubuntu-latest
     steps:
       - name: Checkout ${{ github.ref }}
@@ -58,19 +73,26 @@ jobs:
           cache: "pip"
       - name: Install nox
         run: pip install nox
-      - name: Build  sdist and wheel
-        run: nox --error-on-missing-interpreters --non-interactive --session build
-      - name: Publish to PyPi
-        uses: pypa/[email protected]
+      - name: Build zipapp
+        run: nox --error-on-missing-interpreters --non-interactive --session zipapp
+      - name: Test zipapp by installing black
+        run: python ./pipx.pyz install black
+      - uses: actions/upload-artifact@v3
         with:
-          user: __token__
-          password: ${{ secrets.pypi_password }}
+          name: pipx.pyz
+          path: pipx.pyz
+          retention-days: 3
 
-  build-zipapp:
-    name: Build zipapp
+  pypi-publish:
+    name: Publish pipx to PyPI on release
     if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags')
-    needs: [tests]
+    needs: [tests, man, zipapp]
     runs-on: ubuntu-latest
+    environment:
+      name: release
+      url: https://pypi.org/p/pipx
+    permissions:
+      id-token: write
     steps:
       - name: Checkout ${{ github.ref }}
         uses: actions/checkout@v4
@@ -79,15 +101,44 @@ jobs:
         with:
           python-version: ${{ env.default-python }}
           cache: "pip"
-      - name: Install shiv
-        run: pip install shiv
-      - name: Build zipapp
-        run: shiv -c pipx -o ./pipx.pyz git+https://github.com/pypa/pipx@${{ github.ref_name }}
-      - name: Show zipapp version
-        run: python ./pipx.pyz --version
-      - name: Test zipapp by installing black
-        run: python ./pipx.pyz install black
-      - name: Upload to releases
+      - name: Install nox
+        run: pip install nox
+      - name: Build  sdist and wheel
+        run: nox --error-on-missing-interpreters --non-interactive --session build
+      - name: Publish to PyPi
+        uses: pypa/[email protected]
+
+  upload-zipapp:
+    name: Upload zipapp to GitHub Release on release
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags')
+    needs: [tests, man, zipapp]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/download-artifact@v3
+        with:
+          name: pipx.pyz
+      - name: Upload to release
         uses: softprops/action-gh-release@v1
         with:
           files: pipx.pyz
+
+  bump-changelog:
+    name: Bump changelog on release
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags')
+    needs: [pypi-publish, upload-zipapp]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout ${{ github.ref }}
+        uses: actions/checkout@v4
+      - name: Extract release tag
+        run: echo "RELEASE_VERSION=${GITHUB_REF#refs/*/}" >> $GITHUB_ENV
+      - name: Update changelog
+        run: echo -e "## dev\n\n## $RELEASE_VERSION\n$(tail -n +2 CHANGELOG.md)" > CHANGELOG.md
+      - name: Commit and push change
+        run: |
+          git config --global user.name 'Github Actions'
+          git config --global user.email '[email protected]'
+          git commit -am "Bump changelog for $RELEASE_VERSION"
+          git push

.gitignore

@@ -1,22 +1,17 @@
-/.nox/
-/.coverage
-*egg*
-.mypy_cache
-.vscode
-build
-dist
-activate
-__pypackages__
-venv
-.venv
-.DS_Store
-.tox
+/.*_cache
+/build
+/dist
+/src/pipx/version.py
+/noxfile.py
+/.nox
+*.py[co]
 __pycache__
-site
-docs/docs.md
-pipx.1
-.pipx_tests
+/site
 /.coverage*
-/testdata
-!/testdata/empty_project
-/.idea
+/.pipx_tests
+/testdata/tests_packages/*.txt
+/pipx.pyz
+*.egg-info
+build
+*.whl
+/pipx.1

.pre-commit-config.yaml

@@ -1,9 +1,3 @@
-# See https://pre-commit.com for more information
-# See https://pre-commit.com/#installation for installation instructions
-# See https://pre-commit.com/hooks.html for more hooks
-#
-# use `git commit --no-verify` to disable git hooks for this commit
-
 repos:
 - repo: https://github.com/pre-commit/pre-commit-hooks
   rev: v4.5.0
@@ -22,15 +16,15 @@ repos:
   - id: ruff-format
   - id: ruff
     args: [ "--fix", "--unsafe-fixes", "--exit-non-zero-on-fix"]
-# mypy args:
-#   must include --ignore-missing-imports for mypy.  It is included by default
-#     if no arguments are supplied, but we must supply it ourselves since we
-#     specify args
-#   cannot use --warn-unused-ignores because it conflicts with
-#     --ignore-missing-imports
 - repo: https://github.com/pre-commit/mirrors-mypy
   rev: v1.7.1
   hooks:
   - id: mypy
     args: ['--warn-unused-ignores', '--strict-equality','--no-implicit-optional', '--check-untyped-defs']
     exclude: 'testdata/test_package_specifier/local_extras/setup.py'
+    additional_dependencies:
+    - "mkdocs-gen-files"
+    - "nox"
+    - "packaging>=20"
+    - "platformdirs>=2.1"
+    - "tomli; python_version < '3.11'"

CHANGELOG.md

@@ -1,5 +1,6 @@
 ## dev
 
+- The project version number is now dynamic and generated from the VCS at build time
 - [docs] Add additonal example for --pip-args option, to docs/examples.md
 
 ## 1.3.1

CONTRIBUTING.md

@@ -11,26 +11,6 @@ To run the pipx executable from your source tree during development, run pipx fr
 python src/pipx --version
 ```
 
-## Pre-commit
-
-The use of [pre-commit](https://pre-commit.com/) is recommended. It can show all and fix some lint errors before commit,
-saving you the trouble of finding out later that it failed CI Lint errors, and saving you from having to run
-`nox -s lint` separately.
-
-In the pipx git repository is a `.pre-commit-config.yaml` configuration file tailored just for pipx and its lint
-requirements. To use pre-commit in your clone of the pipx repository, you need to do the following **one-time setup
-procedure**:
-
-1. Install pre-commit using `pipx install pre-commit`
-2. In the top level directory of your clone of the pipx repository, execute `pre-commit install`
-
-Afterwards whenever you commit in this repository, it will first run pipx's personalized lint checks. If it makes a fix
-to a file (e.g. using `black` or `isort`), you will need to `git add` that file again before committing it again. If it
-can't fix your commit itself, it will tell you what's wrong, and you can fix it manually before re-adding the edited
-files and committing again.
-
-If for some reason you want to commit and skip running pre-commit, you can use the switch `git commit --no-verify`.
-
 ## Running Tests
 
 ### Setup
@@ -88,15 +68,18 @@ At the time of this writing, the output looks like this
 * build_docs
 - watch_docs
 * build_man
-- pre_release
-- post_release
 - create_test_package_list-3.12
 - create_test_package_list-3.11
 - create_test_package_list-3.10
 - create_test_package_list-3.9
 - create_test_package_list-3.8
 ```
 
+### Creating a developer environment
+
+For developing the tool (and to attach to your IDE) we recommend creating a Python environment via
+`nox -s develop-3.12`, afterwards use the Python interpreter available under `.nox/develop-3.12/bin/python`.
+
 ### Unit Tests
 
 To run unit tests in Python3.12, you can run
@@ -123,13 +106,13 @@ nox -s tests-3.12
 
 Running the unit tests requires a directory `.pipx_tests/package_cache` to be populated from a fixed list of package
 distribution files (wheels or source files). If you have network access, `nox -s tests` automatically makes sure this
-directory is populated (including downloading files if necessary) as a first step. Thus if you are running the tests
+directory is populated (including downloading files if necessary) as a first step. Thus, if you are running the tests
 with network access, you can ignore the rest of this section.
 
 If, however, you wish to run tests offline without the need for network access, you can populate
 `.pipx_tests/package_cache` yourself manually beforehand when you do have network access.
 
-#### Populating the cache directory using nox
+### Populating the cache directory using nox
 
 To populate `.pipx_tests/package_cache` manually using nox, execute:
 
@@ -140,19 +123,10 @@ nox -s refresh_packages_cache
 This will sequence through available python executable versions to populate the cache directory for each version of
 python on your platform.
 
-#### Populating the cache directory without nox
-
-An alternate method to populate `.pipx_tests/package_cache` without nox is to execute:
-
-```
-mkdir -p .pipx_tests/package_cache
-python3 scripts/update_package_cache.py testdata/tests_packages .pipx_tests/package_cache
-```
-
-You must do this using every python version that you wish to use to run the tests.
-
 ### Lint Tests
 
+Linting is done via `pre-commit`, setting it up and running it can be done via `nox` by typing:
+
 ```
 nox -s lint
 ```
@@ -181,16 +155,13 @@ Finally, check-in the new or modified list files in the directory `testdata/test
 
 ## Testing pipx on Continuous Integration builds
 
-When you push a new git branch, tests will automatically be run against your code as defined in
-`.github/workflows/on-push.yml`.
+Upon opening pull requests GitHub Actions will automatically trigger.
 
 ## Building Documentation
 
 `pipx` autogenerate API documentation, and also uses templates.
 
-When updating pipx docs, make sure you are either modifying a file in the `templates` directory, or the `docs`
-directory. If in the `docs` directory, make sure the file was not autogenerated from the `templates` directory.
-Autogenerated files have a note at the top of the file.
+When updating pipx docs, make sure you are modifying the `docs` directory.
 
 You can generate the documentation with
 
@@ -207,44 +178,12 @@ To preview changes, including live reloading, open another terminal and run
 nox -s watch_docs
 ```
 
-### Publishing Doc Changes to GitHub pages
-
-```
-nox -s publish_docs
-```
-
 ## Releasing New `pipx` Versions
 
-### Pre-release
-
-First, make sure the changelog is complete. Next decide what the next version number will be. Then, from a clone of the
-main pypa pipx repo (not a fork) execute:
-
-```
-nox -s pre_release
-```
-
-Enter the new version number when asked. When the script is finished, check the diff it produces. If the diff looks
-correct, commit the changes as the script instructs, and push the result.
-
-The script will modify `src/pipx/version.py` to contain the new version, and also update the changelog
-(`docs/changelog.md`) to specify the new version.
-
-### Release
-
-To publish to PyPI simply create a "published" release on Github. This will trigger Github workflows that both publish
-the pipx version to PyPI and publish the pipx documentation to the pipx website.
-
-### Post-release
-
-From a clone of the main pypa pipx repo (not a fork) execute:
-
-```
-nox -s post_release
-```
+To publish to PyPI simply create a "published" release on GitHub. This will trigger GitHub workflows that publishes:
 
-When the script is finished, check the diff it produces. If the diff looks correct, commit the changes as the script
-instructs, and push the result.
+- the pipx version to PyPI,
+- the documentation to readthedocs,
+- the `zipapp` to the GitHub release created.
 
-This will update pipx's version in `src/pipx/version.py` by adding a suffix `"dev0"` for unreleased development, and
-will update the changelog to start a new section at the top entitled `dev`.
+No need for any other pre or post publish steps.

mkdocs.yml

@@ -40,3 +40,11 @@ nav:
 
 markdown_extensions:
   - admonition  #  note blocks, warning blocks -- https://github.com/mkdocs/mkdocs/issues/1659
+
+plugins:
+  - search:
+      lang: en
+      enabled: true
+  - gen-files:
+      scripts:
+        - scripts/gen_doc_pages.py