Ask a new issue for the problem, the evidence and what done means

[iderex]

The issue this belongs to

Refs #107. It does not close it, and what is left is under "What this does not
cover" below.

What changed

Two Markdown issue templates and the configuration file beside them:
.github/ISSUE_TEMPLATE/problem.md, .github/ISSUE_TEMPLATE/decision.md and
.github/ISSUE_TEMPLATE/config.yml.

Both templates ask for the three things an issue on this board states: what is
wrong, what the evidence is, and what done means. Where the evidence is a number
they ask for the command that produced it, which is the request
.github/pull_request_template.md already makes of a pull request and for the
same reason. Both open by saying that nothing reads them.

The means is Markdown with a YAML front matter block, and it is forced rather
than chosen. GitHub decides what an issue template is and where it lives, and
this is the smallest shape that reaches the chooser. It adds no language, no
runtime and no dependency this tree does not already carry, since the tree is
already Markdown and YAML. The one place a choice was genuinely available is the
next paragraph.

Markdown rather than a YAML issue form. A form marks fields required and refuses
to submit without them, so a form carrying the sentence "nothing reads this"
would be contradicted by the thing it is written on. config.yml is part of the
same choice: it keeps the blank issue available, so that a template is something
a person can walk past rather than the only route in. It declares no contact
link, because a link there publishes a route to a person, and which address this
repository publishes is entry 5 of #1.

Two templates rather than one. A decision needs the options with what each costs
and what the answer forecloses, and a report of something wrong does not. They
share the request for evidence and nothing else, and the decision template points
at docs/decisions/0001-decision-records.md for the shape of a record instead of
restating it.

The problem template carries a fourth heading, "What this waits on", which is
beyond the three the issue asks for. It is there because almost every issue on
this board ends with a sentence naming what it is blocked on, and a template
without it produces issues that do not look like the board they land on. It is
marked as one to delete where nothing is waiting.

What failure it prevents

The issue nobody can act on. A sentence saying something is wrong, with no
command behind the number in it and no condition under which it closes, cannot be
worked and cannot be refused either, because there is nothing to check a change
against. That shape is what arrives when the only guidance available is other
people's issues, which is what somebody opening their first issue here has today.

It also prevents the opposite mistake, which is the more expensive one. A
template that looks like enforcement teaches a reader that a filled-in form has
been checked. Nothing here checks one, and each template says so in its first
paragraph rather than leaving it to be inferred.

Evidence

What this branch changes, against the reference a reader will have:

$ git diff --name-only origin/main...HEAD
.github/ISSUE_TEMPLATE/config.yml
.github/ISSUE_TEMPLATE/decision.md
.github/ISSUE_TEMPLATE/problem.md

The document check in this tree runs its own fixtures and then judges every
tracked Markdown file, so the two new templates are inside what it read. It
passes at this commit, and the document count moved by the two files added:

$ bash .github/doc-paths/doc-paths.sh check | grep -E '^ok    [0-9]+ document'
ok    44 document(s), 48 named path(s) resolved, 0 excused as examples
$ git ls-tree -r --name-only origin/main | grep -c '\.md$'
42
$ git ls-files '*.md' | grep -c '\.md$'
44

There is no .gitattributes in this tree yet and #99 is where that is answered,
so the bytes are stated rather than assumed. All three files are stored with line
feeds in the index, and none of them carries a carriage return or a byte outside
ASCII:

$ git ls-files --eol .github/ISSUE_TEMPLATE
i/lf    w/lf    attr/                 .github/ISSUE_TEMPLATE/config.yml
i/lf    w/lf    attr/                 .github/ISSUE_TEMPLATE/decision.md
i/lf    w/lf    attr/                 .github/ISSUE_TEMPLATE/problem.md
$ for f in .github/ISSUE_TEMPLATE/*; do printf '%s ' "$f"; git cat-file blob ":$f" | LC_ALL=C grep -c -P '[^\x00-\x7F]|\r'; done
.github/ISSUE_TEMPLATE/config.yml 0
.github/ISSUE_TEMPLATE/decision.md 0
.github/ISSUE_TEMPLATE/problem.md 0

The front matter and the configuration file parse as YAML, read by a parser that
is not in this repository:

$ python -c "import yaml;print(yaml.safe_load(open('.github/ISSUE_TEMPLATE/config.yml')))"
{'blank_issues_enabled': True}
$ python -c "import yaml;print(yaml.safe_load(open('.github/ISSUE_TEMPLATE/problem.md').read().split('---')[1]))"
{'name': 'Something here is wrong', 'about': 'A defect, a gap, or a rule with nothing behind it', 'title': '', 'labels': '', 'assignees': ''}
$ python -c "import yaml;print(yaml.safe_load(open('.github/ISSUE_TEMPLATE/decision.md').read().split('---')[1]))"
{'name': 'Something here has to be decided', 'about': 'A question this repository has to answer before code depends on the answer', 'title': '', 'labels': '', 'assignees': ''}

That says the YAML is well formed. It does not say GitHub accepts it, which is a
different question and is under "What this does not cover".

The condition #107 states is a command that reads the repository rather than a
branch, so it cannot answer differently until this is merged. At this commit it
still reports both rows that issue holds as missing:

$ gh api repos/Flowfin/core/community/profile --jq '.files | to_entries[] | "\(.key)\t\(if .value == null then "missing" else "present" end)"'
code_of_conduct missing
code_of_conduct_file missing
contributing missing
issue_template missing
license missing
pull_request_template present
readme present

What this does not cover

#107 is not closed, and one of its conditions cannot be met on this board at all
yet. The code of conduct is not here. A code of conduct with no reporting address
is a document that is useless at exactly the moment somebody needs it, and which
address this repository publishes is entry 5 of #1. That entry has no answer
written into it.

Nothing here was run through GitHub. The templates have not been rendered by the
issue chooser and no issue has been opened with one, so whether GitHub accepts
this front matter is unverified. The YAML above is a local parser agreeing that
the syntax is valid, which is a weaker statement. The issue_template row in the
command above is what settles it, and it can only be re-run after the merge.

No template sets a default label or a default assignee. Both fields are present
and empty. A default label would be wrong on most issues, because the labels on
this board are topical rather than a single kind, and a default assignee would
route a stranger's issue to somebody who has not agreed to it. The cost is that
an issue opened from a template starts with neither, and whoever triages it adds
both.

No guard was added, so there is nothing here to prove bites. These are prompts,
and a check that refuses an issue for saying nothing does not exist on this
board.

The scope comparison in the pull-request hygiene check will report NOT MADE
against this change, because #107 declares no Scope: line at column zero. The
changed paths were compared against nothing, and the three paths listed under
Evidence are what a reader has instead.

Who has read it

Nobody other than the author has read this change. The evidence above stands in
place of a review rather than the question being left open.