Update the package versioning (#146)

* chore: update pr template

* style: shorten CI description to add them into README badges

* chore: add some more details to the README

* build: make the package versioning single source (git tag)

* ci: use trusted publishers

* refactor: use separate file for versioning

* chore: use package version on docker image

* chore: add --no-cache-dir to save a bit of space in the docker image

* fix: don't lint the _version.py file

.github/PULL_REQUEST_TEMPLATE.md

@@ -5,6 +5,7 @@
 - [ ] Tested the changes locally with a real Telegram bot.
 - [ ] Introduced tests for the changes have been added (for bug fixes / features).
 - [ ] Docs have been added/updated (for bug fixes / features).
+- [ ] I have updated the `CHANGELOG.rst` file with an overview of the changes made.
 
 ### Description
 

.github/workflows/docker.yml

@@ -1,9 +1,9 @@
-name: Create and publish a Docker image
+name: Docker
 
 on:
   push:
-    branches: 
-      - main
+    tags:
+      - "*"
 
 env:
   REGISTRY: ghcr.io
@@ -21,22 +21,24 @@ jobs:
         uses: actions/checkout@v4
 
       - name: Log in to the Container registry
-        uses: docker/login-action@f054a8b539a109f9f41c372932f1ae047eff08c9
+        uses: docker/login-action@v3
         with:
           registry: ${{ env.REGISTRY }}
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Extract metadata (tags, labels) for Docker
         id: meta
-        uses: docker/metadata-action@98669ae865ea3cffbcbaa878cf57c20bbf1c6c38
+        uses: docker/metadata-action@v5
         with:
           images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
 
       - name: Build and push Docker image
-        uses: docker/build-push-action@ad44023a93711e3deb337508980b4b5e9bcdc5dc
+        uses: docker/build-push-action@v5
         with:
           context: .
           push: true
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}
+          build-args: |
+            VERSION=${{ github.ref_name }}

.github/workflows/docs.yml

@@ -1,4 +1,4 @@
-name: "Docs build and deploy"
+name: Docs
 
 on:
   push:

.github/workflows/lint.yml

@@ -1,4 +1,4 @@
-name: "Lint Python code and docs"
+name: Lint
 
 on:
   push:

.github/workflows/publish.yml

@@ -1,36 +1,32 @@
-name: "Publish Python package"
+name: Publish
 
 on:
   push:
     tags:
       - "*"
 
-permissions:
-  contents: read
-
 jobs:
   deploy:
-
     runs-on: ubuntu-latest
+    permissions:
+      id-token: write
 
     steps:
-    - uses: actions/checkout@v4
-    - name: Set up Python
-      uses: actions/setup-python@v4
-      with:
-        python-version: '3.x'
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.x"
+
+      - name: Install dependencies
+        run: |
+          python3 -m pip install --upgrade pip
+          python3 -m pip install build
 
-    - name: Install dependencies
-      run: |
-        python3 -m pip install --upgrade pip
-        python3 -m pip install build
-  
-    - name: Build package
-      run: python3 -m build
+      - name: Build package
+        run: python3 -m build
 
-    - name: Publish package to PyPI
-      uses: pypa/gh-action-pypi-publish@release/v1
-      with:
-        skip-existing: true
-        password: ${{ secrets.TEST_PYPI_API_TOKEN }}
-        repository-url: https://test.pypi.org/legacy/ 
+      - name: Publish package to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true

.github/workflows/test.yml

@@ -1,4 +1,4 @@
-name: "Test Python code"
+name: Test
 
 on:
   push:

.gitignore

@@ -72,6 +72,7 @@ docs/source/api/
 
 # PyBuilder
 target/
+_version.py
 
 # Jupyter Notebook
 .ipynb_checkpoints

Dockerfile

@@ -1,9 +1,12 @@
 FROM python:3-slim
 WORKDIR /app
 
+ARG VERSION="0.0.0"
+ENV SETUPTOOLS_SCM_PRETEND_VERSION_FOR_TELEGRAM_SPOTTED_DMI_BOT=${VERSION}
+
 COPY . .
 #Install the library
-RUN pip3 install .
+RUN pip install --no-cache-dir .
 
 #Start the bot
 ENTRYPOINT [ "python3", "-m", "spotted" ]

README.md

@@ -1,8 +1,12 @@
 # Telegram-SpottedDMI-Bot
 
