Merge branch 'master' into deploy-informations

.github/CONTRIBUTING.md

@@ -1,33 +1,122 @@
+# Contribution Guidelines
+
 Feel free to contribute to MyBot.
-There is mainly three ways to contribute :
- 1.  Source code contributions
- 2.  Translations contributions
- 3.  Financial contributions
+There is mainly three ways to contribute:
+
+1.  Source code contributions
+2.  Translations contributions
+3.  Financial contributions
 
 ## Source code contributions
 
-If you have any suggestion for the bot, and you think you have the ability to do it yourself, start by contacting me through Discord!
-It would be a pleasure to count you from the Mybot's contibutors!
+If you have any suggestions for the bot and you think you have the ability to do it yourself, consider contacting me through [Discord](https://discord.gg/GRsAy4aUgu)!
+It would be a pleasure to count you to the Mybot's contributors!
 Then, fork this project, make the changes you want, and open a Pull Request on `master`.
-Before open a Pull Request, you can start by running `tox`. This will ensure your code respect the style, etc...
+
+## Good practices and requirements
+
+### Dependencies
+
+The project is using [pip-tools](https://github.com/jazzband/pip-tools) to manage its dependencies. The requirements are declared in [requirements.in](/requirements.in) and developers requirements are in [requirements.dev.in](/requirements.dev.in).
+
+Install the dependencies using `pip-sync` or simply `pip install -r requirements.txt`, as well as the developer dependencies with `pip install -r requirements.dev.txt`.
+
+If you add or change dependencies, edit the corresponding `.in` file, then use `pip-compile` (`pip-compile requirements.dev.in` for developer deps).
+
+### Lint, formatting...
+
+The project use [pyright](https://github.com/microsoft/pyright) for static type checking and [ruff](https://github.com/astral-sh/ruff) for general formatting, import sorting, security scans and static code analyses.
+
+Please use these tool to avoid Github Actions failure. [tox](https://github.com/tox-dev/tox) can be used to run every checks before committing by running `tox`.
+
+## Docker watch
+
+The [compose file](/compose.yml) implements [watch](https://docs.docker.com/compose/file-watch/) to help debugging the code. By running `docker compose watch`, the bot will be executed while observing for files changes or deps updates. This will allow extensions reload, and speed up restarts (it avoids rebuilds).
+
+## Run the code on debug version
+
+You can use [debugpy](https://github.com/microsoft/debugpy) easily when running MyBot locally, for dev and debug purposes.  
+Replace `docker compose` with `docker compose -f compose.yml -f compose.debug.yml` when using Docker Compose. You can then use debugpy with the port `5678`.
+
+Additionally, this will setup `config.DEBUG` to `True` from the code perspective, which will also set the logger level to `DEBUG`, and expose the PostgresSQL port to the host (`5432`).
+
+### VSCode debug config
+
+As an example, here is a json configuration that can be added inside your local `.vscode/launch.py` to use the integrated debugger:
+```json
+{
+    "name": "debug",
+    "type": "debugpy",
+    "request": "attach",
+    "connect": {
+        "host": "localhost",
+        "port": 5678
+    },
+    "pathMappings": [
+        {
+            "localRoot": "${workspaceFolder}/src",
+            "remoteRoot": "/app"
+        }
+    ]
+}
+```
+
+After you run the code in debug mode, click on the "play" icon inside VSCode to attach the debug console. You can then use breakpoints, etc.  
+To make the restart button actually restart the bot and not just re-attach the debugger, you can add pre&post tasks:
+```json
+    ...
+    "preLaunchTask": "bot up",
+    "postDebugTask": "bot restart",
+```
+And in `.vscode/tasks.json`, add the tasks:
+```json
+{
+    "label": "bot up",
+    "type": "shell",
+    "presentation": {
+        "reveal": "silent"
+    },
+    "command": "docker compose -f compose.yml -f compose.debug.yml up -d",
+},
+{
+    "label": "bot restart",
+    "type": "shell",
+    "presentation": {
+        "reveal": "silent"
+    },
+    "command": "docker-compose restart mybot"
+}
+```
+
+If the bot is executed with the up task, you should then use the `watch` command with `--no-up`.
+More information here: https://code.visualstudio.com/docs/python/debugging
+
+## Database revisions
+
+The project use [alembic](https://github.com/sqlalchemy/alembic) to manage database revisions.  
+When the bot is started using Docker, `alembic upgrade head` is [automatically executed](https://github.com/mybot-organization/mybot/blob/cleanup/Dockerfile#L30).
+To create revisions, you can use [`alembic.sh`](bin/alembic.sh) in the `bin` directory. This script allow you to use the alembic CLI inside the container, and will mount the [`/alembic`](/alembic/) directory.
+
+If you are unfamiliar with alembic, [`here is some information`](/alembic/README). Check also the [documentation](https://alembic.sqlalchemy.org/en/latest/tutorial.html#create-a-migration-script) as well.
 
 ## Translations contributions
 
-MyBot is a multi-language bot! The codebase is in english, which is then translated in several languages.
+MyBot is a multi-language bot! The codebase is in English, which is then translated in several languages.
 
 Currently, MyBot is translated in :
-  -  French
+
+- French
 
 If you know one of these languages, you can contribute to translations here:
 https://crowdin.com/project/mybot-discord
 
-If you are able to add a new language to the bot, please contact me on Discord! It would be a pleasure to add a new language to MyBot!
+If you want to add a new language to the bot, please contact me on Discord! It would be a pleasure to add a new language to MyBot!
 However, this language must also be available on the Discord application.
 
-## Financial contributions 
+## Financial contributions
 
-You can make voluntary donation at https://www.buymeacoffee.com/airopi
+You can make voluntary donations at https://www.buymeacoffee.com/airopi
 
-----
+---
 
 Thanks !

.github/workflows/ci.yml

@@ -9,8 +9,8 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 60
     steps:
-      - uses: actions/checkout@v3
-      - uses: actions/setup-python@v4
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
         with:
           python-version: 3.11.0
           cache: pip
@@ -25,4 +25,4 @@ jobs:
       #   uses: actions/upload-artifact@v3
       #   with:
       #     name: pytest_results
-      #     path: junit/test-results.xml  
+      #     path: junit/test-results.xml

.github/workflows/codeql-analysis.yml

@@ -6,7 +6,7 @@ on:
   pull_request:
     branches: [master]
   schedule:
-    - cron: '30 1 * * 0'
+    - cron: "30 1 * * 0"
 
 jobs:
   codeql_build:
@@ -16,24 +16,24 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        language: [ 'python' ]
+        language: ["python"]
 
     permissions:
       security-events: write
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       # Initializes the CodeQL tools for scanning.
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@v2
+        uses: github/codeql-action/init@v3
         with:
           languages: ${{ matrix.language }}
 
       # This should not be needed
       - name: Autobuild
-        uses: github/codeql-action/autobuild@v2
+        uses: github/codeql-action/autobuild@v3
 
       - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@v2
+        uses: github/codeql-action/analyze@v3

.github/workflows/crowdin-download.yml

@@ -11,7 +11,7 @@ jobs:
     # secrets cannot be accessed inside an `if` so this needs to be checked in separate job
     name: dowload
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
         with:
           fetch-depth: 0
           ref: master
@@ -29,14 +29,14 @@ jobs:
         env:
           CROWDIN_API_KEY: ${{ secrets.CROWDIN_API_KEY }}
 
-      - uses: tibdex/github-app-token@v1
+      - uses: tibdex/github-app-token@v2
         id: generate-token
         with:
           app_id: ${{ secrets.APP_ID }}
           private_key: ${{ secrets.APP_PRIVATE_KEY }}
 
       - name: Create Pull Request
-        uses: peter-evans/create-pull-request@v5
+        uses: peter-evans/create-pull-request@v6
         with:
           token: ${{ steps.generate-token.outputs.token }}
           commit-message: "PO files added."

.github/workflows/crowdin-upload.yml

@@ -12,7 +12,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
         with:
           ref: master
 
@@ -22,7 +22,7 @@ jobs:
           echo "deb https://artifacts.crowdin.com/repo/deb/ /" | sudo tee -a /etc/apt/sources.list.d/crowdin.list
           sudo apt-get update && sudo apt-get install crowdin3
 
-      - uses: actions/setup-python@v4
+      - uses: actions/setup-python@v5
         with:
           python-version: "3.11"
           cache: pip

.github/workflows/docker-publish.yml

@@ -14,7 +14,7 @@ jobs:
         os: [ubuntu-latest]
     steps:
       - name: Check out the repo
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Log in to Docker Hub
         uses: docker/login-action@v2

Dockerfile

@@ -11,11 +11,13 @@ RUN --mount=type=cache,target=/var/cache/apk/ \
     --mount=type=bind,source=./bin/msgfmt.py,target=./msgfmt.py \
     : \
     && apk add gcc musl-dev linux-headers \
+    && pip install -U pip \
     && pip install -U -r requirements.txt \
     && python ./msgfmt.py ./locale/**/LC_MESSAGES/*.po \
     && :
 
 FROM python:3.12.0-alpine as base
+# https://docs.docker.com/reference/dockerfile/#copy---parents
 COPY --parents --from=build /opt/venv /app/locale/**/LC_MESSAGES/*.mo /
 WORKDIR /app
 COPY ./src ./
@@ -24,7 +26,7 @@ ENV PATH="/opt/venv/bin:$PATH"
 ENV PYTHONUNBUFFERED=0
 
 
-FROM base as prod
+FROM base as production
 CMD ["/bin/sh", "-c", "alembic upgrade head && python ./main.py bot --sync -c ./config.toml"]
 
 

bin/pot-generation.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 pybabel extract \
-    --msgid-bugs-address="[email protected]" \
+    --msgid-bugs-address="[email protected]" \
     --project="MyBot" \
     --version="1.0" \
     -k "_ __" \

compose.debug.yml

@@ -0,0 +1,13 @@
+version: '3.4'
+
+services:
+  mybot:
+    build:
+      target: debug
+    restart: "no"
+    ports:
+      - 5678:5678  # for debugpy; see .github/CONTRIBUTING/md
+
+  database:
+    ports:
+      - 5432:5432  # publish database port to the host

docker-compose.yml → compose.yml

@@ -4,14 +4,15 @@ services:
   mybot:
     image: airopi/mybot:stable
     build:
-      context: .
       dockerfile: ./Dockerfile
-      target: prod
+      target: production
     develop:
       watch:
         - action: sync
           path: ./src
           target: /app
+        - action: rebuild
+          path: ./requirements.txt
     env_file:
       - .env
     tty: true