# Code Sample Standard: [Documentation set or product name]

> Rules for code samples and snippets in documentation: what a sample
> must contain, how it is tested in CI, how it is licensed and
> attributed, how it handles secrets, versions and errors, and how it
> is reviewed and retired. Licence tagging follows SPDX identifiers and
> the REUSE Specification 3.3. Replace every `[bracketed]` value and
> every row marked *Example*. The examples use a fictional SDK, the
> Quarrow Storage SDK.

<!--
Guidance: How to use this template
- Readers copy samples straight into production code. Treat every
  sample as shipped code: tested, licensed, secure and current.
- Decide the testing approach first (section 4). Rules nobody can check
  automatically will drift.
- Keep samples in files in the repository and include them into pages,
  rather than pasting code into Markdown, so the same file is tested
  and published.
-->

## Document control

<!-- Guidance: Record the owner and the repositories the standard applies to. -->

| Field | Value |
|---|---|
| Document ID | [DOC-CODE-001] |
| Version | [1.0] |
| Status | [Draft / Approved] |
| Owner | [@docs-engineering-lead] |
| Approvers/reviewers | [@sdk-lead], [@security-reviewer], [@legal-or-open-source-office] |
| Applies to | [Docs site, SDK READMEs, API reference, blog tutorials] |
| Sample licence | [MIT-0 / Apache-2.0 / MIT] |
| Last updated | YYYY-MM-DD |

### Revision history

| Version | Date | Author | Change |
|---|---|---|---|
| 1.0 | YYYY-MM-DD | [@name] | First version |

## 1. Sample types

<!-- Guidance: Name the kinds of samples you publish; each type has different testing and completeness rules. -->

| Type | Definition | Must run as published? | Tested by |
|---|---|---|---|
| Snippet | A few lines showing one call, inside a page | No, but must compile in a test harness | Harness file that wraps it |
| Complete sample | A runnable file or small program | Yes | CI job per language |
| Sample application | A repository a reader clones | Yes | Its own CI pipeline |
| Shell command | A command line with expected output | Yes, in a clean container | Doc-test runner |

## 2. Content rules

<!-- Guidance: These rules make a sample useful when copied. -->

1. **Show the task, not the API.** Each sample solves one task named in
   its heading ("Upload a file with a retry"), not "Using `putObject`".
2. **Complete enough to run.** Complete samples include imports, client
   setup and cleanup. Snippets state what they assume in a comment.
3. **Handle errors as production code would.** Catch the documented
   errors and show what to do; never swallow exceptions silently.
4. **Use realistic, harmless values.** Use reserved example domains
   (`example.com`), placeholder IDs and the fictional names from your
   style guide.
5. **Pin versions.** State the SDK or runtime version the sample was
   tested with.
6. **Show the output.** Give expected output after commands and samples,
   so readers can tell whether they succeeded.
7. **Follow the language's idioms and formatter.** Run the standard
   formatter and linter for the language.
8. **Keep it short.** Remove everything that does not serve the task.
   Move setup code into a shared helper if it repeats.
9. **Comment the why.** Comments explain decisions and caveats, not
   what each line does.

*Example complete sample (Python):*

```python
# SPDX-FileCopyrightText: 2026 Quarrow Labs
# SPDX-License-Identifier: MIT-0
# Tested with quarrow-storage 2.3.1 and Python 3.13.
import os

from quarrow_storage import Client, NotFoundError

client = Client(api_key=os.environ["QUARROW_API_KEY"])

try:
    obj = client.objects.get(bucket="reports", key="2026/q3.pdf")
    print(f"Downloaded {obj.size} bytes")
except NotFoundError:
    print("No report for Q3 yet. Check the key or upload it first.")
```

## 3. Secrets and security

<!-- Guidance: Samples are a common source of leaked credentials and insecure patterns. -->

- Never put real credentials, tokens or private URLs in a sample.
  Read secrets from environment variables or a secret store and say so.
- Use placeholder values that secret scanners recognise as fake, and
  run a secret scanner on the docs repository.
- Do not disable TLS verification, use deprecated cryptography or turn
  off input validation in a sample, even "for simplicity".
- Apply least privilege in examples of permissions and policies.
- Security review is required for samples about authentication,
  cryptography, payments and access control.

## 4. Testing

<!-- Guidance: Every published sample is executed or compiled in CI. Pick the mechanism per language and record it. -->

