[REQ-toml]
text = '''
artifact files like this one are written in the TOML format
you can read more about it here: https://github.com/toml-lang/toml
All artifact files must end in ".toml"
Artifact names must be composed of the set "a-zA-Z_-" and spaces
and case are ignored. The `.` character is not allowed.
'''
[REQ-learn-artifact]
text = '''
Artifacts are defined by specifying their name like so: "[REQ-NAME]"
Artifacts can be a requirement (REQ), design-specification (SPC)
risk (RSK) or test (TST)
This particular artifact is a requirement, therefore it begins with
"REQ". After REQ there is a "-" and then the name of the requirement.
Unlike many requirements tracking tools, artifact encourages the use
of human-readable names. We will talk more about this later.
'''
[SPC-learn-spc]
partof = "REQ-toml"
text = '''
Anything starting with SPC is a design specification. Requirements (REQ)
should be used for detailing "what you want your application to do" and
design specifications (SPC) should be used for detailing "how your application
will do it".
There are also tests (TST) and risks (RSK) which we will learn about later.
'''
[REQ-learn-partof]
text = "see the next artifact"
[SPC-learn-partof]
text = '''
artifact uses the names of artifacts to automatically link them and track
progress. This makes it easy for the user to intuitively link together
requirements with their specification and reduces boilerplate.
REQ-learn-partof is automatically a "partof" this artifact because the names
after the type are the same ("learn-partof")
In addition, missing parents are automatically created and linked. So
SPC-LEARN is also a partof this artifact, even though it is not even in this
document. This makes it very easy to make trees of artifacts without needing to
specify every branch.
So far we have:
```
--- SPC-LEARN <--- SPC-learn-spc
/
REQ <-- REQ-LEARN <-- REQ-learn-partof <-- SPC-learn-partof
^ |
\-------- REQ-learn-artifact <-----/
* items in ALL CAPS were created automatically
```
> Note: only parents are created automatically. Auto-creating for similar-named
> artifacts would pollute your links
>
> Note: RSK artifacts are never automatically linked by name (only their parents
> are automatically created and linked)
'''
[SPC-learn-example]
text = "this is used in the next artifact"
[TST-learn-partof]
partof = "SPC-learn-[spc, example]"
text = '''
The partof field is a string that uses a simple grouping syntax. This example
does as you would expect, this artifact is a partof SPC-learn-spc and
SPC-learn-example
Note: it is also automatically a partof SPC-learn-partof and TST-LEARN because
of the name
'''
[SPC-learn-valid]
text = '''
There are only a few rules for defining artifacts:
- case is ignored for all names
- names cannot overlap, even in different files
- all names must start with either REQ, RSK, SPC or TST
- artifact names must follow SPC-learn-links (see bellow)
'''
[SPC-learn-links]
partof = "SPC-learn-partof"
text = '''
There are some rules for which artifacts can be a partof other artifacts:
- all artifacts can be a partof their own group (i.e. SPC can be a partof SPC)
- SPC and RSK can be a partof REQ
- TST can be a partof SPC and RSK
- REQ can only be a partof itself
Here is a helpful graph of valid relations:
```
REQ <-- SPC <-- TST
^ |
\---- RSK <-----/
```
In other words, you can design a spec (SPC) based on a requirement (REQ). A
requirement can also have a risk (RSK) associated with it. Tests can test to
either a spec (SPC) or to a risk (RSK)
'''
[SPC-learn-rsk]
text = '''
the RSK type allows you to specify risks associated with your requirements
(RSK can be partof REQ).
Frequently (for larger projects especially) it is a good idea to do risk
analysis on which areas defined by your requirements ation are most likely to
fail and which would be the most catastrophic. RSK artifacts allow you to
document these and design test cases based on them.
'''
[SPC-learn-tst]
text = '''
TST is used to document test design and is the only way that an artifact can be
considered "tested".
'''
[SPC-learn-ls]
text = '''
The `ls` command is the most important command to learn in artifact, as it helps
you manage the artifacts in your project, see how they are linked, and view how
completed/tested they are.
Type:
art ls SPC-learn-ls -l
This will show you this artifact, pretty printed on your terminal.
Try:
art ls learn -p
This searches in the "Name" field for all artifacts that have "learn"
in their name.
Let's say you wanted to find an artifact, and all you knew was that it mentioned
files in it's text field. You could run:
art ls file -p T -T
This will search for the pattern "file" in the text field (`-p T`). It will also
display a short piece of the text field (`-T`)
Now let's say that You see that SPC-learn-valid is what you were looking for,
but you want an expanded view:
art ls SPC-learn-valid -l
Now you see that SPC-learn-valid has not been tested or implemented and that it
is partof SPC-LEARN. From there you could decide what to do.
'''