Setup release process and README improvement

.github/workflows/ci.yaml

@@ -27,7 +27,9 @@ jobs:
         uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python }}
-      - name: Install development dependencies
-        run: pip install -r dev-requirements.txt
+      - name: Install poetry
+        run: |
+          pipx install --pip-args=--constraint=./dev-constraints.txt poetry
+          poetry --version
       - name: Build python library
         run: poetry build

.github/workflows/publish.yaml

@@ -1,4 +1,4 @@
-# This workflow will build the python distribution and it will publish to Pypi
+# This workflow will build the python distribution, and it will publish to Pypi
 # This is going to be triggered on on every tag `v*`, e.g., `v0.13`.
 # TODO: trigger tests once implemented, to ensure everything is working before publishing
 name: Publish Horreum library
@@ -7,11 +7,14 @@ on:
   push:
     tags:
       - v*
+  workflow_dispatch:
 
 jobs:
-  test:
+  publish:
     name: ${{ matrix.session }} ${{ matrix.python }}
     runs-on: ubuntu-latest
+    permissions:
+      id-token: write  # IMPORTANT: this permission is mandatory for trusted publishing
     env:
       FORCE_COLOR: "1"
     steps:
@@ -21,8 +24,10 @@ jobs:
         uses: actions/setup-python@v5
         with:
           python-version: "3.10"
-      - name: Install development dependencies
-        run: pip install -r dev-requirements.txt
+      - name: Install poetry
+        run: |
+          pipx install --pip-args=--constraint=./dev-constraints.txt poetry
+          poetry --version
       - name: Check version coherence
         run: |
           PROJECT_VERSION=$(poetry version | cut -d' ' -f2)

.github/workflows/generate-client.yaml → .github/workflows/update-client.yaml

@@ -2,7 +2,7 @@
 # that it will re-generate the Horreum raw client and creates a new pull request against the corresponding branch here.
 # It could be tested running `gh act workflow_dispatch -e ./test/workflow_dispatch_event_example.json`. Remember to
 # comment out the pull request creation :)
-name: Autogenerate Horreum client
+name: Update Horreum auto-generated client
 
 on:
   workflow_dispatch:
@@ -32,12 +32,6 @@ jobs:
       - uses: actions/checkout@v4
         with:
           persist-credentials: false
-      - uses: actions/setup-python@v5
-        with:
-          python-version: '3.10'
-          cache: 'pip'
-      - name: Install development dependencies
-        run: pip install -r dev-requirements.txt
       - name: Generate horreum client
         run: make HORREUM_BRANCH=${{ steps.fetch-branch.outputs.HORREUM_BRANCH }} generate
       - run: git --no-pager diff

Makefile

@@ -36,9 +36,13 @@ help: ## Display this help.
 
 ##@ Development
 
+.PHONY: clean-bin
+clean-bin: ## Clean external tools
+	@rm -rf ${PROJECT_BIN}
+
 .PHONY: clean
 clean: ## Clean external tools and output dirs
-	@rm -rf ${PROJECT_BIN} ${PROJECT_DIST} ${GENERATED_CLIENT_PATH}/api ${GENERATED_CLIENT_PATH}/models ${GENERATED_CLIENT_PATH}/horreum_raw_client.py ${GENERATED_CLIENT_PATH}/kiota-lock.json
+	@rm -rf ${PROJECT_DIST} ${GENERATED_CLIENT_PATH}/api ${GENERATED_CLIENT_PATH}/models ${GENERATED_CLIENT_PATH}/horreum_raw_client.py ${GENERATED_CLIENT_PATH}/kiota-lock.json
 
 .PHONY: kiota
 kiota: ${PROJECT_BIN}/kiota ## Install kiota tool under ${PROJECT_PATH}/bin

README.md

