chore(deps): bump from template

Author: helmut-hoffer-von-ankershoffen

.copier-answers.yml

@@ -1,22 +1,26 @@
-_commit: v0.6.21
+_commit: v0.7.3
 _src_path: gh:helmut-hoffer-von-ankershoffen/oe-python-template
+attestations_enabled: true
 author_email: helmuthva@googlemail.com
 author_github_username: helmut-hoffer-von-ankershoffen
 author_name: Helmut Hoffer von Ankershoffen
+codeql_enabled: true
 docker_io_enabled: true
 docker_io_image_name: starbridge
 docker_io_owner: helmuthva
 github_repository_name: starbridge
 github_repository_owner: helmut-hoffer-von-ankershoffen
 github_repository_url_https: https://github.com/helmut-hoffer-von-ankershoffen/starbridge
 github_repository_url_ssh: git@github.com:helmut-hoffer-von-ankershoffen/starbridge.git
+import_package_name: starbridge
 org_email: helmuthva@googlemail.com
 org_name: Helmut Hoffer von Ankershoffen
 project_description: Integrates Claude Desktop with the web, Google and Atlassian
     workspaces.
 project_icon: ⭐
 project_name: Starbridge
 pypi_distribution_name: starbridge
+pypi_enabled: true
 readthedocs_domain: readthedocs.org
 readthedocs_project_key: starbridge
 sonarqube_key: helmut-hoffer-von-ankershoffen_starbridge

.github/workflows/codeql.yml

@@ -59,7 +59,7 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v4
 
-      # Add any setup steps before running the `github/codeql-action/init` action.
+        # Add any setup steps before running the `github/codeql-action/init` action.
       # This includes steps like installing compilers or runtimes (`actions/setup-node`
       # or others). This is typically only required for manual builds.
       # - name: Setup runtime (example)

.github/workflows/docker-image-build-publish.yml

@@ -85,6 +85,7 @@ jobs:
 
 
 
+
       - name: Generate artifact attestation
         uses: actions/attest-build-provenance@c074443f1aee8d4aeeae555aebba3282517141b2 # v2.2.3
         with:

.github/workflows/package-build-publish-release.yml

@@ -32,21 +32,22 @@ jobs:
       - name: Print the release notes
         run: cat "${{ steps.git-cliff.outputs.changelog }}"
 
-
       - name: Install uv
         uses: astral-sh/setup-uv@f94ec6bedd8674c4426838e6b50417d36b6ab231 # v5.3.1
         with:
           version: "0.6.3"
           cache-dependency-glob: uv.lock
           enable-cache: true
 
-      - name: Build package into dist/
+      - name: Build distribution into dist/
         run: uv build
 
-      - name: Publish package to PyPI
+
+      - name: Publish distribution to Python Package Index at pypi.org
         run: uv publish -t ${{ secrets.UV_PUBLISH_TOKEN }}
 
-      - name: Build package into dist/
+
+      - name: Have audit checks publish to reports/ for auditing
         run: uv run nox -s audit
 
       - name: Create GitHub release

.vscode/extensions.json

@@ -17,6 +17,7 @@
         "ms-python.python",
         "ms-python.vscode-pylance",
         "ms-toolsai.jupyter",
+        "ms-vscode.makefile-tools",
         "oderwat.indent-rainbow",
         "samuelcolvin.jinjahtml",
         "sonarsource.sonarlint-vscode",

CODE_STYLE.md

@@ -4,40 +4,22 @@ Thank you for considering contributing to Starbridge!
 
 ## Setup
 
-Clone this GitHub repository via
-`git clone git@github.com:helmut-hoffer-von-ankershoffen/starbridge.git` and
-change into the directory of your local Starbridge repository: `cd starbridge`
-
-Install the dependencies:
-
-### macOS
+Install or update tools required for development:
 
 ```shell
-if ! command -v brew &> /dev/null; then # if Homebrew package manager not present ...
-  /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" # ... install it
-else
-  which brew # ... otherwise inform where brew command was found
-fi
-# Install required tools if not present
-which jq &> /dev/null || brew install jq
-which xmllint &> /dev/null || brew install xmllint
-which act &> /dev/null || brew install act
-which pinact &> /dev/null || brew install pinact
-uv run pre-commit install             # install pre-commit hooks, see https://pre-commit.com/
+# Install Homebrew, uv package manager, copier and further dev tools
+curl -LsSf https://raw.githubusercontent.com/helmut-hoffer-von-ankershoffen/oe-python-template/HEAD/install.sh | sh
 ```
 
