The files of a project
A project is a repository with a .skein/ directory at its root. This page describes the files in it that skein reads so far. All of them are TOML; one file declares one thing, and a file’s name is the name of what it declares. A name is lowercase letters, digits, - and _, starting with a letter. A key that skein does not know is reported, so a misspelled key is never ignored in silence.
skein check reads all of this and reports every mistake with its file.
.skein/config.toml
[project]
name = "example"
# Markdown documents whose paragraphs can be items
[[sources]]
path = "docs/spec"
# Markdown files that are one item each
[[sources]]
path = "docs/requirements"
kind = "items"
type = "srs"
| Key | Meaning |
|---|---|
project.name |
The project’s name, for reports. |
sources |
The places that hold items. |
sources.path |
A directory, from the project’s root, with forward slashes. |
sources.kind |
"documents" (the default) or "items". |
sources.type |
For "items": the item type of a file that names none. |
citations |
The places whose files cite items in comments. |
citations.name |
What the citations are: "test", "code". Coverage counts by this name. |
citations.path |
A directory, from the project’s root; "." for all of it. |
citations.files |
The ends of the names of the files to read: [".zig"], ["_test.c"]. |
citations.marker |
The text that comes before the IDs on a line: "// spec:". |
citations.to |
The item types the citations may name; leave out for any. |
citations.expected |
Every item of a to type should be cited by the set; coverage counts the ones that are not. |
[[citations]]
name = "test"
path = "tests"
files = [".zig"]
marker = "// spec:"
to = ["rule"]
Directories whose names start with a dot, and zig-out, zig-pkg and node_modules, are never read.
.skein/types/<name>.toml: an item type
description = "A software requirement"
id = "numbered"
prefix = "SRS"
digits = 3
categories = ["functional", "performance"]
statuses = ["draft", "approved", "deprecated", "removed"]
tombstone = "removed"
verification = ["test", "analysis", "inspection", "demonstration"]
[attributes.priority]
type = "string"
values = ["low", "medium", "high"]
required = true
[attributes.rationale]
normative = false
| Key | Meaning |
|---|---|
description |
What the type is for. |
id |
"hierarchical" (the default): IDs like lex.comment.line. "numbered": IDs like SRS-012, with prefix and at least digits digits (default 3). |
separator |
For numbered IDs: what stands between the prefix and the number. Default "-"; may be empty (REQ001). |
names |
For numbered IDs: true allows a name in the number’s place (SRS-PURPOSE). |
categories |
The categories an item of the type is one of; leave out for none. |
statuses |
The lifecycle. Default: draft, approved, deprecated, removed. |
tombstone |
The status of a removed item, whose ID stays taken. Default "removed", when the statuses have it. |
verification |
The verification methods an item of the type may name. |
approval |
The statuses an item may have only while it is approved as it is: see reviewing. |
attributes.<name>.type |
"string" (the default), "integer", "boolean" or "date". |
attributes.<name>.values |
The values a string attribute may take. |
attributes.<name>.required |
Whether every item of the type must have it. |
attributes.<name>.normative |
Whether a change to it changes the item’s fingerprint. |
An empty file is a valid type: hierarchical IDs, no categories, the default statuses, no attributes.
.skein/links/<name>.toml: a link type
description = "A test verifies a rule"
from = ["test"]
to = ["rule"]
expected = true
| Key | Meaning |
|---|---|
description |
What the link means. |
from |
The item types a link of this kind may start at; leave out for any. |
to |
The item types it may point to; leave out for any. |
required |
Every item of a from type must have one. |
expected |
Every item of a to type should be pointed to by one; coverage counts the ones that are not. |
review |
Links of this type are reviewed: see reviewing. |
.skein/profiles/<name>.toml: a profile
A profile is a named selection of items. An item is in it when it passes every condition given.
description = "What the first stage of the language defines"
types = ["rule"]
statuses = ["approved"]
[where]
stage = "s0"
| Key | Meaning |
|---|---|
description |
What the profile selects. |
types |
Item types; leave out for any. |
categories |
Categories; leave out for any. |
statuses |
Statuses; leave out for any. |
where.<attribute> |
A value, or an array of values, the attribute must have one of. |