Merge pull request #862 from freakboy3742/template-versioning

Fixes #824 - Use briefcase version rather than Python version for template versioning

.github/workflows/ci.yml

@@ -13,8 +13,9 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 10
     steps:
-      - uses: actions/checkout@v3.0.2
+      - uses: actions/checkout@v3
         with:
+          fetch-depth: 0
           ref: ${{ github.event.pull_request.head.sha }}
       - name: Set up Python
         uses: actions/[email protected]
@@ -51,26 +52,28 @@ jobs:
       run: |
         pip install --upgrade pip
         pip install --upgrade setuptools
-        pip install tox
+        pip install setuptools_scm tox
     - name: Run pre-test check
       run: |
         tox -e ${{ matrix.task }}
 
   smoke:
-    name: Smoke test (3.7)
+    name: Smoke test
     needs: beefore
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v3
-    - name: Set up Python 3.7
+      with:
+        fetch-depth: 0
+    - name: Set up Python
       uses: actions/[email protected]
       with:
-        python-version: "3.7"
+        python-version: ${{ env.python_version }}
     - name: Install dependencies
       run: |
         pip install --upgrade pip
         pip install --upgrade setuptools
-        pip install tox
+        pip install setuptools_scm tox
     - name: Test
       run: |
         tox -e py
@@ -92,9 +95,11 @@ jobs:
     strategy:
       max-parallel: 4
       matrix:
-        python-version: ['3.8', '3.9', '3.10', '3.11.0-alpha - 3.11.0']
+        python-version: ['3.8', '3.10', '3.11.0-alpha - 3.11.0']
     steps:
     - uses: actions/checkout@v3
+      with:
+        fetch-depth: 0
     - name: Set up Python ${{ matrix.python-version }}
       uses: actions/[email protected]
       with:
@@ -103,7 +108,7 @@ jobs:
       run: |
         pip install --upgrade pip
         pip install --upgrade setuptools
-        pip install tox
+        pip install setuptools_scm tox
     - name: Test
       run: |
         tox -e py
@@ -125,6 +130,8 @@ jobs:
     runs-on: ${{ matrix.platform }}
     steps:
     - uses: actions/checkout@v3
+      with:
+        fetch-depth: 0
     - name: Set up Python
       uses: actions/[email protected]
       with:
@@ -133,7 +140,7 @@ jobs:
       run: |
         pip install --upgrade pip
         pip install --upgrade setuptools
-        pip install tox
+        pip install setuptools_scm tox
     - name: Test
       run: |
         tox -e py
@@ -183,6 +190,8 @@ jobs:
           ${{ matrix.pip-cache-dir }}
           ${{ matrix.docker-cache-dir }}
     - uses: actions/checkout@v3
+      with:
+        fetch-depth: 0
     - name: Set up Python
       uses: actions/[email protected]
       with:
@@ -195,6 +204,7 @@ jobs:
       run: |
         pip install --upgrade pip
         pip install --upgrade setuptools
+        pip install setuptools_scm
         pip install .
     - name: Create App
       run: |

changes/824.feature.rst

@@ -0,0 +1 @@
+Briefcase templates are now versioned by the Briefcase version, rather than the Python version.

docs/conf.py

@@ -10,9 +10,10 @@
 # serve to show the default.
 
 import os
-import re
 import sys
 
+from importlib.metadata import version as metadata_version
+
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
@@ -48,17 +49,7 @@
 # built documents.
 #
 # The full version, including alpha/beta/rc tags.
-with open("../src/briefcase/__init__.py", encoding="utf8") as version_file:
-    version_match = re.search(
-        r"^__version__ = ['\"]([^'\"]*)['\"]", version_file.read(), re.M
-    )
-    if version_match:
-        release = version_match.group(1)
-    else:
-        raise RuntimeError("Unable to find version string.")
-
-# The short X.Y version.
-version = ".".join(release.split(".")[:2])
+version = metadata_version("briefcase")
 
 autoclass_content = "both"
 

docs/how-to/internal/release.rst

@@ -21,61 +21,59 @@ The procedure for cutting a new release is as follows:
 
    Check that the HEAD of release now matches upstream/main.
 
