# Contributing

Thanks for improving deepseek-kubernetes-sandbox. This repository packages
DeepSeek Harness Web as a container and ships self-contained implementation
examples around it. The root is the container; every implementation lives
under examples/.

## Repository layout

| Path | Purpose |
| --- | --- |
| Dockerfile | The primary artifact: the DSH Web image |
| versions.env | Single source of truth for every pinned version |
| Makefile | Canonical local entrypoint (build, test, lint, check, e2e) |
| docs/ | Repository-wide docs: main image, example contract, gitflow, versioning |
| examples/ | One self-contained implementation per directory |
| scripts/ | Repository checks (versions, example layout, manifests, version bump) |
| .github/ | CI, releases, dependency updates, templates |

## Requirements

- Docker (for image builds)
- Python 3.12+ (gateway tests and repository checks)
- make and git
- kubectl and kind only for the end-to-end example

## Local workflow

    git switch -c feat/<short-slug>
    make check          # versions, example layout, manifest YAML
    make test           # gateway unit tests
    make lint           # ruff, shellcheck (+ yamllint/actionlint when installed)
    make image          # build the main DSH Web image
    make gateway        # build the example gateway image
    make e2e            # full kind walkthrough (optional, slow)

Install the gateway dev dependencies once:

    python -m pip install -r examples/dsh-agents-as-a-service/gateway/requirements-dev.txt

## Pull requests

- Use a Conventional Commit title, for example feat(gateway): add wake metrics
  or docs(examples): clarify SSO trust boundary. PR titles are linted.
- Keep the diff scoped. Squash merge into main; history stays linear.
- Required on every PR: lint, pr-title, CodeQL (both Analyze jobs) and
  dependency-review. python, manifests and build-amd64 are path-filtered
  on-demand checks; run them when the change touches their scope. Branch
  protection is described in docs/gitflow.md.
- Update the docs that the change affects; docs are part of the change, not a
  follow-up.
- Never commit a real secret. Secret-shaped YAML belongs in a *.yaml.example
  file, and versions live in versions.env only.

## Changing versions

    make set-version DSH_VERSION=dsh-vX.Y.Z RELEASE_REVISION=r2
    make check

CHANGELOG.md is generated by git-cliff from Conventional Commits. Do not edit
it by hand; the release workflow regenerates it.

## Adding an example

Read docs/examples.md, then add examples/<name>/ with a README.md,
numbered manifests/NN-*.yaml, optional manifests/optional/<feature>/ or
manifests/exposure/<variant>/ (each with a README), optional components (a
Dockerfile plus README and tests), and executable, idempotent, self-cleaning
scripts. Add the literal examples/<name>/ entry to examples/README.md;
scripts/check-examples.sh enforces the layout.

## Documentation

- Root README.md is the front door: main image first, then examples.
- docs/ holds repository-wide material; example-specific material belongs in
  the example directory.

## Branches and releases

See docs/gitflow.md for the branch model and docs/versioning.md for the
release identity, channels and rollback rules.

## Security

See SECURITY.md. Report vulnerabilities privately through GitHub Security
Advisories; do not open a public issue.