torbenandClaude Code
71170bc1e8
Files changed: - .gitattributes - .gitea/workflows/converters.yml - .gitea/workflows/release.yml - .gitignore - CHANGES.md - VERSION - docs/dev/development.md - instructions/dev/dev-setup.md - instructions/dev/publish-and-ci.md - instructions/dev/testing-conventions.md - testfiles/README.md - testfiles/mail/github-outlook.msg - testfiles/mail/github-roundcube.eml - testfiles/mail/gog-outlook.msg - testfiles/mail/gog-roundcube.eml - testfiles/mail/gog-roundcube.eml.expect - testfiles/mail/tldr-outlook.msg - testfiles/mail/tldr-roundcube.eml - testfiles/office/excel-artificial.xlsx - testfiles/office/excel-business.xlsx - testfiles/office/excel-business.xlsx.expect - testfiles/office/excel-science.xlsx - testfiles/office/pptx-baseline.pptx - testfiles/office/pptx-master.pptx - testfiles/office/pptx-objects.pptx - testfiles/office/word-complex.docx - testfiles/office/word-simple.docx - testfiles/pdf/einstein-dissertation.pdf - testfiles/pdf/ifg.pdf - testfiles/pdf/nist-ai-rmf.pdf - testfiles/pdf/nist-ssdf-genai.pdf - testfiles/zip/archive.zip - tools/chemenu/tests/test_raw_derive_testfiles.py Co-Authored-By: Claude Code <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SnAJ7Z3CpVD3PRbN73QtU2
92 lines
5.1 KiB
Markdown
92 lines
5.1 KiB
Markdown
---
|
|
type: types/instruction.md
|
|
name: dev-setup
|
|
description: Set up a clone of the origin repository for stack development - preflight, skills, the demo corpus and its persona, telemetry on - and use dist export as a build and test tool, never as a way to install an instance.
|
|
---
|
|
# Set up a development checkout of the stack
|
|
|
|
A clone of the origin repository is where the stack is developed. It is not an instance: it
|
|
carries a demo corpus that documents the stack itself, a demo persona in `USER.md`/`SOUL.md`, the
|
|
development material under `instructions/dev/` and `commonplace/`, and no
|
|
`.wikitool-release.json`. Instances are installed from releases
|
|
([setup-instance.md](../setup-instance.md)); nothing here produces one.
|
|
|
|
## When to run
|
|
|
|
- A fresh clone of the origin repository, before the first stack-dev session in it.
|
|
- A clone that was moved, or whose `tools/.venv` was removed - only step 2 again.
|
|
- Before testing a change to the install path itself (`setup-instance.md`, the preflight, the
|
|
release workflow) - step 5.
|
|
|
|
## Steps
|
|
|
|
1. **Clone** the origin repository. The tree is complete as checked out: `kb/`, `raw/`,
|
|
`USER.md`, `SOUL.md` and the filled `kb/CONVENTIONS.md` are committed here, unlike in an
|
|
instance.
|
|
|
|
2. **Run [bootstrap.md](../bootstrap.md)** - the preflight, then `tools/wikitool instructions
|
|
sync`. That publishes `stack-dev`, `stack-build` and `stack-close` along with the content skills;
|
|
all three exist only in this repository.
|
|
|
|
3. **Record the environment** (bootstrap.md step 5). Here it is worth the minute: which harness,
|
|
that `gitea-mcp` reaches the tracker and CI, which remote `publish` talks to. Every stack-dev
|
|
session reads it instead of asking.
|
|
|
|
4. **Know what differs from an instance before relying on a default.**
|
|
|
|
| Here | In an instance |
|
|
|---|---|
|
|
| No `.wikitool-release.json`: telemetry is **on** - the traces are the stack's measuring instrument ([telemetry-and-evaluation.md](../../docs/explanation/telemetry-and-evaluation.md#whether-it-runs-at-all)) | Telemetry is off until the operator turns it on |
|
|
| `USER.md`/`SOUL.md` describe a demo operator and persona | Written by the operator during setup |
|
|
| `tools/wikitool dist upgrade` refuses: there is no stamp to compare against. The checkout follows `main` with `tools/wikitool sync` | Updated with `dist upgrade --latest` |
|
|
| `instructions/dev/`, `docs/dev/`, `commonplace/` and `.gitea/` are present | Never shipped |
|
|
| `testfiles/` may hold the private test corpus (step 6) | Never present |
|
|
|
|
5. **Use `dist export` as a build and test tool.** It writes exactly the tree a release ships, so
|
|
it is how a change to the shipped surface is looked at before it is released:
|
|
|
|
```bash
|
|
tools/wikitool dist export <empty scratch folder> --dry-run
|
|
tools/wikitool dist export <empty scratch folder>
|
|
```
|
|
|
|
To replay the install path the way a user meets it, build the release tarball from that tree
|
|
the way `.gitea/workflows/release.yml` does (one top-level folder, a `.sha256` beside it) and
|
|
start the tree's `tools/preflight.sh` as the asset, from an empty folder, with
|
|
`--archive <tarball>` - the step "The distribution works as a fresh instance" in
|
|
`.gitea/workflows/ci.yml` is that replay and the reference for it. Keep scratch trees outside
|
|
this checkout.
|
|
|
|
6. **Clone the private test corpus, if you have access.** The real documents the converters are
|
|
tested against, and the harness that runs them, are a repository of their own and not part of
|
|
this one:
|
|
|
|
```bash
|
|
git clone ssh://git@gitea.nehmer.net:10101/torben/chemenu-testfiles.git testfiles
|
|
cd tools && .venv/bin/python -m pytest -c pytest.ini ../testfiles/harness
|
|
```
|
|
|
|
The clone sits in `testfiles/`, which `.gitignore` excludes; it is deliberately not a
|
|
submodule. Without access nothing breaks: `pytest` in `tools/` needs none of it, and a
|
|
session that changes a converter leaves the real-document run to the `converters` workflow
|
|
([publish-and-ci.md](publish-and-ci.md) step 3). What is missing without the clone is the
|
|
local run of that harness, nothing else. The corpus holds files that may not be public, so
|
|
nothing from it is copied into this repository, an issue or a bug report without its README
|
|
saying the file could be public.
|
|
|
|
## Decision points
|
|
|
|
- **Asked to set up an instance from this checkout** (`dist export` into the user's folder, or a
|
|
clone that "becomes" their wiki)? Neither is an install path. An instance is installed from a
|
|
release, by [setup-instance.md](../setup-instance.md); a stack state that has no release yet is
|
|
released first, or tested with the replay in step 5 and thrown away.
|
|
- **The demo corpus is in the way of a test?** Do not delete or rewrite corpus content to make
|
|
room: [corpus-policy.md](corpus-policy.md) says what may be changed and how. Use a scratch
|
|
export (step 5) for a clean tree instead.
|
|
|
|
## Scope
|
|
|
|
Not for operating an instance, and not for the release workflow itself (`docs/dev/development.md` for
|
|
humans, [version-parts.md](version-parts.md) for the version part). Not shipped: `dist export`
|
|
prunes `instructions/dev/` wholesale.
|