-2. Make sure the branch is ready for release. Ensure that:
-
-   1. The version number has been bumped.
-
-   2. The release notes are up to date. If they are, the `changes
-      <https://github.com/beeware/briefcase/tree/main/changes>`__ directory
-      should be empty, except for the ``template.rst`` file.
-
-   These two changes (the version bump and release notes update) should go
-   through the normal pull request and review process. They should generally
-   comprise the last PR merged before the release occurs.
-
-   If the version number *hasn't* been updated, or ``changes`` directory
-   *isn't* empty, you need to create a PR (using the normal development
-   process) that contains these changes. Run::
+2. Ensure that the release notes are up to date. Run::
 
          $ tox -e towncrier -- --draft
 
    to review the release notes that will be included, and then::
 
          $ tox -e towncrier
 
-   to generate the updated release notes. Submit the PR; once it's been
-   reviewed and merged, you can restart the release process from step 1.
+   to generate the updated release notes.
+
+3. Ensure that there is a version branch for the new Briefcase version
+   every template that Briefcase will use at runtime:
+
+   * briefcase-template
+   * briefcase-macOS-app-template
+   * briefcase-macOS-Xcode-template
+   * briefcase-windows-app-template
+   * briefcase-windows-VisualStudio-template
+   * briefcase-linux-appimage-template
+   * briefcase-linux-flatpak-template
+   * briefcase-iOS-Xcode-template
+   * briefcase-android-gradle-template
 
-3. Tag the release, and push the branch and tag upstream::
+4. Tag the release, and push the branch and tag upstream::
 
     $ git tag v1.2.3
     $ git push upstream main
     $ git push upstream v1.2.3
 
-4. Pushing the tag will start a workflow to create a draft release on GitHub.
+5. Pushing the tag will start a workflow to create a draft release on GitHub.
    You can `follow the progress of the workflow on GitHub
    <https://github.com/beeware/briefcase/actions?query=workflow%3A%22Create+Release%22>`__;
    once the workflow completes, there should be a new `draft release
    <https://github.com/beeware/briefcase/releases>`__.
 
-5. Log into ReadTheDocs, visit the `Versions tab
+6. Log into ReadTheDocs, visit the `Versions tab
    <https://readthedocs.org/projects/briefcase/versions/>`__, and activate the
    new version. Ensure that the build completes; if there's a problem, you
    may need to correct the build configuration, roll back and re-tag the release.
 
