Skip to content

Commit b6c7f79

Browse files
net0wellclaude
andcommitted
docs: README em inglês, CONTRIBUTING, CHANGELOG e SECURITY (spec 009)
O README (que também vai para o nuget.org) passa para o inglês com o mesmo conteúdo e ganha as seções da fase 7: pacotes, imagens no GHCR, volumes e sistema de arquivos somente leitura, limites de memória (cgroup v2 ou RLIMIT_AS + ThreadsPerProcess), exemplo de Kubernetes, ambiente Aspire, docker-compose pelo aspire publish e a matriz de compatibilidade (D-178). CHANGELOG segue o Keep a Changelog; a seção [0.1.0] vira as notas do GitHub Release. SECURITY descreve o modelo de segurança (autores confiáveis, sem sandbox) e o reporte privado pelo GitHub. CONTRIBUTING lista pré-requisitos, as verificações do CI e o processo de release (D-186). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1 parent e609567 commit b6c7f79

4 files changed

Lines changed: 660 additions & 168 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
# Changelog
2+
3+
All notable changes to PythonScriptRunner are documented in this file. The format is based on
4+
[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project follows
5+
[Semantic Versioning](https://semver.org/spec/v2.0.0.html). The NuGet packages and the container images share one
6+
version; the `psrunner` SDK has its own version on PyPI.
7+
8+
## [0.1.0] - Unreleased
9+
10+
The first release.
11+
12+
### Added
13+
14+
- **Core runner** (`PythonScriptRunner.Core`, `PythonScriptRunner.Abstractions`):
15+
- stages with typed inputs and outputs (12 field types, including `table`, `file` and `list<T>`), defined in
16+
`stage.json` or in C#;
17+
- each attempt runs in an isolated process: a clean environment, its own work folder, a timeout and a memory limit
18+
(Job Object on Windows; cgroup v2 when it can be delegated on Linux, otherwise `RLIMIT_AS` with
19+
`ThreadsPerProcess`);
20+
- secrets reach only the stages that declare them, and are masked in the captured output;
21+
- Python environments created and cached by uv, one per set of dependencies.
22+
- **Pipelines:**
23+
- steps bound to the pipeline's inputs, to earlier steps' outputs or to constants;
24+
- types and bindings validated when the catalog loads;
25+
- defined in `*.pipeline.json` or in C#.
26+
- **`psrunner` 0.1.0**, the Python SDK:
27+
- `@stage`, `Context`, `File` and `StageError`;
28+
- `psrunner.testing.run_stage`, to test stages with pytest without .NET.
29+
- **Persistence** (`PythonScriptRunner.EntityFrameworkCore`, PostgreSQL 16+):
30+
- a versioned catalog (draft, published, archived), with dependencies locked by hash on publish and zip import and
31+
export;
32+
- the full history of runs, attempts, logs and files;
33+
- idempotency keys, an audit log and partitioned retention.
34+
- **Queue** (`PythonScriptRunner.RabbitMQ`, RabbitMQ 3.13+):
35+
- queued runs through a transactional outbox;
36+
- the public `StartPipelineRun` command, `run.*` and `step.*` events, and subscriptions for event handlers.
37+
- **Worker** (`PythonScriptRunner.Worker`):
38+
- leases, retries with exponential backoff, recovery of lost workers and cancellation;
39+
- concurrency limits per worker and per pipeline;
40+
- cron schedules with IANA time zones and catch-up runs.
41+
- **Dashboard** (`PythonScriptRunner.Dashboard`):
42+
- an embeddable dashboard with an internal API and real-time updates (SignalR);
43+
- a Vue UI to edit, test and publish stages and pipelines, follow runs live, and manage schedules, the audit log and
44+
administration;
45+
- four cumulative roles, and access by fixed login, a custom filter, host authentication or local requests.
46+
- **`psr` tool** (`PythonScriptRunner.Tool`): `psr hash-password` generates the password hashes for fixed login.
47+
- **Hosts and images:**
48+
- `WorkerHost` and `DashboardHost`, configured by environment variables, with health checks, JSON logs, OpenTelemetry
49+
and optional migrations at startup (`PSR_AUTO_MIGRATE`). The DashboardHost also supports OpenID Connect;
50+
- multi-arch images `ghcr.io/scriptrunnerkit/psr-worker` and `ghcr.io/scriptrunnerkit/psr-dashboard`: non-root,
51+
read-only root file system, with an SBOM and provenance.
52+
- **Local environment:** a .NET Aspire AppHost with PostgreSQL, RabbitMQ, Mailpit, both hosts and the UI in development
53+
mode. `aspire publish` generates a Docker Compose file from it.
54+
55+
### Compatibility
56+
57+
| PythonScriptRunner (NuGet and images) | .NET | Protocol | `psrunner` | Python |
58+
|---------------------------------------|------|----------|------------|--------|
59+
| 0.1.0 | 10 | 1 | 0.1.x | 3.10–3.13 |
60+
61+
[0.1.0]: https://github.com/ScriptRunnerKit/PythonScriptRunner/releases/tag/v0.1.0

‎CONTRIBUTING.md‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
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

Comments
 (0)