```mermaid
flowchart LR
  A["Sample file in repo"] --> B["CI: format and lint"]
  B --> C["CI: compile or run against test environment"]
  C --> D{"Pass?"}
  D -->|Yes| E["Docs build includes the file"]
  D -->|No| F["Build fails, owner fixed before merge"]
```

| Language | Mechanism *(Example)* | Environment |
|---|---|---|
| Python | Samples run as scripts by pytest; doctest for short snippets | Sandbox account, seeded data |
| JavaScript / TypeScript | Type-check every snippet with a wrapper; run complete samples with the test runner | Sandbox account |
| Shell | Commands run in a clean container; output compared with the documented output, ignoring marked variable lines | Container image [name:tag] |
| [Language] | [Mechanism] | [Environment] |

Rules:

- Tests run on every docs change and on every SDK release, so a breaking
  SDK change fails the docs build.
- A sample that cannot be tested (for example, it needs real hardware)
  is labelled "Not tested in CI" with the date it was last checked by
  hand, and reviewed every [6] months.

## 5. Licensing and attribution

<!-- Guidance: Readers need to know they may copy the sample. Decide the licence once and tag every file. -->

- Publish samples under a permissive licence that does not require
  attribution in the reader's code, such as `MIT-0` or `0BSD`, or
  state clearly what the licence requires. *(Decision: [licence])*
- Tag each sample file with `SPDX-FileCopyrightText` and
  `SPDX-License-Identifier` headers, and keep the licence texts in a
  `LICENSES/` directory, as the REUSE Specification 3.3 describes.
  Where per-file headers are impractical, use a `REUSE.toml` file.
- If the docs text has a different licence from the code (for example
  CC BY 4.0 for prose), say so in the site footer.
- Do not paste third-party code into samples unless its licence allows
  it, and keep its original copyright notice and identifier.
- Do not publish code generated by an AI assistant without the same
  review, testing and licence check as human-written code.

## 6. Presentation

<!-- Guidance: Rules for how samples look on the page. -->

- Always set the language on fenced code blocks for highlighting.
- Show prompts (`$`) only in shell samples where output is shown, and
  make the copy button strip them.
- Use tabs for the same sample in several languages; keep the variable
  names and steps identical across tabs.
- Mark lines the reader must change with a comment such as
  `# Replace with your bucket name`.
- Keep line length under [80] characters so samples do not scroll on
  narrow screens.

## 7. Versioning and retirement

<!-- Guidance: Samples go stale when the product changes. Plan for it. -->

| Event | Action |
|---|---|
| New SDK major version | Update samples or label them with the old version; tests run on both versions until the old one is retired |
| API deprecation | Replace samples that use the deprecated call before the removal date |
| Sample not viewed in [12] months and not linked | Review for removal |
| Security issue found in a pattern | Fix every sample using it, then add a lint rule |

## 8. Review checklist

<!-- Guidance: Reviewers tick each item before merging a sample. -->

- [ ] Solves one named task and runs as published (or compiles in harness).
- [ ] Tested in CI, with the tested version stated.
- [ ] No secrets, no insecure shortcuts, errors handled.
- [ ] SPDX header present and licence matches the decision in section 5.
- [ ] Formatter and linter pass; idiomatic for the language.
- [ ] Expected output shown; lines to change are marked.

## 9. Ownership and metrics

<!-- Guidance: Assign owners so failures get fixed. -->

| Item | Value |
|---|---|
| Owner per language | [@python-owner], [@js-owner] |
| Failing sample fix target | [2] working days |
| Metric | Share of published samples tested in CI, target [100]% |
| Metric | Samples broken by an SDK release before docs were updated, target [0] |

## 10. References

<!-- Guidance: List specifications and related templates. -->

- SPDX License List, version 3.29.0 (2026-09-16): https://spdx.org/licenses/.
- REUSE Specification, version 3.3 (2024-11-14): https://reuse.software/spec-3.3/.
- Related templates: `docs/docs-contribution-guide`,
  `docs/style-guide-technical`, `docs/sdk-overview`,
  `docs/developer-guide`, `dev/coding-standards`, `dev/library-readme`.

## Standard and licence note

Based on common docs-as-code practice and on the public SPDX License
List and REUSE Specification 3.3 for licence tagging. This template is
original text written for this collection. Check the current SPDX list
and REUSE version before relying on them, and ask your legal or open
source office to confirm the sample licence. Template licence: MIT.