Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
60 lines (40 loc) · 2.97 KB

CONTRIBUTING.md

File metadata and controls

60 lines (40 loc) · 2.97 KB
Raw

Contributing to TrainKit

Thanks for improving TrainKit. Keep changes focused, add regression coverage for behavior changes, and avoid weakening the local security boundary for convenience.

Development setup

Install Node.js 22.12+, uv, Python 3.12, and the Microsoft Visual C++ x64 Redistributable on Windows. Then run:

npm ci
uv sync --project backend --locked
npm start

The renderer and Electron main process are TypeScript. The authenticated processing backend is Python/FastAPI. See docs/architecture.md before changing IPC, process startup, filesystem access, or job state.

Required checks

Run these from the repository root before opening a pull request:

npm run verify
npm audit
npm run package
npm run verify:package

npm run verify covers ESLint, TypeScript, Vitest, Ruff lint/format checks, and pytest. Add a test that fails before the fix whenever practical. Do not commit node_modules, Python environments, models, output datasets, logs, or package artifacts.

Project invariants

  • The renderer never receives the backend token or its port.
  • Renderer filesystem access must flow through narrow IPC and a user-selected path grant.
  • Backend HTTP and WebSocket access remains authenticated and loopback-only.
  • Resume manifests are untrusted and must remain scoped to the requested input/output roots.
  • Batch output uses collision preflight and atomic replacement.
  • Spandrel model loading remains .safetensors-only. Do not re-enable pickle-based .pt, .pth, or .ckpt loading.
  • Transformers loaders must not enable trust_remote_code without a separate, explicit security design.
  • Dependency and workflow changes must keep lockfiles and immutable action pins current.

Pull requests

Describe the user-visible result, tests performed, model/runtime assumptions, and any migration or security impact. Keep generated lockfile changes in the same commit as their manifest changes.

User-visible changes must update CHANGELOG.md under the target version. The release workflow publishes that version's changelog section verbatim as the GitHub release notes, so keep entries complete, user-focused, and accurate.

Maintainer release setup

Tagged releases must match package.json exactly (for example, version 1.2.1 requires tag v1.2.1). Releases are unsigned by default. To Authenticode-sign the packaged executable, configure both GitHub Actions secrets:

  • WINDOWS_CERTIFICATE_BASE64: Base64-encoded PFX code-signing certificate.
  • WINDOWS_CERTIFICATE_PASSWORD: PFX password.

PowerShell can encode a PFX without printing binary data:

[Convert]::ToBase64String([IO.File]::ReadAllBytes("C:\path\TrainKit.pfx"))

When both secrets are configured, the release workflow verifies the application Authenticode signature. Without them, it publishes an explicit unsigned-build warning. Every release contains only the standard Windows ZIP plus its SHA-256 checksum and GitHub build-provenance attestation.