Development and releases

This standalone repository follows coderpad-cli main at cf613fc21b457ff85fc13f89daf99ff0e9625ecf. It adapts the src layout, Click entry points, setuptools-scm versions, uv lockfile, strict checks, 100% branch coverage, Sphinx, Towncrier, and distribution workflows. The SDK baseline is the released hackerrank==2026.9.16 in uv.lock. Python 3.13 or later is required by the SDK.

The released SDK exposes questions.upload_project_zip. Its newer upload_project_directory helper is not yet released. This CLI prepares filtered ZIPs with the standard library and uses the public released SDK for multipart serialization and all API communication. It does not import private SDK helpers or install an unreleased Git dependency.

uv sync --locked --group dev
uv run pytest
uv run prek run --all-files
uv run prek run --all-files --stage pre-push
uv run sphinx-build -W --keep-going -b html docs/source docs/build/html
uv build
uv run twine check dist/*
uv run check-wheel-contents dist/*.whl

Tests use the real SDK with its public Transport interface and default HTTPX transport. No SDK methods are replaced and no live questions are mutated. RESPX intercepts the HTTP boundary and fails closed for unregistered requests. Tests inspect the actual multipart body and ZIP bytes, assert the absence of metadata updates, preserve text, binary contents and executable bits, and exercise SDK retries with immutable archive bytes.

The SDK’s checked-in Swagger specification does not describe the upload_project_zip endpoint. The upload tests therefore assert the released SDK’s actual wire behavior instead of inventing an OpenAPI schema. No separate mock-spec repository is needed for this scope.

Add a Towncrier feature or bugfix fragment for each user-visible change.

Versions derive from Git tags using setuptools-scm. Untagged initial builds have a development version. Use date-based tags such as 2026.10.02 for releases; no release tag is created as part of repository initialization. Before tagging a release, assemble notes with uv run towncrier build --yes --version VERSION, commit the changelog, then write the same version to VERSION, commit it, then tag the commit. Pushing a tag is the explicit publication trigger. The release workflow builds and checks packages, builds three standalone binaries, and then publishes to PyPI, GitHub Releases, and GHCR.

Local builds

uv run --group binary pyinstaller --clean --onefile --copy-metadata hackerrank-cli --name hackerrank bin/hackerrank_wrapper.py
./dist/hackerrank --help
docker build -t hackerrank-cli .
docker run --rm hackerrank-cli --help
nix flake check
nix build
nix run . -- --help

The Docker image builds a wheel from this checkout rather than depending on an unpublished PyPI artifact. Mount content read-only and forward the existing environment variable for an upload:

docker run --rm -e HACKERRANK_API_TOKEN -v "$PWD/starter:/starter:ro" hackerrank-cli questions upload 123456 --directory /starter --dry-run

The Nix flake uses uv2nix and the committed lockfiles. Its build injects an SCM version because Git metadata is unavailable in Nix source snapshots. Ordinary macOS CI builds use PyInstaller’s ad-hoc signature and do not use Apple credentials. Distribution signing and notarization are required by the release workflow. See macOS releases for signing, notarization, and credential setup.

External setup

  • Register a PyPI trusted publisher for project hackerrank-cli, owner adamtheturtle, repository hackerrank-cli, workflow release.yml, environment release. That GitHub environment already exists. No PyPI token is stored in the repository.

  • GitHub Pages is already enabled with the GitHub Actions source. Manually run publish-site.yml from main to redeploy documentation. Ordinary CI builds documentation without deploying it.

  • Allow Actions to create GitHub Releases and publish the repository’s GHCR package. Make the GHCR package public after the first release if needed.

  • Configure the five macOS signing and notarization repository secrets in macOS releases before releasing. A missing credential fails the build; releases cannot fall back to an unsigned macOS binary.

  • No Homebrew tap, winget manifest, package-manager registration, or TestPyPI configuration has been created. Do not advertise those installation paths until they exist.

The default branch already requires 15 Actions checks: tests on Python 3.13 and 3.14 across Linux, macOS, and Windows, lint, documentation, packaging, two Nix builds, three standalone binaries, and autofix. The public repository’s tests and builds do not need a HackerRank token.