@@ -18,7 +18,7 @@ Horreum python client is a high-level python library to interact with [Horreum](
 The raw client is generated using [kiota](https://github.com/microsoft/kiota) openapi generator tool starting from 
 the [Horreum OpenAPI spec](https://github.com/Hyperfoil/Horreum/blob/master/docs/site/content/en/openapi/openapi.yaml).
 
-Refer to the [get started guide](./GET_STARTED.md) for comprehensive instructions on installing and utilizing this library.
+Refer to the [get started guide](docs/GET_STARTED.md) for comprehensive instructions on installing and utilizing this library.
 
 ## What is Horreum?
 
@@ -44,7 +44,7 @@ Contributions to `horreum-client-python` Please check our [CONTRIBUTING.md](./CO
 
 Install all dev dependencies (consider using Python virtual environments):
 ```bash
-pip install -r dev-requirements.txt
+pip install -r dev-constraints.txt
 ```
 
 Generate source files

docs/GET_STARTED.md

@@ -0,0 +1,82 @@
+<div align="center">
+
+# Get Started Guide
+
+</div>
+
+In this document you can find all information to get started using the Horreum python library from scratch.
+
+Right now the library is not published anywhere, therefore the only way to install it is from source.
+
+---
+## Prerequisites
+
+* Python environment, e.g., `pyenv` or `miniconda` with all development dependencies installed:
+```bash
+pip install -r dev-constraints.txt
+```
+
+## Installation
+
+Once all dependencies are installed simply build the `whl` by running:
+
+```bash
+poetry build
+```
+
+Now you can install the local build of `horreum` python client:
+
+```bash
+pip install dist/horreum-*.dev0-py3-none-any.whl --force-reinstall
+```
+
+## Usage
+
+Horreum Python library leverages the auto-generated client using [Kiota](https://github.com/microsoft/kiota) tool to translate all REST requests
+into python methods calls.
+
+Right now Horreum library does not expose any specific high-level api, but it simply offers the Kiota generated client 
+which is made available through the `HorreumClient.raw_client` property.
+
+Check [Kiota python examples](https://github.com/microsoft/kiota-samples/tree/main/get-started/quickstart/python) to see
+how to interact with a Kiota auto-generated Python client.
+
+Here a very simple example:
+
+```bash
+>>> import asyncio
+
+# Import the constructor function
+>>> from horreum.horreum_client import new_horreum_client
+
+# Initialize the client
+>>> client = await new_horreum_client(base_url="http://localhost:8080", username="..", password="..")
+
+# Call the api using the underlying raw client, in this case retrieve the Horreum server version
+>>> await client.raw_client.api.config.version.get()
+VersionInfo(additional_data={}, privacy_statement=None, start_timestamp=1710864862253, version='0.13.0')
+```
+
+The previous api call is equivalent to the following `cURL`:
+```bash
+curl --silent -X 'GET' 'http://localhost:8080/api/config/version' -H 'accept: application/json' | jq '.'
+```
+
+Other examples can be found in the [test folder](../test), for instance:
+
+```bash
+# Import Horreum Test model
+>>> from horreum.raw_client.models.test import Test
+>>> from horreum.raw_client.models.protected_type_access import ProtectedType_access
+
+# Initialize the client
+>>> client = await new_horreum_client(base_url="http://localhost:8080", username="..", password="..")
+
+# Create new Horreum test
+>>> t = Test(name="TestName", description="Simple test", owner="dev-team", access=ProtectedType_access.PUBLIC)
+>>> created = await client.raw_client.api.test.post(t)
+Test(additional_data={}, access=<ProtectedType_access.PUBLIC: 'PUBLIC'>, owner='dev-team', compare_url=None, datastore_id=1, description='Simple test', fingerprint_filter=None, fingerprint_labels=None, folder=None, id=12, name='TestName', notifications_enabled=True, timeline_function=None, timeline_labels=None, tokens=None, transformers=None)
+
+# Delete the Horreum test
+>>> await client.raw_client.api.test.by_id(12).delete()
+```

docs/RELEASE.md

@@ -0,0 +1,79 @@
+# Release
+
+This document aims to describe how to perform a release of the Horreum python library.
+
+The versioning pattern should follow the [Horreum](https://github.com/Hyperfoil/Horreum) 
+versioning scheme to keep coherence among all Horreum-related projects versions.
+
+## Procedure
+
+### Tag a new version
+
+Checkout to your branch, either a `stable` (e.g., `0.12.x`) or the `main` one.
+
+```bash
+git checkout origin/main
+```
+
+Update the project version:
+
+```bash
+poetry version patch
+```
+
+This will bump your version, from `0.12-dev` to `0.12`.
+
+To double-check the version, run:
+```bash
+poetry version                                                                                                                                                      [15:55:39]
+# horreum 0.12
+```
+
+Commit the changes and tag a new version:
+```bash
+git add .
+git commit -m "Tag version 0.12"
+git tag v0.12
+```
+
+Ensure the tag is in the form of `v$(poetry version)`.
+
+Push changes and tag:
+```bash
+git push origin main
+git push origin v0.12
+```
+
+If you are releasing a new patch from a _stable_ branch all previous operations must be performed
+from _stable_ rather than from `main`.
+
+### Create stable branch
+
+> **NOTE**: If the _stable_ branch is already existing simply skip this step at all as this means 
+> you already did the following steps.
+
+To create a _stable_ branch from the `main` one, e.g., `0.12.x`, run the following commands.
+
+```bash
+git checkout origin/main
+git checkout -b 0.12.x
+git checkout origin/main
+```
+
+Update version to the next development one:
+```bash
+poetry version 0.13-dev
+```
+
+Commit the changes:
+```bash
+git add .
+git commit -m "Next is 0.13"
+```
+
+Push changes:
+```bash
+git push origin 0.12.x
+git push origin main
+```
+

pyproject.toml

@@ -2,13 +2,19 @@
 name = "horreum"
 version = "0.13-dev"
 description = "Horreum python library"
+keywords = ["horreum", "performance", "change-detection"]
 authors = ["Andrea Lamparelli <[email protected]>"]
+maintainers = ["Andrea Lamparelli <[email protected]>"]
 license = "Apache 2.0"
 readme = "README.md"
+homepage = "https://github.com/Hyperfoil/horreum-client-python"
 include = [
-    "src/horreum/raw_client/**/*", # all files in "src/horreum/raw_client" and any subfolders
+    "src/horreum/raw_client/**/*", # this folder includes auto-generated client
 ]
 
+[tool.poetry.urls]
+"Issues" = "https://github.com/Hyperfoil/horreum-client-python/issues"
+
 [tool.poetry.dependencies]
 python = "^3.10"
 microsoft-kiota-abstractions = "^1.3.1"