Merge pull request #851 from paperless-ngx/feature-semver-tags

Feature: Use semver for release process

.github/release-drafter.yml

@@ -30,7 +30,6 @@ replacers: # Changes "Feature: Update checker" to "Update checker"
     replace: ''
 change-template: '- $TITLE @$AUTHOR (#$NUMBER)'
 change-title-escapes: '\<*_&#@'
-tag-prefix: "ngx-"
 template: |
   # Changelog
 

.github/workflows/ci.yml

@@ -3,8 +3,10 @@ name: ci
 on:
   push:
     tags:
-      - ngx-*
+      # https://semver.org/#spec-item-2
-      - beta-*
+      - 'v[0-9]+.[0-9]+.[0-9]+'
+      # https://semver.org/#spec-item-9
+      - 'v[0-9]+.[0-9]+.[0-9]+-beta.rc[0-9]+'
     branches-ignore:
       - 'translations**'
   pull_request:
@@ -53,7 +55,7 @@ jobs:
 
   prepare-docker-build:
     name: Prepare Docker Pipeline Data
-    if: github.event_name == 'push' && (startsWith(github.ref, 'refs/heads/feature-') || github.ref == 'refs/heads/dev' || github.ref == 'refs/heads/beta' || startsWith(github.ref, 'refs/tags/ngx-') || startsWith(github.ref, 'refs/tags/beta-'))
+    if: github.event_name == 'push' && (startsWith(github.ref, 'refs/heads/feature-') || github.ref == 'refs/heads/dev' || github.ref == 'refs/heads/beta' || contains(github.ref, 'beta.rc') || startsWith(github.ref, 'refs/tags/v'))
     runs-on: ubuntu-20.04
     needs:
       - documentation
@@ -197,8 +199,12 @@ jobs:
             ghcr.io/${{ github.repository }}
             name=paperlessngx/paperless-ngx,enable=${{ steps.docker-hub.outputs.enable }}
           tags: |
+            # Tag branches with branch name
             type=ref,event=branch
-            type=ref,event=tag
+            # Process semver tags
+            # For a tag x.y.z or vX.Y.Z, output an x.y.z and x.y image tag
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
       -
         name: Checkout
         uses: actions/checkout@v3
@@ -334,7 +340,7 @@ jobs:
     runs-on: ubuntu-20.04
     needs:
       - build-release
-    if: github.ref_type == 'tag' && (startsWith(github.ref_name, 'ngx-') || startsWith(github.ref_name, 'beta-'))
+    if: github.ref_type == 'tag' && (startsWith(github.ref_name, 'v') || contains(github.ref_name, '-beta.rc'))
     steps:
       -
         name: Download release artifact
@@ -346,12 +352,11 @@ jobs:
         name: Get version
         id: get_version
         run: |
