* doc: add warning against omitting outputs
While implied by the specification, add an explicit warning that
generated outputs MUST not be omitted from the final transaction.
Co-authored-by: Mark "Murch" Erhardt <murch@murch.one>
The specified field order is consistent with both BIPs 2 and 3. The
ordering of fields which are only present in one or the other is
ambiguous, e.g. as in `Proposed-Replacement` and `Superseded-By` but
only one of these applies to a given BIP.
The `Editor` field is spurious, only being used in BIP 69, and appears
after Author.
-BEGIN VERIFY SCRIPT-
set -e
perl <<'-END PERL-'
use strict;
use warnings;
my $topbip = 9999;
my @FieldOrder = qw(
BIP
Layer
Title
Author
Authors
Editor
Deputies
Discussions-To
Comments-Summary
Comments-URI
Status
Type
Created
License
License-Code
Discussion
Post-History
Version
Requires
Replaces
Proposed-Replacement
Superseded-By
);
my $bipnum = 0;
while (++$bipnum <= $topbip) {
my $fn = sprintf "bip-%04d.mediawiki", $bipnum;
my $is_markdown = 0;
if (!-e $fn) {
$fn = sprintf "bip-%04d.md", $bipnum;
$is_markdown = 1;
}
-e $fn || next;
open my $F, "<", $fn or die "$!";
my (@before, %preamble, @after);
if ($is_markdown) {
while (<$F>) {
push @before, $_;
last if m[^(?:\xef\xbb\xbf)?```$]
}
die "No ``` in $fn" if eof $F;
} else {
while (<$F>) {
push @before, $_;
last if m[^(?:\xef\xbb\xbf)?<pre>$];
}
die "No <pre> in $fn" if eof $F;
}
my %found;
my ($title, $author, $status, $type, $layer);
my ($field, $val, @field_order);
while (<$F>) {
push @after, $_ and last if ($is_markdown && m[^```$]);
push @after, $_ and last if (!$is_markdown && m[^</pre>$]);
if (m[^ ([\w-]+)\: (.*\S)$]) {
$field = $1;
$val = $2;
} elsif (m[^ ( +)(.*\S)$]) {
$val = $2;
} else {
die "Bad line in $fn preamble";
}
push @{$preamble{$field} ||= []}, $_;
}
push @after, <$F>;
close $F or die $!;
open my $W, ">", "$fn" or die "$!";
print $W @before;
print $W map { @$_ } grep { defined } delete @preamble{@FieldOrder};
die "Unknown fields: @{[ keys %preamble ]}" if %preamble;
print $W @after;
close $W or die $!;
}
-END PERL-
-END VERIFY SCRIPT-
The actual reason why I suggest this is that I think that's a great
default choice for a new BIP, so it's a perfect example. CC0-1.0 is a
great liberal choice for the BIP document (and test vectors etc.), and
MIT is the common choice for code in our ecosystem. Putting both BIP and
code under the "OR" avoids any confusion about which part is licensed
under which terms and also avoids any hassle when reorganizing, e.g.,
when moving code out of the BIP Markdown file to a separate file etc.
But I don't want this PR to recommend a license, so let me sell this
change as an editorial change to an example, which is warranted because
the MIT is much more known than FSFAP, in particular in this ecosystem.
I think that requirement is not helpful. I don't think hat including
additional licenses will be overwhelming to the reader. If anything, it
will obfuscates the actual licensing conditions. (Anyway, this should be
super rare.)
That's a bit of legal nitpicking, sorry. CC0 contains something like a
public domain dedication along with a fallback license, so it's neither
entirely. Some call it a "legal instrument". I prefer not calling it
anything.
SPDX doesn't have an official identifier for "public domain", at least
not for the simple "This document is placed into the public domain"
declarations used in some BIPs, see
https://wiki.spdx.org/view/Legal_Team/Decisions/Dealing_with_Public_Domain_within_SPDX_Files
for the rationale provided by their legal team. The rationale is sound,
but It's possible to create "user-defined" identifiers of the form
LicenseRef-X. This is a good idea here to make sure that all SPDX
expression will be formally valid.
And in our case, all "PD" BIPs match the following pseudo regex, so
there's not much potential for confusion:
"This (document|BIP|work|proposal) is (hereby)? (placed)? in the
public domain."
So it makes sense to keep using a single identifier for all of these.
