Adjust release workflow

* Update the ci-cd workflow 
* Add documentation for release workflow
* Remove publish environment
* Refactor documentation builds & updates
* Update changelog
* Bump version number

Co-authored-by: Muhammet Orazov <[email protected]>

.github/workflows/ci-cd.yml

@@ -72,10 +72,10 @@ jobs:
 
       - name: GitHub Release
         env:
-          GITHUB_TOKEN: ${{ secrets.GH_RELEASE_TOKEN }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: >
-          gh release create ${{ github.rev_name }}
-          --title ${{ github.rev_name }}
-          --notes-file doc/changes/changes_${{ github.rev_name }}.md
+          gh release create ${GITHUB_REF_NAME}
+          --title ${GITHUB_REF_NAME}
+          --notes-file doc/changes/changes_${GITHUB_REF_NAME}.md
           dist/*
               

.github/workflows/ci.yml

@@ -4,6 +4,7 @@ on:
   push:
     branches-ignore:
       - "github-pages/*"
+      - "main"
   pull_request:
     branches-ignore:
       - 'main'
@@ -13,8 +14,3 @@ jobs:
   ci-job:
     name: Checks
     uses: ./.github/workflows/checks.yml
-
-  publish-docs:
-    name: Publish Documentation
-    if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
-    uses: ./.github/workflows/docs.yml

.github/workflows/docs.yml

@@ -6,7 +6,6 @@ jobs:
 
   documenation-job:
     runs-on: ubuntu-latest
-    environment: publish
 
     steps:
       - name: SCM Checkout

.github/workflows/pr_merge.yml

@@ -0,0 +1,16 @@
+name: Update Docs
+
+on:
+  push:
+    branches:
+      - 'main'
+
+jobs:
+
+  ci-job:
+    name: Checks
+    uses: ./.github/workflows/checks.yml
+
+  publish-docs:
+    name: Publish Documentation
+    uses: ./.github/workflows/docs.yml

doc/changes/changelog.md

@@ -1,5 +1,6 @@
 # Changes
 
+* [0.5.0](changes_0.5.0.md)
 * [0.4.0](changes_0.4.0.md)
 * [0.3.0](changes_0.3.0.md)
 * [0.2.0](changes_0.2.0.md)
@@ -10,6 +11,7 @@
 ---
 hidden:
 ---
+changes_0.5.0
 changes_0.4.0
 changes_0.3.0
 changes_0.2.0

doc/changes/changes_0.5.0.md

@@ -0,0 +1,14 @@
+# BucketFs Python 0.5.0, released YYYY-MM-DD
+
+## Summary
+TDB
+
+## Features / Enhancements
+
+## Bug Fixes
+
+## Refactoring
+- Rework 
+
+## Documentation
+- Add information on how to trigger a release

doc/developer_guide/developer_guide.rst

@@ -7,4 +7,5 @@ In this developer guide we explain how you can build this project.
 .. toctree::
    :maxdepth: 1
 
+   releases
    building_documentation

doc/developer_guide/releases.rst

@@ -0,0 +1,66 @@
+Creating a Release
+*******************
+
+Prerequisites
+-------------
+
+* Change log needs to be up to date
+* Latest change log version needs to match project and package version
+* Release tag needs to match package, changelog and project version
+
+  For Example:
+        * Tag: 0.4.0
+        * Changelog: changes_0.4.0.md
+        * \`poetry version -s\`: 0.4.0
+
+Triggering the Release
+----------------------
+In order to trigger a release a new tag must be pushed to Github.
+For further details see: `.github/workflows/ci-cd.yml`.
+
+
+#. Create a local tag with the appropriate version number
+
+    .. code-block:: shell
+
+        git tag x.y.z
+
+#. Push the tag to Github
+
+    .. code-block:: shell
+
+        git tag push origin x.y.z
+
+What to do if the release failed?
+---------------------------------
+
+The release failed during pre-release checks
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+#. Delete the local tag
+
+    .. code-block:: shell
+
+        git tag -d x.y.z
+
+#. Delete the remote tag
+
+    .. code-block:: shell
+
+        git push --delete origin x.y.z
+
+#. Fix the issue(s) which lead to the failing checks
+#. Start the release process from the beginning
+
+
+One of the release steps failed (Partial Release)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#. Check the Github action/workflow to see which steps failed
+#. Finish or redo the failed release steps manually
+
+.. note:: Example
+
+    **Scenario**: Publishing of the release on Github was successfull but during the PyPi release, the upload step got interrupted.
+
+    **Solution**: Manually push the package to PyPi
+

exasol_bucketfs_utils_python/version.py

@@ -3,7 +3,7 @@
 # If you need to change the version, do so in the project.toml, e.g. by using `poetry version X.Y.Z`.
 
 MAJOR = 0
-MINOR = 4
+MINOR = 5
 PATCH = 0
 
 VERSION = f"{MAJOR}.{MINOR}.{PATCH}"

pyproject.toml

@@ -3,7 +3,7 @@ name = "exasol-bucketfs"
 packages  = [
     {include = "exasol_bucketfs_utils_python"}
 ]
-version = "0.4.0"
+version = "0.5.0"
 description = "BucketFS utilities for the Python programming language"
 
 license = "MIT"