-### Linux
-
-Notes:
-
-- Not yet validated
-- .github/workflows/test.yml might provide further information
+[Create a fork](https://github.com/helmut-hoffer-von-ankershoffen/starbridge/fork)
+and clone your fork using `git clone URL_OF_YOUR_CLONE`. Then change into the
+directory of your local Starbridge repository with `cd starbridge`.
 
-```shell
-sudo sudo apt install -y curl jq libxml2-utils gnupg2  # tooling
-curl --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash # act
-uv run pre-commit install # see https://pre-commit.com/
-```
+If you are one of the committers of
+https://github.com/helmut-hoffer-von-ankershoffen/starbridge you can directly
+clone via
+`git clone git@github.com:helmut-hoffer-von-ankershoffen/starbridge.git` and
+`cd starbridge`.
 
 ## Configuration
 
@@ -92,74 +74,191 @@ Desktop application.
 To show the configuration of starbridge within Claude, you can use
 `uv run starbridge claude config`.
 
-## Running all build steps
+## Directory Layout
 
-All build steps are defined in `noxfile.py`.
+```
+├── Makefile               # Central entrypoint for build, test, release and deploy
+├── noxfile.py             # Noxfile for running tests in multiple python environments and other tasks
+├── .pre-commit-config.yaml # Definition of hooks run on commits
+├── .github/               # GitHub specific files
+│   ├── workflows/         # GitHub Actions workflows
+│   ├── prompts/           # Custom prompots for GitHub Copilot
+│   └── copilot-instructions.md # Insructions for GitHub Copilot
+├── .vscode/               # Recommended VSCode settings and extensions
+├── .env                   # Environment variables, on .gitignore
+├── .env.example           # Example environment variables
+src/starbridge/            # Source code
+tests/                   # Unit and E2E tests
+docs/                    # Documentation
+├── partials/*.md        # Partials to compile README.md,  _main partial included in HTML and PDF documentation
+├── ../README.md         # Compiled README.md shown on GitHub
+├── source/*.rst         # reStructuredText files used to generate HTML and PDF documentation
+├── ../*.md              # Markdown files shown on GitHub and imported by .rst files
+├── source/conf.py       # Sphinx configuration used to generate HTML and PDF documentation
+├── build/html/*         # Generated HTML documentation as multiple pages
+├── build/singlehtml/index.html # HTML documentation as a single page
+└── build/latex/starbridge.pdf # PDF manual - generate with make docs pdf
+reports/                 # Compliance reports for auditing
+├── junit.xml            # Report of executions
+├── mypy_junit.xml       # Report of executions
+├── coverage.xml         # Test coverage in XML format
+├── coverage_html        # Report of test coverage in HTML format
+├── licenses.csv         # List of dependencies and their license types
+├── licenses.json        # .json file with dependencies their license types
+└── licenses_grouped.json  # .json file with dependencies grouped by license type
+```
+
+## Build, Run and Release
+
+### Setup project specific development environment
 
 ```shell
-uv run nox        # Runs all build steps except setup_dev
+make setup
 ```
 
-You can run individual build steps - called sessions in nox as follows:
+Don't forget to configure your `.env` file with the required environment
+variables.
+
+Notes:
+
+1. .env.example is provided as a template, use `cp .env.example .env` and edit
+   `.env` to create your environment.
+2. .env is excluded from version control, so feel free to add secret values.
+
+### Build
 
 ```shell
-uv run nox -s test      # run tests
-uv run nox -s lint      # run formatting and linting
-uv run nox -s audit     # run security and license audit, inc. sbom generation
-uv run nox -s docs      # build documentation, output in docs/build/html
-uv run nox -s docs_pdf  # locally build pdf manual to docs/build/latex/starbridge.pdf
+make        # Runs primary build steps, i.e. formatting, linting, testing, building HTML docs and distribution, auditing
+make help   # Shows help with additional build targets, e.g. to build PDF documentation, bump the version to release etc.
 ```
 
-As a shortcut, you can run build steps using `./n`, e.g.
+Notes:
+
+1. Primary build steps defined in `noxfile.py`.
+2. Distribution dumped into `dist/`
+3. Documentation dumped into `docs/build/html/` and `docs/build/latex/`
+4. Audit reports dumped into `reports/`
+
+### Run the CLI
 
 ```shell
-./n test
-./n lint
-# ...
+uv run starbridge # shows help
 ```
 
-Generate a wheel using uv
+### Commit and Push your changes
 
 ```shell
-uv build
+git add .
+git commit -m "feat(user): added new api endpoint to offboard user"
+git push
 ```
 
 Notes:
 
-1. Reports dumped into `reports/`
-2. Documentation dumped into `docs/build/html/`
-3. Distribution dumped into `dist/`
+1. [pre-commit hooks](https://pre-commit.com/) will run automatically on commit
+   to ensure code quality.
+2. We use the conventional commits format - see the
+   [code style guide](CODE_STYLE.md) for the mandatory commit message format.
 
-### Running GitHub CI workflow locally
+### Publish Release
 
 ```shell
-uv run nox -s act
+make bump   # Patch release
+make minor  # Patch release
+make major  # Patch release
+make x.y.z  # Targeted release
 ```
 
 Notes:
 
-- Workflow defined in `.github/workflows/*.yml`
-- test-and-report.yml calls all build steps defined in noxfile.py
+1. Changelog generated automatically
+2. Publishes to PyPi, Docker Registries, Read The Docs, Streamlit and Auditing
+   services
+
+## Advanced usage
+
+### Running GitHub CI Workflow locally
+
+```shell
+make act
+```
+
+Notes:
+
+1. Workflow defined in `.github/workflows/*.yml`
+2. test-and-report.yml calls all build steps defined in noxfile.py
+
+### Docker
+
+Build and run the Docker image with plain Docker
+
+```shell
+# Build from Dockerimage
+make docker build
+# Run the CLI
+docker run --env THE_VAR=THE_VALUE starbridge --help
+```
+
+Build and run the Docker image with docker compose:
+
+```shell
+echo "Building the Docker image with docker compose and running CLI..."
+docker compose run --build oe-python-template --help
+echo "Building the Docker image with docker compose and running API container as a daemon ..."
+docker compose up --build -d
+echo "Waiting for the API server to start..."
+sleep 5
+echo "Checking health of v1 API ..."
+curl http://127.0.0.1:8000/api/v1/healthz
+echo ""
+echo "Saying hello world with v1 API ..."
+curl http://127.0.0.1:8000/api/v1/hello-world
+echo ""
+echo "Swagger docs of v1 API ..."
+curl http://127.0.0.1:8000/api/v1/docs
+echo ""
+echo "Checking health of v2 API ..."
+curl http://127.0.0.1:8000/api/v2/healthz
+echo ""
+echo "Saying hello world with v1 API ..."
+curl http://127.0.0.1:8000/api/v2/hello-world
+echo ""
+echo "Swagger docs of v2 API ..."
+curl http://127.0.0.1:8000/api/v2/docs
+echo ""
+echo "Shutting down the API container ..."
+docker compose down
+```
+
+### Pinning GitHub Actions
+
+```shell
+pinact run  # See https://dev.to/suzukishunsuke/pin-github-actions-to-a-full-length-commit-sha-for-security-2n7p
+```
 
-### Copier
+## Update from Template
 
-Update from template
+Update project to latest version of
+[oe-python-template](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template)
+template.
 
 ```shell
-uv run nox -s update_from_template
+make update_from_template
 ```
 
 ## Pull Request Guidelines
 
-- Before starting to write code read the [code style guide](CODE_STYLE.md)
-  document for mandatory coding style guidelines.
-- **Pre-Commit Hooks:** We use pre-commit hooks to ensure code quality. Please
-  install the pre-commit hooks by running `uv run pre-commit install`. This
-  ensure all tests, linting etc. pass locally before you can commit.
-- **Squash Commits:** Before submitting a pull request, please squash your
-  commits into a single commit.
-- **Branch Naming:** Use descriptive branch names like `feature/your-feature` or
-  `fix/issue-number`.
-- **Testing:** Ensure new features have appropriate test coverage.
-- **Documentation:** Update documentation to reflect any changes or new
-  features.
+1. Before starting to write code read the [code style](CODE_STYLE.md) document
+   for mandatory coding style requirements.
+2. **Pre-Commit Hooks:** We use pre-commit hooks to ensure code quality. Please
+   install the pre-commit hooks by running `uv run pre-commit install`. This
+   ensure all tests, linting etc. pass locally before you can commit.
+3. **Squash Commits:** Before submitting a pull request, please squash your
+   commits into a single commit.
+4. **Signed Commits:** Use
+   [signed commits](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits).
+5. **Branch Naming:** Use descriptive branch names like `feature/your-feature`
+   or `fix/issue-number`.
+6. **Testing:** Ensure new features have appropriate test coverage.
+7. **Documentation:** Update documentation to reflect any changes or new
+   features.