-[![Test and docs](https://github.com/UNICT-DMI/Telegram-SpottedDMI-Bot/actions/workflows/prod.workflow.yml/badge.svg)](https://github.com/UNICT-DMI/Telegram-SpottedDMI-Bot/actions/workflows/prod.workflow.yml)
+[![Docs](https://github.com/UNICT-DMI/Telegram-SpottedDMI-Bot/actions/workflows/docs.yml/badge.svg)](https://github.com/UNICT-DMI/Telegram-SpottedDMI-Bot/actions/workflows/docs.yml)
+[![Lint](https://github.com/UNICT-DMI/Telegram-SpottedDMI-Bot/actions/workflows/lint.yml/badge.svg)](https://github.com/UNICT-DMI/Telegram-SpottedDMI-Bot/actions/workflows/lint.yml)
+[![Test](https://github.com/UNICT-DMI/Telegram-SpottedDMI-Bot/actions/workflows/test.yml/badge.svg)](https://github.com/UNICT-DMI/Telegram-SpottedDMI-Bot/actions/workflows/test.yml)
 [![Docker image](https://github.com/UNICT-DMI/Telegram-SpottedDMI-Bot/actions/workflows/docker.yml/badge.svg)](https://github.com/UNICT-DMI/Telegram-SpottedDMI-Bot/actions/workflows/docker.yml)
+[![Publish](https://github.com/UNICT-DMI/Telegram-SpottedDMI-Bot/actions/workflows/publish.yml/badge.svg)](https://github.com/UNICT-DMI/Telegram-SpottedDMI-Bot/actions/workflows/publish.yml)
 [![CodeFactor](https://www.codefactor.io/repository/github/unict-dmi/telegram-spotteddmi-bot/badge)](https://www.codefactor.io/repository/github/unict-dmi/telegram-spotteddmi-bot)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 
 **Telegram-SpottedDMI-Bot** is the platform that powers **[@Spotted_DMI_Bot](https://telegram.me/Spotted_DMI_Bot)**, a Telegram bot that let students send an anonymous message to the channel community.
 
@@ -149,20 +153,20 @@ docker build --tag spotted-image .
 Then something like
 
 ```bash
-docker run -d --name botcontainer -e TOKEN=<token_arg> -e POST_CHANNEL_ID=-4 -e POST_GROUP_ID=-5 -e POST_CHANNEL_GROUP_ID=-6 spotted-image
+docker run -d --name spotted-container -e TOKEN=<token_arg> -e POST_CHANNEL_ID=-4 -e POST_GROUP_ID=-5 -e POST_CHANNEL_GROUP_ID=-6 spotted-image
 ```
 
 If you want to check the logs in real time, you can run
 
 ```bash
 # -f flag to follow the logs, otherwise it will just print the last ones
-docker logs -f botcontainer
+docker logs -f spotted-container
 ```
 
 If you want to access the container's shell, you can run
 
 ```bash
-docker exec -it botcontainer /bin/bash
+docker exec -it spotted-container /bin/bash
 ```
 
 #### Mounting a volume
@@ -172,20 +176,32 @@ This will assume the default database path, which is _"./spotted.sqlite3"_.
 
 ```bash
 # The file will survive the container removal, stored in the volume "spotted-db"
-docker run -d --name botcontainer -v spotted-db:/app -e TOKEN=<token_arg> -e POST_CHANNEL_ID=-4 -e POST_GROUP_ID=-5 -e POST_CHANNEL_GROUP_ID=-6 spotted-image
+docker run -d --name spotted-container -v spotted-db:/app -e TOKEN=<token_arg> -e POST_CHANNEL_ID=-4 -e POST_GROUP_ID=-5 -e POST_CHANNEL_GROUP_ID=-6 spotted-image
 ```
 
 If you want to be able to access the database file from the host, you can use a bind mount instead.
 
 ```bash
 # The file will be available in the host under the path "./spotted.sqlite3"
-docker run -d --name botcontainer -v .:/app -e TOKEN=<token_arg> -e POST_CHANNEL_ID=-4 -e POST_GROUP_ID=-5 -e POST_CHANNEL_GROUP_ID=-6 spotted-image
+docker run -d --name spotted-container -v .:/app -e TOKEN=<token_arg> -e POST_CHANNEL_ID=-4 -e POST_GROUP_ID=-5 -e POST_CHANNEL_GROUP_ID=-6 spotted-image
 ```
 
+#### Package version
+
+If you want to change the version displayed by the package inside the container, you can do when building the image:
+
+```bash
+docker build --tag spotted-image --build-arg VERSION=<version> .
+# Example
+docker build --tag spotted-image --build-arg VERSION=3.0.0 .
+```
+
+Keep in mind that this will only change the version displayed by `python3 -m spotted --version`, not the version of the package itself.
+
 ### To stop/remove the container:
 
-- **Run** `docker stop botcontainer` to stop the container
-- **Run** `docker rm -f botcontainer` to remove the container
+- **Run** `docker stop spotted-container` to stop the container
+- **Run** `docker rm -f spotted-container` to remove the container
 
 ## 📦 DevContainer
 
@@ -282,10 +298,15 @@ DEBUG_LOCAL_LOG=4   # will override the *debug.local_log* value found in setting
 The complete order of precedence for the application of configuration settings is
 
 ```
-env var > settings.yaml > settings.yaml.default
+env var > (user provided) settings.yaml > (package provided) settings.yaml
 ```
 
-Since every setting has a default value specified in _settings.yaml.default_ except for **token**, this is the only necessary setting to add when setting up the bot for the first time.
+> [!Note]
+> The bot provides a **/reload** command that will reload the settings without restarting the bot.
+> Keep in mind that the order of precedence will be the same, meaning that the env vars will always override the _settings.yaml_ files.
+
+Since every setting has a default value specified in the default _settings.yaml_ except for **token** and the **chat_id**s of the groups and the channel, those are the only necessary setting to add when setting up the bot for the first time.
+All other values will be assigned a valid default value if not specified.
 
 ### Settings typing
 
@@ -373,15 +394,20 @@ pip3 install -e .[lint]
 
 ### Scripts
 
-The `scripts` folder contains some utility scripts that can be used to simulate the whole CI pipeline locally.
+The `script` folder contains some utility scripts such as [_script/local-ci.sh_](./script/local-ci.sh) that can be used to simulate the whole CI pipeline locally.
 Make sure to have the dev dependencies installed before running them.
 
 Furthermore, the package provides a `run_sql` script that can be used to run an arbitrary sql script on the indicated sqlite3 database.
 
 ```shell
 run_sql <path_to_sql_script> <path_to_db_file>
+# Example
+run_sql ./script/create_db.sql ./spotted.sqlite3
 ```
 
+> [!Important]
+> Make sure to backup your database before running any scripts on it, since all alteration will happen in place, and there is no way to undo them.
+
 ## 📚 Documentation
 
 [Link to the documentation](https://unict-dmi.github.io/Telegram-SpottedDMI-Bot/)

pyproject.toml

@@ -1,5 +1,5 @@
 [build-system]
-requires = ["setuptools>=46.1.0", "setuptools_scm[toml]>=5"]
+requires = ["setuptools>=46.1.0", "setuptools-scm>=8.0"]
 build-backend = "setuptools.build_meta"
 
 # Metadata of the project
@@ -75,8 +75,9 @@ run_sql = "spotted.scripts.run_sql:main"
 include-package-data = true
 package-dir = { "" = "src" }
 
-[tool.setuptools.dynamic]
-version = { attr = "spotted.__version__" }
+# Automatic versioning based on git tags
+[tool.setuptools_scm]
+version_file = "src/spotted/_version.py"
 
 # Pytest configuration (test runner)
 [tool.pytest.ini_options]
@@ -103,7 +104,7 @@ profile = "black"
 
 # Pylint configuration (code linter)
 [tool.pylint.MASTER]
-ignore = ['tests']
+ignore = ['tests', '_version.py']
 fail-under = '10.0'
 
 [tool.pylint.'MESSAGES CONTROL']

src/spotted/__init__.py

@@ -4,8 +4,6 @@
 from spotted.data import Config, init_db
 from spotted.handlers import add_commands, add_handlers, add_jobs
 
-__version__ = "0.0.2"
-
 
 def run_bot():
     """Init the database, add the handlers and start the bot"""

src/spotted/__main__.py

@@ -2,9 +2,14 @@
 import argparse
 from typing import TYPE_CHECKING
 
-from spotted import __version__, run_bot
+from spotted import run_bot
 from spotted.data import Config
 
+try:
+    from spotted._version import __version__
+except ImportError:
+    __version__ = "0.0.0"
+
 if TYPE_CHECKING:
 
     class SpottedArgs(argparse.Namespace):