Everything in this plan that is an engineering judgement has been decided in its
own issue, with its reasons and its rejected alternatives. What is left is the set
of questions that are not engineering judgements. They are collected here, in one
place, because a question scattered across five issues gets answered five times or
not at all.
Nothing below is decided. Each entry states the question, the options as they
actually stand, and what each option costs. Answer them in a comment or by editing
this body, and each answer then becomes a decision record in docs/decisions/ under
its own issue.
1. The licence of this repository.
This is the first entry because more of the plan waits on it than on anything else.
The repository has no licence file today, which is not a neutral state: without
one, default copyright applies, nobody has permission to reuse anything here, and
the sign-off gate is asking contributors to certify their right to contribute under
terms that do not exist. Every day it stays open, contributions arrive with no
inbound terms.
The options and what each costs.
GPL-3.0, which is what every plugin board in this organisation carries today. That
population moves, so derive it rather than trusting a number written here:
gh repo list Flowfin --limit 100 --json name --jq '.[].name' | while read -r r; do
printf '%s %s\n' "$r" "$(gh api "repos/Flowfin/$r" --jq '.license.spdx_id // "none"')"
done
Code moving from an experiment into one of those plugins needs no relicensing,
which is the common direction and the one the hand-over path was designed around.
The cost is the other direction: a result that would be useful to a permissively
licensed project cannot go there, and an experiment that wants to borrow
permissively licensed code and give something back is constrained.
Apache-2.0. Permissive, with an explicit patent grant, which matters more than it
looks for work touching authentication and media handling. Results can move into a
GPL plugin and also anywhere else. The cost is that the flow only runs one way:
code borrowed from a GPL plugin cannot come back into an Apache experiment without
the experiment becoming GPL, and some experiments will want to start from existing
plugin code.
MIT. The same permissive shape as Apache-2.0, shorter, widely understood, and with
no patent grant. The cost is exactly that missing grant.
CC0 or a public-domain dedication. No attribution obligation at all, which suits
throwaway prototypes. The cost is that some organisations will not accept
public-domain-dedicated code because the dedication is not effective in every
jurisdiction, so it can block the promotion path it was chosen to simplify.
Leaving it unlicensed. The cost is stated above and it grows rather than holding
steady.
The related question, which may have a different answer: whether the experiment
content and the runner carry the same licence. They have different audiences, since
the runner is downloaded and run while the experiments are read and copied from.
Issue #47 already exists to land the file once this entry is answered, and it is
blocked on this issue rather than guessing. Two other Done-whens in the plan point at
that file, so answering this entry unblocks a chain that reaches the first release.
2. Whether an experiment may bring in code under a licence the answer to entry 1
does not match, and how that is declared.
Experiments will want to start from something that exists. The question is whether
that is allowed, and if so what the record has to say about it.
Allowing it, with a declaration in the experiment record naming the source and its
licence, keeps the board useful for the questions that begin with existing code.
The cost is that a permissive repository then contains directories that are not
permissive, and somebody promoting one later has to notice. That is a footgun placed
at the exact moment when people are least careful.
Forbidding it keeps the tree uniform and the promotion path simple. The cost is
that a real class of question becomes unaskable here.
Allowing it only in a quarantined directory with its own licence file is the middle
option. The cost is a layout rule that has to be taught and a check that has to be
maintained.
3. Whether a result may be promoted into a board with a different licence, and
who may agree that on a contributor's behalf.
The plan has a hand-over path. If the receiving board is under different terms from
this one, somebody has to be entitled to place the contributor's work under those
terms. The sign-off gate already asks contributors to certify their right to
contribute under this project's licence, and that certification says nothing about a
different licence elsewhere.
The options run from taking only work you authored yourself, through asking
contributors for explicit permission at promotion time, to a contributor agreement
covering it in advance. The costs run in the opposite order: the first limits what
the board can hand over, the second creates a step that will sometimes be skipped
under time pressure, and the third puts a legal document in front of somebody who
wanted to try an idea, which is a real deterrent on a board whose whole purpose is
lowering the cost of trying.
4. Whether this board publishes downloadable release artefacts at all.
The scope this board opened with excludes anything a user is asked to install. The
plan also reaches a first release an operator can run, and those two are in tension
even though they are not in contradiction: the operator here is somebody checking
this repository, not somebody using a media server.
Publishing binaries makes the tool usable by somebody who has no toolchain, which is
most people who might want to check this board's claims for themselves. The cost is
a published artefact, which brings signing, checksums, a bill of materials, a
vulnerability surface and an expectation of continuity, and it is exactly the shape
the scope exclusion was written to avoid.
Publishing source only, with the tool run from a checkout, has none of those costs
and requires the toolchain. It also weakens the independent-verification argument,
since somebody who has to build the tool from the repository they are checking is in
a weaker position than somebody who downloads it.
A middle option is publishing artefacts while stating in the release notes that they
are for checking this board and are not part of what the organisation ships to
users. The cost of the middle option is that it depends on people reading the
sentence.
If the answer is to publish, a second question follows: whether the artefacts are
signed, and with what. Signing costs key custody and a rotation story. Not signing
means a checksum published next to the file it checksums, which proves the download
arrived intact and nothing about who built it.
5. Whether an experiment on this board may touch real personal data at all.
The plan proposes a rule: real data stays on the host, never enters the tree, and
the record carries only the measurement. That rule is written as a proposal because
the decision underneath it is not an engineering one.
Allowing it under that rule keeps the honest questions answerable, because some
things only behave realistically at real scale with real messiness. The cost is that
the rule depends on a person following it, on a public board where a mistake is
public and permanent, and git history does not forget.
Forbidding it and requiring synthetic fixtures for everything makes the mistake
impossible. The cost is that some questions get answers that are true of synthetic
data and not of anything else, which is a worse failure than not asking, because it
looks like a result.
A third option is allowing it only where the data belongs to the person running the
experiment and only for measurements agreed in the record before the work starts.
The cost is that it needs a reviewer to hold the line at the moment when the work is
most interesting.
6. How long a held-back record waits when the fix never arrives.
Issue #51 decides that an experiment which finds a flaw in shipped software does
not start here in public, and that the record is written once the flaw is fixed and
the affected project has said what it wants said. It deliberately does not say what
happens when neither of those arrives. That is a judgement about how this board
treats a project that has gone quiet, and it is not an engineering answer.
Waiting indefinitely is safest for the people running the affected software and it
hands the schedule to whoever is slowest to reply. The cost is a board carrying an
unwritten record nobody outside knows exists, which is the invisible half-finished
state this board was opened to make impossible.
A fixed window, counted from the report and published in the security policy, gives
both sides a date and is what most projects do. The cost is that a date chosen in
advance is sometimes wrong for the flaw in front of it, and publishing on schedule
against a flaw that is still live in software this organisation ships is a thing to
choose deliberately rather than arrive at by default.
A window with one written extension is the middle option. The cost is that it needs
somebody to answer the request inside the window, which is the failure the window
exists to handle in the first place.
Whatever the answer, it has to say what the record looks like while it waits. An
experiment held back is either sitting in asking with a question that says
nothing, or not existing at all, and those are different lines in lab list.
Leaving it unstated means the listing quietly misreports what is running, which is
the one thing that listing exists to prevent.
7. Whether a commit on the default branch has to carry a verified signature.
Neither this board nor the board the parity work targets requires one today, so
parity settles nothing here. The ruleset walk in issue #55 points at this entry
instead of deciding it.
Requiring one separates two claims that are otherwise collapsed. That an account
pushed a commit and that a key signed it are different statements, and only the
second survives somebody else holding the account. The costs are real and they
arrive later than the decision does. A key has to be held somewhere and rotated
eventually. An unsigned commit anywhere in a branch's history refuses the merge
rather than refusing the commit, so the repair is rebuilding the branch rather
than adding one more commit to it, and it lands at the end of the work rather
than at the start. Edits made through the web interface and anything an
automation authors are signed by the platform's key or not at all, which decides
what those routes can still be used for.
Not requiring one costs nothing to operate and rests authorship on the account.
The cost is exactly that it rests on the account, which is one credential and one
recovery route away from being somebody else's.
A middle option is requiring it from the first release onward, on the reasoning
that a signature matters most where somebody downloads something built from this
tree. The cost is that a history already carrying unsigned commits does not
become signed afterwards, so the rule covers what comes after the day it is set
whatever was intended by setting it.
Whichever way this goes, it meets entry four. Signing a release artefact and
signing a commit both need a key that is held somewhere and rotated eventually,
so answering the two together costs less than answering either alone and avoids
one key custody story being written twice with different answers.
8. Whether this board takes experiments from anybody, or only from the people
who keep it.
The plan assumes contributors from outside throughout and never decides that they
are wanted. A sign-off gate asks somebody to certify their right to contribute. An
issue template invites a proposal. The contributing guide is written for a person
arriving with an idea. Entry three above asks who may place a contributor's work
under another board's terms, which only becomes a question once there are
contributors. None of that settles the question, and the answer changes what all
four of them say.
Taking them is what a public board usually means, and it is the only way this one
becomes useful to anybody who is not already here. The cost is not review effort,
which is ordinary. It is that three rules in this plan depend on a person having
read them before they start: what may never be committed, what happens when an
experiment finds a flaw in shipped software, and what an experiment may do with
real data. Somebody arriving for the first time is exactly the person least likely
to have read any of them, and the first two are the ones where a mistake is public
and permanent. Nothing here can refuse those violations, which is stated plainly in
the issues that hold them, so the residual sits on whoever reads the change.
Taking none, and saying so, costs the board its reach and buys a much smaller
surface. The cost is that the guide, the templates and the sign-off gate are then
written for an audience that does not exist, and a repository that reads as open
while accepting nothing wastes the time of whoever believes it.
A middle option is taking proposals as issues rather than as changes, so a
question is discussed before anybody writes code against it. The cost is that it
turns the cheapest thing this board offers, which is trying something, into a
request that somebody has to answer.
Whatever the answer, the contributing guide has to carry it in the first
paragraph, because the alternative is somebody finding out after doing the work.
Issue #9 writes that guide and waits on this entry rather than guessing, and the
templates in issue #48 follow the same answer.
Done when every entry above carries an answer, each answer has an issue opened for
the decision record that writes it down with its reasons, and this issue is closed
with nothing left undecided.
Everything in this plan that is an engineering judgement has been decided in its
own issue, with its reasons and its rejected alternatives. What is left is the set
of questions that are not engineering judgements. They are collected here, in one
place, because a question scattered across five issues gets answered five times or
not at all.
Nothing below is decided. Each entry states the question, the options as they
actually stand, and what each option costs. Answer them in a comment or by editing
this body, and each answer then becomes a decision record in
docs/decisions/underits own issue.
1. The licence of this repository.
This is the first entry because more of the plan waits on it than on anything else.
The repository has no licence file today, which is not a neutral state: without
one, default copyright applies, nobody has permission to reuse anything here, and
the sign-off gate is asking contributors to certify their right to contribute under
terms that do not exist. Every day it stays open, contributions arrive with no
inbound terms.
The options and what each costs.
GPL-3.0, which is what every plugin board in this organisation carries today. That
population moves, so derive it rather than trusting a number written here:
Code moving from an experiment into one of those plugins needs no relicensing,
which is the common direction and the one the hand-over path was designed around.
The cost is the other direction: a result that would be useful to a permissively
licensed project cannot go there, and an experiment that wants to borrow
permissively licensed code and give something back is constrained.
Apache-2.0. Permissive, with an explicit patent grant, which matters more than it
looks for work touching authentication and media handling. Results can move into a
GPL plugin and also anywhere else. The cost is that the flow only runs one way:
code borrowed from a GPL plugin cannot come back into an Apache experiment without
the experiment becoming GPL, and some experiments will want to start from existing
plugin code.
MIT. The same permissive shape as Apache-2.0, shorter, widely understood, and with
no patent grant. The cost is exactly that missing grant.
CC0 or a public-domain dedication. No attribution obligation at all, which suits
throwaway prototypes. The cost is that some organisations will not accept
public-domain-dedicated code because the dedication is not effective in every
jurisdiction, so it can block the promotion path it was chosen to simplify.
Leaving it unlicensed. The cost is stated above and it grows rather than holding
steady.
The related question, which may have a different answer: whether the experiment
content and the runner carry the same licence. They have different audiences, since
the runner is downloaded and run while the experiments are read and copied from.
Issue #47 already exists to land the file once this entry is answered, and it is
blocked on this issue rather than guessing. Two other Done-whens in the plan point at
that file, so answering this entry unblocks a chain that reaches the first release.
2. Whether an experiment may bring in code under a licence the answer to entry 1
does not match, and how that is declared.
Experiments will want to start from something that exists. The question is whether
that is allowed, and if so what the record has to say about it.
Allowing it, with a declaration in the experiment record naming the source and its
licence, keeps the board useful for the questions that begin with existing code.
The cost is that a permissive repository then contains directories that are not
permissive, and somebody promoting one later has to notice. That is a footgun placed
at the exact moment when people are least careful.
Forbidding it keeps the tree uniform and the promotion path simple. The cost is
that a real class of question becomes unaskable here.
Allowing it only in a quarantined directory with its own licence file is the middle
option. The cost is a layout rule that has to be taught and a check that has to be
maintained.
3. Whether a result may be promoted into a board with a different licence, and
who may agree that on a contributor's behalf.
The plan has a hand-over path. If the receiving board is under different terms from
this one, somebody has to be entitled to place the contributor's work under those
terms. The sign-off gate already asks contributors to certify their right to
contribute under this project's licence, and that certification says nothing about a
different licence elsewhere.
The options run from taking only work you authored yourself, through asking
contributors for explicit permission at promotion time, to a contributor agreement
covering it in advance. The costs run in the opposite order: the first limits what
the board can hand over, the second creates a step that will sometimes be skipped
under time pressure, and the third puts a legal document in front of somebody who
wanted to try an idea, which is a real deterrent on a board whose whole purpose is
lowering the cost of trying.
4. Whether this board publishes downloadable release artefacts at all.
The scope this board opened with excludes anything a user is asked to install. The
plan also reaches a first release an operator can run, and those two are in tension
even though they are not in contradiction: the operator here is somebody checking
this repository, not somebody using a media server.
Publishing binaries makes the tool usable by somebody who has no toolchain, which is
most people who might want to check this board's claims for themselves. The cost is
a published artefact, which brings signing, checksums, a bill of materials, a
vulnerability surface and an expectation of continuity, and it is exactly the shape
the scope exclusion was written to avoid.
Publishing source only, with the tool run from a checkout, has none of those costs
and requires the toolchain. It also weakens the independent-verification argument,
since somebody who has to build the tool from the repository they are checking is in
a weaker position than somebody who downloads it.
A middle option is publishing artefacts while stating in the release notes that they
are for checking this board and are not part of what the organisation ships to
users. The cost of the middle option is that it depends on people reading the
sentence.
If the answer is to publish, a second question follows: whether the artefacts are
signed, and with what. Signing costs key custody and a rotation story. Not signing
means a checksum published next to the file it checksums, which proves the download
arrived intact and nothing about who built it.
5. Whether an experiment on this board may touch real personal data at all.
The plan proposes a rule: real data stays on the host, never enters the tree, and
the record carries only the measurement. That rule is written as a proposal because
the decision underneath it is not an engineering one.
Allowing it under that rule keeps the honest questions answerable, because some
things only behave realistically at real scale with real messiness. The cost is that
the rule depends on a person following it, on a public board where a mistake is
public and permanent, and git history does not forget.
Forbidding it and requiring synthetic fixtures for everything makes the mistake
impossible. The cost is that some questions get answers that are true of synthetic
data and not of anything else, which is a worse failure than not asking, because it
looks like a result.
A third option is allowing it only where the data belongs to the person running the
experiment and only for measurements agreed in the record before the work starts.
The cost is that it needs a reviewer to hold the line at the moment when the work is
most interesting.
6. How long a held-back record waits when the fix never arrives.
Issue #51 decides that an experiment which finds a flaw in shipped software does
not start here in public, and that the record is written once the flaw is fixed and
the affected project has said what it wants said. It deliberately does not say what
happens when neither of those arrives. That is a judgement about how this board
treats a project that has gone quiet, and it is not an engineering answer.
Waiting indefinitely is safest for the people running the affected software and it
hands the schedule to whoever is slowest to reply. The cost is a board carrying an
unwritten record nobody outside knows exists, which is the invisible half-finished
state this board was opened to make impossible.
A fixed window, counted from the report and published in the security policy, gives
both sides a date and is what most projects do. The cost is that a date chosen in
advance is sometimes wrong for the flaw in front of it, and publishing on schedule
against a flaw that is still live in software this organisation ships is a thing to
choose deliberately rather than arrive at by default.
A window with one written extension is the middle option. The cost is that it needs
somebody to answer the request inside the window, which is the failure the window
exists to handle in the first place.
Whatever the answer, it has to say what the record looks like while it waits. An
experiment held back is either sitting in
askingwith a question that saysnothing, or not existing at all, and those are different lines in
lab list.Leaving it unstated means the listing quietly misreports what is running, which is
the one thing that listing exists to prevent.
7. Whether a commit on the default branch has to carry a verified signature.
Neither this board nor the board the parity work targets requires one today, so
parity settles nothing here. The ruleset walk in issue #55 points at this entry
instead of deciding it.
Requiring one separates two claims that are otherwise collapsed. That an account
pushed a commit and that a key signed it are different statements, and only the
second survives somebody else holding the account. The costs are real and they
arrive later than the decision does. A key has to be held somewhere and rotated
eventually. An unsigned commit anywhere in a branch's history refuses the merge
rather than refusing the commit, so the repair is rebuilding the branch rather
than adding one more commit to it, and it lands at the end of the work rather
than at the start. Edits made through the web interface and anything an
automation authors are signed by the platform's key or not at all, which decides
what those routes can still be used for.
Not requiring one costs nothing to operate and rests authorship on the account.
The cost is exactly that it rests on the account, which is one credential and one
recovery route away from being somebody else's.
A middle option is requiring it from the first release onward, on the reasoning
that a signature matters most where somebody downloads something built from this
tree. The cost is that a history already carrying unsigned commits does not
become signed afterwards, so the rule covers what comes after the day it is set
whatever was intended by setting it.
Whichever way this goes, it meets entry four. Signing a release artefact and
signing a commit both need a key that is held somewhere and rotated eventually,
so answering the two together costs less than answering either alone and avoids
one key custody story being written twice with different answers.
8. Whether this board takes experiments from anybody, or only from the people
who keep it.
The plan assumes contributors from outside throughout and never decides that they
are wanted. A sign-off gate asks somebody to certify their right to contribute. An
issue template invites a proposal. The contributing guide is written for a person
arriving with an idea. Entry three above asks who may place a contributor's work
under another board's terms, which only becomes a question once there are
contributors. None of that settles the question, and the answer changes what all
four of them say.
Taking them is what a public board usually means, and it is the only way this one
becomes useful to anybody who is not already here. The cost is not review effort,
which is ordinary. It is that three rules in this plan depend on a person having
read them before they start: what may never be committed, what happens when an
experiment finds a flaw in shipped software, and what an experiment may do with
real data. Somebody arriving for the first time is exactly the person least likely
to have read any of them, and the first two are the ones where a mistake is public
and permanent. Nothing here can refuse those violations, which is stated plainly in
the issues that hold them, so the residual sits on whoever reads the change.
Taking none, and saying so, costs the board its reach and buys a much smaller
surface. The cost is that the guide, the templates and the sign-off gate are then
written for an audience that does not exist, and a repository that reads as open
while accepting nothing wastes the time of whoever believes it.
A middle option is taking proposals as issues rather than as changes, so a
question is discussed before anybody writes code against it. The cost is that it
turns the cheapest thing this board offers, which is trying something, into a
request that somebody has to answer.
Whatever the answer, the contributing guide has to carry it in the first
paragraph, because the alternative is somebody finding out after doing the work.
Issue #9 writes that guide and waits on this entry rather than guessing, and the
templates in issue #48 follow the same answer.
Done when every entry above carries an answer, each answer has an issue opened for
the decision record that writes it down with its reasons, and this issue is closed
with nothing left undecided.