The repository owner maintains shared setup guidance; contributors use it before running project checks. Workspace/build manifests and tool configuration own membership and executable settings. This guide routes to those authorities rather than maintaining a second project database.
The pnpm workspace defines members and their shared lockfile/linking settings. Root scripts define the build, test, lint and format fan-out. Use mise for tool version intent and the lockfile for resolved tool versions.
From the repository root, pnpm install prepares the workspace. pnpm run build
runs package builds; the test, lint and format scripts use --if-present for
packages without those scripts. Review needed install scripts with
pnpm approve-builds; do not globally disable the package-manager checks.
pyproject.toml owns uv workspace membership. Projects live
under src/, with internal delivery fixtures under tests/; there is no separate
top-level OnePython/ workspace. Project
manifests own their dependencies, supported versions and package contracts.
The root .python-version and setup-uv configuration .config/uv/uv.toml
are generated from mise.lock, checked against
mise.toml. After a Python or UV lock update, run
mise run sync:python-version; HK checks projection drift. Synchronize an
existing environment before using --no-sync. For example:
uv sync --frozenmise run test:python runs the
native Python group
in explicit full mode against committed HEAD on Linux, including configured
pytest targets and adopted distribution checks. Commit tracked changes before
using this command; Windows contributors need a Linux environment for it.
For the internal application's managed tests, prepare the pinned SDK/tools and
run dotnet test --project tests/private/app/workflow-delivery/WorkflowDelivery.Tests.csproj
from the repository root. That project check does not replace the complete native
Python group. Ordinary commits run HK source checks;
affected CI owns project tests. The
execution contract explains selection,
required results and timing evidence. Scholarly-publication's standalone
script runtime remains governed by its own package contract.
The root pytest configuration releases successful tmp_path fixtures and the
implicit temporary session directory after a successful run. Failed test-call
fixtures remain available for diagnosis within pytest's default three-session
retention window; its existing cleanup locks protect active runs. This applies
to all tests using the root configuration in explicit local commands and CI.
Native callers own their separate scratch and cache directories. Root pytest
retention does not establish cleanup of native subprocess files outside
pytest-owned state.
Use an executable temporary filesystem with enough free bytes and inodes for
native integration fixtures. On Linux, check both df -h and df -i for that
filesystem. A fresh, task-owned TMPDIR (or TEMP on Windows) outside the
workspace ancestry can isolate a run; preserve its logs outside that directory.
Avoid reusing --basetemp: pytest clears that explicit path before a run, and
successful-session cleanup does not apply to it.
Cleanup is best effort. Forced termination can leave files and cleanup locks; pytest considers an abandoned lock eligible after three days, so interrupted runs do not have an immediate retention bound. For earlier recovery, preserve needed diagnostics and confirm the owning run and its child processes have exited before removing only that run's identified temporary directory. Never clear shared temporary roots or other runs' data. Native tool caches outside pytest's session directory follow their own lifecycle.
dirs.proj is the active C# traversal for src/, tests/ and
src/lab/. Shared SDK and package selection use
global.json and
Directory.Packages.props.
The compatibility rationale explains retained local
exceptions; the referenced build files own their values.
Install the tool versions recorded in mise.lock from the repository root:
mise install --lockedThe repository validates Linux x64 and Windows x64 lock entries. When tool versions change, refresh both mise configuration roots instead of running an unlocked platform-specific install:
mise lock --platform linux-x64,windows-x64
mise -C src/public/lib/hexo-renderer-asciidoc lock --platform linux-x64,windows-x64Run these refresh commands on Linux; WSL is sufficient. On Windows, mise currently writes no Ruby platform entries (jdx/mise#14517), so a Windows refresh drops Ruby from the lockfile. Locked installs and lockfile validation work on both platforms.
The repository requires MISE 2026.10.11 or later through min_version in
mise.toml. global.json is the .NET SDK authority: MISE reads its
sdk.version as an idiomatic version file with its built-in core:dotnet
backend, and mise.lock records that selection. Upgrade the SDK by editing
global.json (keep rollForward as disable) and then run
mise lock dotnet. Do not install version-fox/vfox-dotnet manually. If that legacy
plugin is already installed, remove it before installing the repository tools:
mise plugins uninstall dotnet
mise install --lockedHK is the sole Git hook and lint runner; the former prek-generated pre-commit configuration is no longer maintained.
Install the repository-managed Git hooks after installing the toolchain:
mise exec -- hk install --mise