-          if [[ $GITHUB_REF == refs/tags/ngx-* ]]; then
+          echo ::set-output name=version::${{ github.ref_name }}
-            echo ::set-output name=version::${GITHUB_REF#refs/tags/ngx-}
+          if [[ ${{ contains(github.ref_name, '-beta.rc') }} == 'true' ]]; then
-            echo ::set-output name=prerelease::false
-          elif [[ $GITHUB_REF == refs/tags/beta-* ]]; then
-            echo ::set-output name=version::${GITHUB_REF#refs/tags/beta-}
             echo ::set-output name=prerelease::true
+          else
+            echo ::set-output name=prerelease::false
           fi
       -
         name: Create Release and Changelog
@@ -359,7 +364,7 @@ jobs:
         uses: release-drafter/release-drafter@v5
         with:
           name: Paperless-ngx ${{ steps.get_version.outputs.version }}
-          tag: ngx-${{ steps.get_version.outputs.version }}
+          tag: ${{ steps.get_version.outputs.version }}
           version: ${{ steps.get_version.outputs.version }}
           prerelease: ${{ steps.get_version.outputs.prerelease }}
           publish: true # ensures release is not marked as draft

docs/administration.rst

@@ -117,6 +117,23 @@ Then you can start paperless-ngx with ``-d`` to have it run in the background.
 
                 image: ghcr.io/paperless-ngx/paperless-ngx:latest
 
+    .. note::
+        In version 1.7.1 and onwards, the Docker image can now pinned to a release series.
+        This is often combined with automatic updaters such as Watchtower to allow safer
+        unattended upgrading to new bugfix releases only.  It is still recommended to always
+        review release notes before upgrading.  To ping your install to a release series, edit
+        the ``docker-compose.yml`` find the line that says
+
+            .. code::
+
+                image: ghcr.io/paperless-ngx/paperless-ngx:latest
+
+        and replace the version with the series you want to track, for example:
+
+            .. code::
+
+                image: ghcr.io/paperless-ngx/paperless-ngx:1.7
+
 Bare Metal Route
 ================
 

docs/conf.py

@@ -2,6 +2,8 @@ import sphinx_rtd_theme
 
 
 __version__ = None
+__full_version_str__ = None
+__major_minor_version_str__ = None
 exec(open("../src/paperless/version.py").read())
 
 
@@ -41,9 +43,9 @@ copyright = "2015-2022, Daniel Quinn, Jonas Winkler, and the paperless-ngx team"
 #
 
 # The short X.Y version.
-version = ".".join([str(_) for _ in __version__[:2]])
+version = __major_minor_version_str__
 # The full version, including alpha/beta/rc tags.
-release = ".".join([str(_) for _ in __version__[:3]])
+release = __full_version_str__
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

src/documents/views.py

@@ -676,28 +676,33 @@ class RemoteVersionView(GenericAPIView):
     def get(self, request, format=None):
         remote_version = "0.0.0"
         is_greater_than_current = False
+        current_version = packaging_version.parse(version.__full_version_str__)
         # TODO: this can likely be removed when frontend settings are saved to DB
         feature_is_set = settings.ENABLE_UPDATE_CHECK != "default"
         if feature_is_set and settings.ENABLE_UPDATE_CHECK:
             try:
-                with urllib.request.urlopen(
+                req = urllib.request.Request(
-                    "https://api.github.com/repos/"
+                    "https://api.github.com/repos/paperless-ngx/"
-                    + "paperless-ngx/paperless-ngx/releases/latest",
+                    "paperless-ngx/releases/latest",
-                ) as response:
+                )
+                # Ensure a JSON response
+                req.add_header("Accept", "application/json")
+
+                with urllib.request.urlopen(req) as response:
                     remote = response.read().decode("utf-8")
                 try:
                     remote_json = json.loads(remote)
-                    remote_version = remote_json["tag_name"].replace("ngx-", "")
+                    remote_version = remote_json["tag_name"].removeprefix("ngx-")
                 except ValueError:
-                    logger.debug("An error occured parsing remote version json")
+                    logger.debug("An error occurred parsing remote version json")
             except urllib.error.URLError:
-                logger.debug("An error occured checking for available updates")
+                logger.debug("An error occurred checking for available updates")
 
-            current_version = ".".join([str(_) for _ in version.__version__[:3]])
+            is_greater_than_current = (
-            is_greater_than_current = packaging_version.parse(
+                packaging_version.parse(
-                remote_version,
+                    remote_version,
-            ) > packaging_version.parse(
+                )
-                current_version,
+                > current_version
             )
 
         return Response(

src/paperless/middleware.py

@@ -11,6 +11,6 @@ class ApiVersionMiddleware:
         if request.user.is_authenticated:
             versions = settings.REST_FRAMEWORK["ALLOWED_VERSIONS"]
             response["X-Api-Version"] = versions[len(versions) - 1]
-            response["X-Version"] = ".".join([str(_) for _ in version.__version__])
+            response["X-Version"] = version.__full_version_str__
 
         return response

src/paperless/version.py

@@ -1 +1,8 @@
-__version__ = (1, 7, 0)
+from typing import Final
+from typing import Tuple
+
+__version__: Final[Tuple[int, int, int]] = (1, 7, 0)
+# Version string like X.Y.Z
+__full_version_str__: Final[str] = ".".join(map(str, __version__))
+# Version string like X.Y
+__major_minor_version_str__: Final[str] = ".".join(map(str, __version__[:-1]))