diff --git a/.changeset/readme-chapter.md b/.changeset/readme-chapter.md new file mode 100644 index 0000000..61c63e4 --- /dev/null +++ b/.changeset/readme-chapter.md @@ -0,0 +1,5 @@ +--- +"@variablelab/brand": minor +--- + +Add the `readme.md` chapter: the rules every README follows, the structure of each kind of README, and the `docs/contributing.md` and `docs/development.md` every repository keeps. `templates/project/` now holds a README and those two docs beside the `brand/` folder. `logo.md` says which Logo a README links, and `project-brand.md` that a README's `` takes a width and no height. diff --git a/AGENTS.md b/AGENTS.md index 61f16ad..c0ad5de 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -7,7 +7,8 @@ Variable Lab's brand guideline, design tokens and shared assets, the package `@v - `skills/vlab-brand/`: the guideline, as an Agent Skill. `SKILL.md` routes each task to one chapter; `glossary.md` holds the terms. - `tokens/tokens.json`: the only source of colors, fonts and the type scale. - `assets/`: the Logo and the Class stamps. No Project's Sign lives here. -- `templates/project/brand/`: what a Project copies into its own `brand/` folder. +- `templates/project/`: what a new Project copies: its README, its `docs/` and its `brand/` folder. +- `docs/`: this repository's contributing and development guides, for people. - `.github/readme/`: the images in the README. Generated. ## Rules @@ -35,7 +36,7 @@ mise installs node and pnpm, locally and in CI: run `mise install`, then `pnpm i ## Releasing -- Changes to `skills/`, `tokens/`, `assets/`, `templates/`, `BRAND-USE.md` or the `exports` in `package.json` carry a changeset: run `pnpm changeset`. Changes to the README, LICENSE, this file or CI don't. +- Changes to `skills/`, `tokens/`, `assets/`, `templates/`, `BRAND-USE.md` or the `exports` in `package.json` carry a changeset: run `pnpm changeset`. Changes to the README, LICENSE, `docs/`, this file or CI don't. - Major: a token, an export path or an asset path is removed or renamed. Minor: one is added, or a chapter. Patch: a value or a text changes. - Merging a change with a changeset to `main` opens or updates the "chore: update versions" pull request. Merging that pull request publishes to npm through trusted publishing. - Agents install the skill from `main` on GitHub, not from npm, so a change to `skills/` reaches them when it merges, before any release. diff --git a/README.md b/README.md index 7723aba..bbfaa12 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@

- The Logo: a green hexagon with a V + The Logo: a green hexagon with a V

Brand guideline