-6. Edit the GitHub release. Add release notes (you can use the text generated
+7. Edit the GitHub release. Add release notes (you can use the text generated
    by towncrier). Check the pre-release checkbox (if necessary).
 
-7. Double check everything, then click Publish. This will trigger a
+8. Double check everything, then click Publish. This will trigger a
    `publication workflow on GitHub
    <https://github.com/beeware/briefcase/actions?query=workflow%3A%22Upload+Python+Package%22>`__.
 
-8. Wait for the `package to appear on PyPI
+9. Wait for the `package to appear on PyPI
 <https://pypi.org/project/briefcase/>`__.
 
 Congratulations, you've just published a release!
 
-If anything went wrong during steps 3 or 5, you will need to delete the draft
+If anything went wrong during steps 4-6, you will need to delete the draft
 release from GitHub, and push an updated tag. Once the release has successfully
 appeared on PyPI, it cannot be changed; if you spot a problem in a published
 package, you'll need to tag a completely new release.

docs/reference/commands/new.rst

@@ -21,7 +21,8 @@ The following options can be provided at the command line.
 ---------------------------------------------
 
 A local directory path or URL to use as a cookiecutter template for the new
-project.
-
-If a URL is provided, the ``master`` branch of the referenced repository will
-be used.
+project. Briefcase will attempt to use a template branch matching the version
+of Briefcase that is being used (i.e., if you're using Briefcase 0.3.9,
+Briefcase will use the `v0.3.9` template branch when generating the app).
+If you're using a development version of Briefcase, Briefcase will use the
+`main` branch of the template.

docs/reference/configuration.rst

@@ -332,15 +332,12 @@ package for the platform.
 ~~~~~~~~~~~~~~~~~~~~
 
 The specific revision of a support package that should be used. By default,
-Briefcase will always use the most recently released support package; if you
-specify a support revision, the support package will be pinned to that version
-for your app.
+Briefcase will use the support package revision nominated by the application
+template. If you specify a support revision, that will override the revision
+nominated by the application template.
 
-If the support package is a URL, a query argument of
-``revision=<support_revision>`` will be added to the support package URL when
-it is downloaded.
-
-If the support package is a file path, this argument is ignored.
+If you specify an explicit support package (either as a URL or a file path),
+this argument is ignored.
 
 ``supported``
 ~~~~~~~~~~~~~
@@ -368,8 +365,10 @@ the output format and Python version.
 
 The branch of the project template to use when generating the app. If the
 template is a local file, this attribute will be ignored. If not specified,
-Briefcase will use a branch matching the Python version in use (i.e., the `3.8`
-branch will be used when Python 3.8 is used to generate the app).
+Briefcase will use a branch matching the version of Briefcase that is being used
+(i.e., if you're using Briefcase 0.3.9, Briefcase will use the `v0.3.9` template
+branch when generating the app). If you're using a development version of
+Briefcase, Briefcase will use the `main` branch of the template.
 
 ``url``
 ~~~~~~~

pyproject.toml

@@ -1,10 +1,29 @@
+[build-system]
+requires = ["setuptools>=60", "setuptools_scm[toml]>=7.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.isort]
+profile = "black"
+skip_glob = [
+    "docs/conf.py",
+    "venv*",
+    "local",
+]
+multi_line_output = 3
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+# need to ensure build directories aren't excluded from recursion
+norecursedirs = []
+
+[tool.setuptools_scm]
+# To enable SCM versioning, we need an empty tool configuration for setuptools_scm
+
 [tool.towncrier]
 directory = "changes"
 package = "briefcase"
 package_dir = "src"
 filename = "docs/background/releases.rst"
 title_format = "{version} ({project_date})"
 template = "changes/template.rst"
-
-[tool.isort]
-profile = "black"

requirements.dev.txt

@@ -1,2 +1,3 @@
+setuptools_scm[toml]>=7.0
 pre-commit
 tox

setup.cfg

@@ -1,6 +1,5 @@
 [metadata]
 name = briefcase
-version = attr: briefcase.__version__
 url = http://beeware.org/briefcase
 project_urls =
     Funding = https://beeware.org/contributing/membership/
@@ -17,10 +16,10 @@ classifiers =
     License :: OSI Approved :: BSD License
     Operating System :: OS Independent
     Programming Language :: Python :: 3
-    Programming Language :: Python :: 3.7
     Programming Language :: Python :: 3.8
     Programming Language :: Python :: 3.9
     Programming Language :: Python :: 3.10
+    Programming Language :: Python :: 3.11
     Programming Language :: Python :: 3 :: Only
     Topic :: Software Development
     Topic :: Utilities
@@ -47,7 +46,7 @@ platforms = any
 [options]
 zip_safe = False
 packages = find:
-python_requires = >= 3.7
+python_requires = >= 3.8
 include_package_data = True
 package_dir =
     = src
@@ -64,6 +63,7 @@ install_requires =
     psutil >= 5.9.0
     rich >= 12.4.1
     platformdirs >= 2.5.2
+    packaging >= 21.3
 
 [options.packages.find]
 where = src
@@ -111,9 +111,6 @@ briefcase.formats.windows =
 [aliases]
 test=pytest
 
-[bdist_wheel]
-universal=1
-
 [flake8]
 # https://flake8.readthedocs.org/en/latest/
 exclude=\
@@ -127,16 +124,3 @@ exclude=\
 max-complexity = 10
 max-line-length = 119
 ignore = E121,E123,E126,E226,E24,E704,W503,W504,C901
-
-[isort]
-skip_glob =
-    docs/conf.py
-    venv*
-    local
-multi_line_output=3
-
-[tool:pytest]
-testpaths = tests
-
-# need to ensure build directories aren't excluded from recursion
-norecursedirs =

src/briefcase/__init__.py

@@ -2,12 +2,17 @@
     "__version__",
 ]
 
-# Examples of valid version strings
-# __version__ = '1.2.3.dev1'  Development release 1
-# __version__ = '1.2.3a1'     Alpha Release 1
-# __version__ = '1.2.3b1'     Beta Release 1
-# __version__ = '1.2.3rc1'    RC Release 1
-# __version__ = '1.2.3'       Final Release
-# __version__ = '1.2.3.post1' Post Release 1
+try:
+    # Read version from SCM metadata
+    # This will only exist in a development environment
+    from setuptools_scm import get_version
 
-__version__ = "0.3.9"
+    __version__ = get_version("../..", relative_to=__file__)
+except (ModuleNotFoundError, LookupError):
+    # If setuptools_scm isn't in the environment, the call to import will fail.
+    # If it *is* in the environment, but the code isn't a git checkout (e.g.,
+    # it's been pip installed non-editable) the call to get_version() will fail.
+    # If either of these occurs, read version from the installer metadata.
+    from importlib.metadata import version
+
+    __version__ = version("briefcase")