|
| 1 | +# Contributing to PythonScriptRunner |
| 2 | + |
| 3 | +Thanks for helping! The [ScriptRunnerKit contributing guide](https://github.com/ScriptRunnerKit/.github/blob/main/CONTRIBUTING.md) |
| 4 | +and the [Code of Conduct](https://github.com/ScriptRunnerKit/.github/blob/main/CODE_OF_CONDUCT.md) apply here. This file |
| 5 | +adds what is specific to this repository: the tools, the checks the CI runs and how releases work. |
| 6 | + |
| 7 | +Before anything bigger than a small fix, open an issue to agree on the behavior and its acceptance criteria. Report |
| 8 | +security problems privately, as described in [SECURITY.md](SECURITY.md), never in a public issue. |
| 9 | + |
| 10 | +## Prerequisites |
| 11 | + |
| 12 | +- .NET 10 SDK (the version in `global.json`). |
| 13 | +- [uv](https://docs.astral.sh/uv/): the integration tests create real Python environments. |
| 14 | +- Node.js 24 (`panel/.nvmrc`): the dashboard UI, and Release builds that embed it. |
| 15 | +- Docker: the tests for PostgreSQL, RabbitMQ, the worker, the dashboard, the containers and the Aspire AppHost use |
| 16 | + Testcontainers or Aspire. |
| 17 | + |
| 18 | +## Build and test |
| 19 | + |
| 20 | +```bash |
| 21 | +dotnet build |
| 22 | +dotnet test --solution tests/PythonScriptRunner.SemE2E.slnf # unit, integration and dashboard tests |
| 23 | +dotnet test --project tests/PythonScriptRunner.Containers.Tests # host images and compose |
| 24 | +dotnet test --project tests/PythonScriptRunner.AppHost.Tests # Aspire AppHost |
| 25 | +dotnet build tests/PythonScriptRunner.Panel.E2E.Tests -p:PsrBuildPanel=true |
| 26 | +dotnet test --project tests/PythonScriptRunner.Panel.E2E.Tests --no-build # run it on its own |
| 27 | + |
| 28 | +cd python/psrunner && uv sync && uv run pytest |
| 29 | +cd panel && npm ci && npm test |
| 30 | +``` |
| 31 | + |
| 32 | +The [README](README.md#development) explains each test project, the environment variables the tests read, and how to run |
| 33 | +the local environment with .NET Aspire. |
| 34 | + |
| 35 | +## What the CI checks |
| 36 | + |
| 37 | +A pull request is merged only when every job of `.github/workflows/ci.yml` is green. Run the same checks locally: |
| 38 | + |
| 39 | +| Area | Checks | |
| 40 | +|------|--------| |
| 41 | +| .NET | builds with warnings as errors, the latest analyzers and code style enforced in the build; `dotnet format --verify-no-changes`; tests on Linux, and the Core tests on Windows | |
| 42 | +| Packages | `dotnet pack` produces the 7 packages with one version and their symbol packages | |
| 43 | +| Containers | both Dockerfiles build; the images run read-only as a non-root user; the memory limit and the compose from `aspire publish` work | |
| 44 | +| Python SDK | `uv run ruff check src tests`, `uv run ruff format --check src tests`, `uv run mypy` (strict) and `uv run pytest`, on Python 3.10 to 3.13 | |
| 45 | +| Panel | `npm run lint`, `npm run typecheck`, `npm run api:check`, `npm test` and `npm run build` (initial bundle ≤ 500 KB gzip) | |
| 46 | +| Dependencies | no known vulnerable NuGet packages, no high or critical npm advisories in runtime packages, `pip-audit` clean | |
| 47 | + |
| 48 | +## Conventions |
| 49 | + |
| 50 | +- **Tests:** every acceptance criterion and every fixed bug has a test. Integration tests run against real Python (uv), |
| 51 | + PostgreSQL and RabbitMQ (Testcontainers). |
| 52 | +- **Public API:** public types and members have XML documentation (the build generates it and fails on warnings). |
| 53 | +- **Packages:** versions live in `Directory.Packages.props` (Central Package Management). Dependabot proposes updates |
| 54 | + every Monday. |
| 55 | +- **Database:** a change to the model needs a migration. The design-time factory opens no connection: |
| 56 | + |
| 57 | + ```bash |
| 58 | + dotnet ef migrations add <Name> --project src/PythonScriptRunner.EntityFrameworkCore |
| 59 | + ``` |
| 60 | + |
| 61 | +- **Dashboard API:** the OpenAPI document is a snapshot. After an intended change, accept it with |
| 62 | + `PSR_ACCEPT_SNAPSHOTS=1` and regenerate the UI types with `npm run api` in `panel/`. |
| 63 | +- **Contracts:** the JSON Schemas in `schemas/` and the protocol shared with `psrunner` are public contracts. Changing |
| 64 | + them in an incompatible way needs a new schema or protocol version. |
| 65 | +- **Changelog:** user-visible changes get a line in [CHANGELOG.md](CHANGELOG.md), under the version being prepared. |
| 66 | +- **Commits:** [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`, `docs:`, `test:`, |
| 67 | + `build:`, `ci:`, `chore:`). |
| 68 | + |
| 69 | +## Releases |
| 70 | + |
| 71 | +Maintainers release from tags on `main`; each tag runs the full CI before anything is published. |
| 72 | + |
| 73 | +- **.NET packages and images:** |
| 74 | + 1. Date the version's section in `CHANGELOG.md`. |
| 75 | + 2. Push the tag `vX.Y.Z`. |
| 76 | + 3. `release.yml` waits for approval in the `release` environment. It then publishes the 7 NuGet packages, the two |
| 77 | + multi-arch images to GHCR and the GitHub Release, with the CHANGELOG section as its notes. |
| 78 | + |
| 79 | + MinVer takes the version from the tag. A tag with a suffix (`v0.2.0-rc.1`) is published as a prerelease. |
| 80 | +- **psrunner:** |
| 81 | + 1. Set the version in `python/psrunner/src/psrunner/_version.py`. |
| 82 | + 2. Push the tag `python/vX.Y.Z`. |
| 83 | + 3. `release-python.yml` publishes it to PyPI with trusted publishing. |
0 commit comments