@@ -9,36 +9,32 @@ ## At a glance - **Dark, warm and flat.** One dark palette, no gradients, no shadows, square corners. -- **One Signature.** The green Logo with "Variable Land" beside it. No Project carries it. +- **One Signature.** The green Logo with "Variable Land" beside it. It signs everything Variable Lab publishes, set apart from a Project's Sign. No Project uses it as its own mark. - **A Sign per Project.** A Project starts with its Class stamp and earns a Sign: filled rectangles in one ink. - **Facts, in English.** Short declarative sentences a reader can check in the code. ## Palette -| | Token | Value | Use | -| --- | --- | --- | --- | -| | `ground` | `#14120e` | Page background. | -| | `surface` | `#1b1914` | Code blocks, command boxes and panels. | -| | `ink` | `#f3f0e8` | Main text, Signs and Class stamps. | -| | `ink-muted` | `#bdb7ab` | Secondary prose, such as the paragraph under a title. | -| | `dim` | `#a39e93` | Subtitles, meta, labels and secondary links. | -| | `rule` | `#2e2a24` | 1px rules and borders. | -| | `rule-strong` | `#3a362f` | Link underlines, hover borders, selection and scrollbars. | -| | `logo` | `#36d399` | The Logo, and nothing else. | +-  `ground` `#14120e`. Page background. +-  `surface` `#1b1914`. Code blocks, command boxes and panels. +-  `ink` `#f3f0e8`. Main text, Signs and Class stamps. +-  `ink-muted` `#bdb7ab`. Secondary prose, such as the paragraph under a title. +-  `dim` `#a39e93`. Subtitles, meta, labels and secondary links. +-  `rule` `#2e2a24`. 1px rules and borders. +-  `rule-strong` `#3a362f`. Link underlines, hover borders, selection and scrollbars. +-  `logo` `#36d399`. The Logo, and nothing else. Code is colored with soft Vesper: the roles and the peach and mint accents of [Vesper](https://github.com/raunofreiberg/vesper), on the palette's own warm neutrals. -| | Token | Value | Use | -| --- | --- | --- | --- | -| | `text` | `#f3f0e8` | Identifiers, punctuation and flags. | -| | `keyword` | `#a39e93` | `import`, `from`, `const`, `export`, `as` and operators; JSX attributes; a code block's file name. | -| | `function` | `#e8bf98` | Function calls and declarations; numbers, booleans, types and other `support.*` names; HTML tags and attributes; JSON keys; the first token of a shell command (`pnpm`). | -| | `string` | `#a3d9ca` | Strings, symbols and `constant.other.key`; the arguments of a shell command (`init`, package names). | -| | `comment` | `#8a857b` | Comments; a code block's language label. | -| | `gutter` | `#5f5a52` | Line numbers and the `$` prompt. | +-  `text` `#f3f0e8`. Identifiers, punctuation and flags. +-  `keyword` `#a39e93`. `import`, `from`, `const`, `export`, `as` and operators; JSX attributes; a code block's file name. +-  `function` `#e8bf98`. Function calls and declarations; numbers, booleans, types and other `support.*` names; HTML tags and attributes; JSON keys; the first token of a shell command (`pnpm`). +-  `string` `#a3d9ca`. Strings, symbols and `constant.other.key`; the arguments of a shell command (`init`, package names). +-  `comment` `#8a857b`. Comments; a code block's language label. +-  `gutter` `#5f5a52`. Line numbers and the `$` prompt. ## Type @@ -48,9 +44,9 @@ IBM Plex Sans for text and IBM Plex Mono for code, both in 400 and 500. Two weig ## Shapes

- The App Class stamp + The App Class stamp   - The Library Class stamp + The Library Class stamp

