samples

Sample workspaces for Stuga. Each one is a workspace archive, unzipped: the files of a .stuga.zip, as docs/workspace-archive.md describes them.

How a node uses them

Each release of this repository carries every sample as <id>.stuga.zip, and lists them in index.json. When someone creates a workspace, their node offers the samples that index.json in the latest release lists, and checks the archive it downloads against the SHA-256 and size listed there. A new release changes what nodes offer; a workspace already created from a sample never changes.

Layout

samples/<id>/                a workspace archive, unzipped
samples/<id>.json            its listing: what index.json says of it, and its sources
scripts/check.mjs            checks every sample
scripts/build.mjs            zips every sample into dist/ and writes dist/index.json
scripts/python-specs.mjs     writes python-specs from the PEP index and python/peps
scripts/team-handbook.mjs    writes team-handbook from 18F Guides
scripts/market-research.mjs  writes market-research from World Bank data
scripts/privacy-laws.mjs     writes privacy-laws around the documents in its Laws/ folder
scripts/laws/<law>.mjs       writes one of those documents from the law's official source
scripts/markdown.mjs         the Markdown writer the four sample scripts share

The scripts need Node 22.2 or later. To fetch, scripts/laws/uae-pdpl.mjs also needs Playwright and Google Chrome.

A sample's listing

<id> is 1 to 40 of a-z, 0-9 and -, starting with a letter or digit. samples/<id>.json holds:

Field	Value
title	Up to 60 characters.
description	Up to 60 characters: one short line under the title.
langs	The languages of its text, as primary language tags: en, zh.
position	Its place in the list of samples, from 1.
sources_doc	The path of its Sources document in the archive.
sources	Each {title, url, license, retrieved}: where third-party material comes from, its licence, and the day it was fetched, YYYY-MM-DD. The Sources document links each url.

The new workspace's name is workspace.name in the sample's stuga.json. license is one of:

license	Meaning
CC0-1.0	Creative Commons Zero 1.0
CC-BY-4.0	Creative Commons Attribution 4.0
LicenseRef-public-domain	Placed in the public domain by its author
LicenseRef-official-text	An official text that its country's copyright law does not protect
LicenseRef-eu-reuse	Reuse allowed with acknowledgement, Commission Decision 2011/833/EU

Adding or changing a sample

A sample that a script writes is changed in the script: run it, then go on from step 6.

1. Build or edit the workspace in Stuga.
2. Export it: Settings → This workspace → General → Export workspace.
3. Unzip it into samples/<id>/, replacing what was there: rm -rf samples/<id> && unzip -q <file>.stuga.zip -d samples/<id>.
4. Add start to its stuga.json, the path of its Start here document, which the new workspace opens at, and sample.steps: what Sample agent proposes after an import (Sample steps). An export has neither, so carry both over whenever stuga.json is replaced.
5. Write or update samples/<id>.json.
6. Check it: node scripts/check.mjs. With --stuga <dir>, a checkout of stuga-dev/stuga after pnpm install, it also runs stuga-node archive check on each sample, which reads every body, row, link, image and step as an import would: node scripts/check.mjs --stuga ../stuga.
7. Open a pull request. A reviewer checks its facts and legal summaries against the sources.
8. Once it is merged, bring your main up to date and tag it with the day: git switch main && git pull --ff-only, then git tag -a vYYYY.MM.DD -m vYYYY.MM.DD && git push origin vYYYY.MM.DD, or vYYYY.MM.DD.N for another release that day. The release workflow checks and builds every sample, then publishes the archives and index.json as that tag's release. A published release never changes: a fix is a new tag. Since nodes read the latest release, a tag older than the newest is refused, and so is one on any commit but main's newest.

Licensing

What Stuga wrote here, sample text, scripts and workflows, is dedicated to the public domain under CC0-1.0. Third-party material in a sample keeps its own terms: the sample's Sources document lists its sources and their terms, and its listing names each licence. Naming a source implies no endorsement by it.