The Class stamps of an App and a Library: a body on a base, and a closed frame. Each Project's Sign is drawn on the same 24×24 grid and lives in that Project's own repository, in `brand/`. @@ -59,13 +55,14 @@ The Class stamps of an App and a Library: a body on a base, and a closed frame. | Chapter | Covers | | --- | --- | -| [Principles](skills/vlab-brand/principles.md) | The rules every other chapter follows. | -| [Logo](skills/vlab-brand/logo.md) | Color, the Signature, sizes and what to avoid. | -| [Color](skills/vlab-brand/color.md) | The palette, soft Vesper and contrast. | -| [Typography](skills/vlab-brand/typography.md) | Families, scale and text flow. | -| [Voice](skills/vlab-brand/voice.md) | Tone, names and how to say what a Project is. | -| [Iconography](skills/vlab-brand/iconography.md) | UI icons and shapes beside text. | -| [Project brand](skills/vlab-brand/project-brand.md) | Class stamps, how a Sign is drawn and a Project's `brand/` folder. | +| [Principles](https://github.com/withvariablelab/brand/blob/main/skills/vlab-brand/principles.md) | The rules every other chapter follows. | +| [Logo](https://github.com/withvariablelab/brand/blob/main/skills/vlab-brand/logo.md) | Color, the Signature, sizes and what to avoid. | +| [Color](https://github.com/withvariablelab/brand/blob/main/skills/vlab-brand/color.md) | The palette, soft Vesper and contrast. | +| [Typography](https://github.com/withvariablelab/brand/blob/main/skills/vlab-brand/typography.md) | Families, scale and text flow. | +| [Voice](https://github.com/withvariablelab/brand/blob/main/skills/vlab-brand/voice.md) | Tone, names and how to say what a Project is. | +| [Iconography](https://github.com/withvariablelab/brand/blob/main/skills/vlab-brand/iconography.md) | UI icons and shapes beside text. | +| [Project brand](https://github.com/withvariablelab/brand/blob/main/skills/vlab-brand/project-brand.md) | Class stamps, how a Sign is drawn and a Project's `brand/` folder. | +| [README](https://github.com/withvariablelab/brand/blob/main/skills/vlab-brand/readme.md) | The structure of each kind of README and the rules they share. | The guideline is also an [Agent Skill](https://agentskills.io), `vlab-brand`, so agents read the same text people do. @@ -88,6 +85,14 @@ pnpm add @variablelab/brand @fontsource/ibm-plex-sans @fontsource/ibm-plex-mono @import "@variablelab/brand/tokens.css"; /* plain CSS: var(--vlab-ground)… */ ``` +## Contributing + +The [contributing guide](https://github.com/withvariablelab/brand/blob/main/docs/contributing.md) covers issues, pull requests and releases, and the [development guide](https://github.com/withvariablelab/brand/blob/main/docs/development.md) covers setting up the repo and running its checks. + ## License -The code and the tokens are [MIT](LICENSE). The Logo, the Class stamps and the Signs are not: see [BRAND-USE.md](BRAND-USE.md). +The code and the tokens are [MIT](https://github.com/withvariablelab/brand/blob/main/LICENSE). The Logo, the Class stamps and the Signs are not: see [BRAND-USE.md](https://github.com/withvariablelab/brand/blob/main/BRAND-USE.md). + +

+  Variable Land +

diff --git a/docs/contributing.md b/docs/contributing.md new file mode 100644 index 0000000..1906be5 --- /dev/null +++ b/docs/contributing.md @@ -0,0 +1,32 @@ +# Contributing + +The brand repository takes fixes to the guideline, the tokens and the templates, and reports of a Variable Lab page or README that breaks a rule. To set up the repo and run its checks, see the [development guide](development.md). + +## Issues + +- A report names the chapter, the token or the file, and says what is wrong or missing. +- A new rule or token, or a change to the Logo, a Class stamp or the type scale, starts as an issue before any pull request. + +## Pull requests + +1. Branch from `main` with a prefix: `feat/`, `fix/`, `docs/`, `chore/` or `test/`. +2. Write commits as [Conventional Commits](https://www.conventionalcommits.org), such as `docs: fix a link in logo.md`. The pull request title takes the same form, because it becomes the squash commit. +3. Run `pnpm check` before you push. It fails when a generated file is out of date. + +CI has to pass, and a maintainer squash-merges. + +## Changesets + +A change to `skills/`, `tokens/`, `assets/`, `templates/`, `BRAND-USE.md` or the `exports` in `package.json` needs a changeset: run `pnpm changeset`. A change to the README, the LICENSE, the agent docs, `docs/` or CI needs none. + +- Major: a token, an export path or an asset path is removed or renamed. +- Minor: one is added, or a chapter. +- Patch: a value or a text changes. + +Nobody edits versions or `CHANGELOG.md` by hand. + +## Releases + +When changesets land on `main`, `vland-bot` opens or updates a "chore: update versions" pull request. A maintainer merges it, and that publishes `@variablelab/brand` to npm through trusted publishing. + +Agents install the skill from `main` on GitHub, not from npm, so a change to `skills/` reaches them when it merges, before any release. diff --git a/docs/development.md b/docs/development.md new file mode 100644 index 0000000..8658bdd --- /dev/null +++ b/docs/development.md @@ -0,0 +1,48 @@ +# Development + +How to work on the brand repository in a clone. The [contributing guide](contributing.md) covers how a change gets in. + +## Layout + +- `skills/vlab-brand/`: the guideline, as an Agent Skill. `SKILL.md` routes each task to a chapter, and `glossary.md` holds the terms. +- `tokens/tokens.json`: the only source of colors, fonts and the type scale. +- `assets/`: the Logo and the Class stamps. +- `templates/project/`: what a new Project copies: its README, its docs and its `brand/` folder. +- `scripts/build.ts`: writes every generated file. +- `.github/readme/`: the images in the README. Generated. + +## Setup + +[mise](https://mise.jdx.dev) pins Node 24 and pnpm in `mise.toml`, with checksums in `mise.lock`: + +```sh +mise install +pnpm install +``` + +After changing a version in `mise.toml`, run `mise lock` and commit both files. + +## Tasks + +```sh +pnpm build # write every generated file from its source +pnpm check # exit 1 when a generated file is out of date +``` + +## Generated files + +Edit the source, then run `pnpm build`. + +| Source | Generated | +| --- | --- | +| `tokens/tokens.json` | `tokens/tokens.css`, `tokens/theme.css`, the tables in `color.md`, the scale in `typography.md`, the palette in `README.md` with its swatches in `.github/readme/`, and `templates/project/brand/sign-readme.svg` | +| `assets/stamps/*.svg` | The stamp previews in `.github/readme/` | +| `assets/logo.svg` | `.github/readme/logo.svg`, the Logo on `ground` that READMEs link | + +Inside Markdown, a generated block sits between `` and ``. Write around the markers, never inside them. + +## CI + +- **On each pull request to `main`:** `pnpm check` (CI), and zizmor on the workflows (Workflow audit). +- **On each push to `main`:** the release job opens or updates the "chore: update versions" pull request, or publishes when that pull request merges. +- **Every Monday:** `pnpm audit`, which keeps an issue labeled `dependency-audit` open while it finds known vulnerabilities (Dependency audit). diff --git a/scripts/build.ts b/scripts/build.ts index accc570..c82389c 100644 --- a/scripts/build.ts +++ b/scripts/build.ts @@ -93,9 +93,18 @@ outputs[".github/readme/logo.svg"] = const table = (head: string[], rows: string[][]) => [head, head.map(() => "---"), ...rows].map((cells) => `| ${cells.join(" | ")} |`).join("\n"); -const swatch = (group: Group, name: string) => ``; const rows = (group: Group, render: (name: string, token: Token) => string[]) => Object.entries(tokens[group]).map(([name, token]) => render(name, token)); +// The README is also the npm page, so its images are absolute. They carry a width and no height: +// GitHub rounds an absolute image that has both. A list, not a table, so the swatches never shrink. +const readmeImage = (path: string) => `https://raw.githubusercontent.com/withvariablelab/brand/HEAD/${path}`; +const swatches = (group: Group) => + Object.entries(tokens[group]) + .map( + ([name, t]) => + `-  \`${name}\` \`${t.value}\`. ${t.use}`, + ) + .join("\n"); const blocks: Record> = { "skills/vlab-brand/color.md": { @@ -118,8 +127,8 @@ const blocks: Record> = { ), }, "README.md": { - color: table(["", "Token", "Value", "Use"], rows("color", (name, t) => [swatch("color", name), `\`${name}\``, `\`${t.value}\``, t.use])), - syntax: table(["", "Token", "Value", "Use"], rows("syntax", (name, t) => [swatch("syntax", name), `\`${name}\``, `\`${t.value}\``, t.use])), + color: swatches("color"), + syntax: swatches("syntax"), }, }; diff --git a/skills/vlab-brand/SKILL.md b/skills/vlab-brand/SKILL.md index 0bc88bc..605cb1a 100644 --- a/skills/vlab-brand/SKILL.md +++ b/skills/vlab-brand/SKILL.md @@ -20,5 +20,6 @@ Read the chapter the task touches: | Write any public text | [voice.md](voice.md) | | Use or draw a UI icon, set a shape beside text | [iconography.md](iconography.md) | | Give a Project its Sign, set up its `brand/` folder | [project-brand.md](project-brand.md) | +| Write or restructure a README, or a repository's contributing and development docs | [readme.md](readme.md) | -Beyond this folder, the brand repository (`github.com/withvariablelab/brand`, the package `@variablelab/brand`) holds the tokens (`tokens/`), the Logo and the Class stamps (`assets/`), the template for a Project's `brand/` folder (`templates/project/brand/`) and the terms of use for the marks (`BRAND-USE.md`). +Beyond this folder, the brand repository (`github.com/withvariablelab/brand`, the package `@variablelab/brand`) holds the tokens (`tokens/`), the Logo and the Class stamps (`assets/`), what a new Project copies (`templates/project/`: its README, its docs and its `brand/` folder) and the terms of use for the marks (`BRAND-USE.md`). diff --git a/skills/vlab-brand/logo.md b/skills/vlab-brand/logo.md index 267a30c..bfe4add 100644 --- a/skills/vlab-brand/logo.md +++ b/skills/vlab-brand/logo.md @@ -7,7 +7,7 @@ File: `assets/logo.svg` in the brand repository, `viewBox 0 0 402.02 468.12`. ## Use - Green, on `ground`, at its own proportions: scale it, never stretch it. -- The Signature is the Logo with "Variable Land" beside it, the Logo on the left, the name in IBM Plex Sans 500 in `ink`. The name is set as text each time; there is no wordmark file. +- The Signature is the Logo with "Variable Land" beside it, the Logo on the left, the name in IBM Plex Sans 500 in `ink`. The name is set as text each time; there is no wordmark file. In a README, the name takes the site's font and link color, because a README can't set either ([readme.md](readme.md)). - Smallest size: 16px wide (16×18). ## Avoid @@ -20,3 +20,5 @@ File: `assets/logo.svg` in the brand repository, `viewBox 0 0 402.02 468.12`. ## Linking it From outside the brand repository, link a pinned version so it never changes under a page: `https://cdn.jsdelivr.net/npm/@variablelab/brand@/assets/logo.svg`. jsDelivr caches a pinned version for good and a range for days. + +In a README, link the Logo on a `ground` square, the one the brand repository's README uses, pinned to a tag: `https://cdn.jsdelivr.net/gh/withvariablelab/brand@v0.3.1/.github/readme/logo.svg`. `assets/logo.svg` has no background, and GitHub's light theme would show it on white. When the Logo changes, the tag changes in every README in the same pass. [readme.md](readme.md) has the Signature's markup. diff --git a/skills/vlab-brand/project-brand.md b/skills/vlab-brand/project-brand.md index cfb9c55..1aa1fe5 100644 --- a/skills/vlab-brand/project-brand.md +++ b/skills/vlab-brand/project-brand.md @@ -40,3 +40,5 @@ https://raw.githubusercontent.com/withvariablelab//HEAD//bran ``` npm rewrites a relative image path to this same URL, and GitHub resolves a relative path against the branch. Writing it absolute keeps both explicit. + +Give the `` a `width` and no `height`: with both on an absolute URL, GitHub rounds the corners and puts a gray background behind the Sign. The Sign heads the README at 64px, above the Project's name, which links to the Project's page. [readme.md](readme.md) has the header's markup. diff --git a/skills/vlab-brand/readme.md b/skills/vlab-brand/readme.md new file mode 100644 index 0000000..8ef9010 --- /dev/null +++ b/skills/vlab-brand/readme.md @@ -0,0 +1,205 @@ +# README + +How a README is built in every Variable Lab repository, and the two docs beside it: `docs/contributing.md` and `docs/development.md`. + +## Where a README is read + +- GitHub shows the README at the root of a repository, and the README of a folder when someone opens that folder. +- npm shows a package's README on its page. The page changes only when a new version is published. + +A Project inside a monorepo is read in both places, from one file: its package README. + +## Rules for every README + +### Voice and names + +[voice.md](voice.md) applies. Titles are in sentence case. A scoped package name goes in backticks, so no title holds one: in a title, GitHub shows the backticks as a gray block the size of the title. + +### Sections + +These names, in this order where they appear: `Install`, `Usage`, `Documentation`, `Contributing`, `License`. Never `Installation`, `Prerequisites` or `Development`. + +### No badges + +npm shows the version, GitHub shows CI on every commit, and open source is never a badge ([principles.md](principles.md)). + +### Images + +An `` takes a `width` and no `height`. With both, on an absolute URL, GitHub rounds its corners and puts a gray background behind it. An SVG keeps its proportions from its `viewBox`. + +### Links + +- In a README that npm shows, every link and image is absolute. npm rewrites relative links from `repository` and `repository.directory` in `package.json`, and one missing field breaks them. +- In a README that only GitHub shows, links are relative, so they follow the branch. +- Anchors, such as `#install`, stay relative everywhere. + +### Tables + +When a table is wider than the page, GitHub narrows its columns. A sentence wraps, but an image shrinks and a hyphenated name breaks at the hyphen: `my-project/` becomes `my-` over `project/`. A README can't prevent it. + +- A table may hold sentences when no other cell holds an image or a hyphenated name. +- A table with images or hyphenated names holds only short cells: a name, a command, a value. +- When it needs both, it is a list. + +### The Signature + +Every README at the root of a repository or on an npm page ends with the Signature, centered and apart from the Sign: + +```html +

+  Variable Land +

+``` + +- The image is the Logo on a `ground` square, the one the brand repository's README uses, pinned to a tag. jsDelivr keeps a pinned tag for good. When the Logo changes, the tag changes in every README in the same pass. +- At 24px, the square holds the Logo at about 16×18, the smallest size in [logo.md](logo.md). +- `alt=""`, because the link text already says Variable Land. +- The name takes the site's font and link color, not IBM Plex Sans 500 in `ink`. GitHub and npm strip `style`, so a README can't set either. +- A folder README in a repository that isn't a package, such as a GitHub Action's, has no Signature. + +### License + +A `## License` section, in one of two forms: + +- A Project: ``The code is [MIT](). The Sign in `brand/` is not: its use is set by [BRAND-USE.md](https://github.com/withvariablelab/brand/blob/main/BRAND-USE.md).`` +- Anything else: `[MIT]().` + +The link goes to the `LICENSE` at the repository root. The README never names the holder: the `LICENSE` does. Each published package in a monorepo keeps a copy of that `LICENSE` in its folder, because npm puts only the package folder's `LICENSE` in the tarball. + +### Contributing + +A README at the root of a repository has a `## Contributing` section that links the two docs: + +```markdown +## Contributing + +The [contributing guide](docs/contributing.md) covers issues, pull requests and releases, and the [development guide](docs/development.md) covers setting up the repo and running its checks. +``` + +In a repository that doesn't publish, the first part ends at "issues and pull requests". A package README has no `## Contributing`: the docs belong to the repository. + +## The header of a Project + +```html +

+ +

+ +

+ +

+``` + +- The Sign at 64px, linked as [project-brand.md](project-brand.md) says. +- The name, linked to the Project's page at `https://lab.variable.land/`. It takes the site's link color, like the name in the Signature. +- The tagline, word for word as on the Project's page. + +## The structures + +### A Project in its own repository + +Read on GitHub and on npm, from one file. + +1. The header. +2. An opening of one to three sentences: what it does and how, in the words its code uses. It doesn't repeat the tagline. A short list of behaviors may follow. +3. `## Install`: the install command from the Project's page, word for word, and the requirement in one sentence, taken from `engines` or the peers in `package.json`. Then anything to install beside it. +4. `## Usage`: the smallest example that runs as written. If the Project has a `CLI.md`, Usage links it as "CLI reference". +5. The Project's own sections, such as Styling or Troubleshooting. +6. `## Documentation`, when the Project has docs. +7. `## Contributing`. +8. `## License`, in the Project form. +9. The Signature. + +### A Project's package inside a monorepo + +Read on npm and in its folder on GitHub. The same as a Project in its own repository, without `## Contributing`. + +### The root of a monorepo that is one Project + +Read only on GitHub. It carries the Project's header and links the package README instead of repeating it. + +1. The header, the same as the package's. +2. One sentence: what the repository holds. +3. The install command, and a sentence that sends Usage to the package README and the rest to the docs. +4. `## Repository`: a list of the folders and what each holds. +5. `## Contributing`. +6. `## License`, in the Project form. +7. The Signature. + +### The root of a monorepo with several Projects + +Read only on GitHub. The monorepo isn't a Project: it has no Sign and no tagline, and its title sits on the left. + +1. `# `, and the repository's GitHub description as its first sentence. +2. `## Projects`: one item per Project, with its Sign at 24px, its name linked to its README, its tagline and its page. +3. `## Repository`: a list of folders, not of packages, so adding a package doesn't change the root. +4. `## Contributing`. +5. `## License`. +6. The Signature. + +### A package that isn't a Project + +A plugin, a preset or an internal package, read on npm and in its folder on GitHub. It has no Sign. + +1. `# `, the name of its folder. The first sentence names the package in backticks and the Project it belongs to, linked to that Project's README. Then what it adds. +2. `## Install`: the command, what it does and what it needs. +3. What it provides: a table of capabilities and commands, or its presets. +4. `## Usage` or `## Configuration`. +5. Its own sections. +6. `## Removal`, when installing it changed files. +7. `## License`: `[MIT]().` +8. The Signature. + +An internal package says so in its opening: it is published because the Projects that use it depend on it, and it isn't meant for use outside them. + +### A Variable Lab repository + +The repositories of the guideline, the site and the shared GitHub Actions. + +1. `# `, and the repository's GitHub description as its first sentence. The brand repository opens with the Logo instead, because the Logo is its subject. +2. What the repository offers to whoever uses it. +3. `## Contributing`. +4. `## License`. +5. The Signature. + +What matters only to whoever works in the repository goes to `docs/development.md`. A folder README inside it, such as a GitHub Action's, takes the folder's name as its title, the name used in `uses:`, and has no License or Signature. + +## What is copied and what is linked + +- Copied word for word from the Project's page: the tagline and the install command. +- Taken from `package.json`: the requirement. +- Linked, never copied: the docs, the CLI reference, the Project's page and the license. +- A list that grows, such as a monorepo's plugins or examples, lives in one README. The others link it, and no doc counts its items. +- The Project's page takes its text from the README's opening and its example from Usage. The README never copies them back. + +## docs/contributing.md and docs/development.md + +Every repository has both, in `docs/`, in lowercase. GitHub takes `docs/contributing.md` as the repository's contributing guide and links it when someone opens an issue or a pull request. A monorepo has one pair for the whole repository, and its packages have none. + +### docs/contributing.md + +How a change gets in, for whoever proposes one. + +1. `# Contributing`: what the repository takes, and a link to `development.md`. +2. `## Issues`: what a bug report includes, and that a new feature or an API change starts as an issue. +3. `## Pull requests`: the branch prefixes, Conventional Commits, the pull request title as the squash commit, the checks to run, green CI and who merges. Preview releases, where the repository has them. +4. `## Changesets`, in a repository that publishes: when a change needs one, which bump, and that nobody edits versions or `CHANGELOG.md` by hand. +5. `## Releases`, in a repository that publishes: the "chore: update versions" pull request, and what merging it publishes. +6. The repository's own sections. + +### docs/development.md + +How to work in a clone, for a person or an agent. + +1. `# Development`: one sentence, and a link to `contributing.md`. +2. `## Layout`, in a repository with more than one part: the folders and what each holds. +3. `## Setup`: what mise pins, and how to install everything the first time. +4. `## Tasks`: the everyday commands: dev, check, test and build. +5. `## CI`: what runs on a pull request, and what the git hooks run. +6. The repository's own sections, such as generated files, deploys or troubleshooting. + +Each section comes from the repository's own files: `mise.toml`, `package.json`, the workflows and `lefthook.yml`. Both docs are read only on GitHub, so their links are relative. + +## Starting a Project + +The brand repository's `templates/project/` holds what a new Project copies: `README.md`, `docs/contributing.md`, `docs/development.md` and the `brand/` folder. diff --git a/templates/project/README.md b/templates/project/README.md new file mode 100644 index 0000000..83b3803 --- /dev/null +++ b/templates/project/README.md @@ -0,0 +1,39 @@ + + +

+ +

+ +

+ +

+ + + +## Install + +```sh + +``` + +It needs . + +## Usage + + + +## Documentation + + + +## Contributing + +The [contributing guide](https://github.com/withvariablelab//blob/main/docs/contributing.md) covers issues, pull requests and releases, and the [development guide](https://github.com/withvariablelab//blob/main/docs/development.md) covers setting up the repo and running its checks. + +## License + +The code is [MIT](https://github.com/withvariablelab//blob/main/LICENSE). The Sign in `brand/` is not: its use is set by [BRAND-USE.md](https://github.com/withvariablelab/brand/blob/main/BRAND-USE.md). + +

+  Variable Land +

diff --git a/templates/project/docs/contributing.md b/templates/project/docs/contributing.md new file mode 100644 index 0000000..17a4cff --- /dev/null +++ b/templates/project/docs/contributing.md @@ -0,0 +1,19 @@ +# Contributing + + takes . To set up the repo and run its checks, see the [development guide](development.md). + +## Issues + + + +## Pull requests + + + +## Changesets + + + +## Releases + + diff --git a/templates/project/docs/development.md b/templates/project/docs/development.md new file mode 100644 index 0000000..6639acf --- /dev/null +++ b/templates/project/docs/development.md @@ -0,0 +1,15 @@ +# Development + +How to work on in a clone. The [contributing guide](contributing.md) covers how a change gets in. + +## Setup + + + +## Tasks + + + +## CI + +