RFC: EcoStd RFC Process (#1)

Author: grafikrobot

.gitignore

@@ -1 +1,2 @@
 /.build
+[0-9][0-9][0-9][0-9]-*.html

CONTRIBUTORS.adoc

@@ -0,0 +1,5 @@
+= Contributors
+
+== RFC Authors
+
+* René Ferdinand Rivera Morell

README.adoc

@@ -0,0 +1,173 @@
+= EcoStd RFCs
+:license: Creative Commons Attribution 4.0 International License (CC BY 4.0)
+:nofooter:
+:reproducible:
+:revdate: {docdate}
+:sectanchors:
+:sectnumlevels: 10
+:sectnums:
+:source-highlighter: rouge
+:toc-title: Contents
+:toc:
+:toclevels: 5
+:version-label!:
+
+// TODO: Fill with "Design" section from 0001-rfc-process proposal below.
+
+[#process]
+== Process
+
+In order to add or make changes to the EcoStd standards one must get an RFC
+approved (i.e. proposed, discussed, voted on, and merged). Before following the
+steps below, make sure to read this entire process. As there are considerations
+to keep in mind that will improve the chances of your proposal being effective.
+The steps to submit an RFC are:
+
+. Fork the https://github.com/ecostd/rfcs[RFCs repository].
+
+. Copy the `src/00/00-template-adoc` (or `src/00/00-template-md` for
+  Markdown
+  footnote:gfm[GitHub Flavored Markdown (https://github.github.com/gfm/)])
+  directory to `src/00/00-sliced-bread` (change `sliced-bread` to
+  something short, but descriptive).
+
+. Write your RFC in the `proposal.adoc` (or `proposal.md` for Markdown
+  footnote:gfm[])
+  file. If you need additional files you should place them *only* in the 
+  directory. It's important, i.e. required, to properly fill in the `authors` 
+  and `email` metadata fields at the top with your information. As they are 
+  used for proper license attribution. Consult the
+  https://docs.asciidoctor.org/asciidoc/latest/[Asciidoctor documentation],
+  or on how to do that.
+
+. Submit a pull request. In addition to the RFC itself you should provide a
+  brief description in the pull request itself. Copy-pasting the RFC abstract
+  into the PR description is minimally sufficient.
+
+. Use the pull request number you now have to rename the
+  `src/00/00-my-proposal` directory to match the PR number and fill the
+  `rfcpr` field in `proposal.adoc` (or `proposal.md` for Markdown
+  footnote:gfm[]) to match.
+
+. At this time the RFC will be considered _active_ and will be labeled
+  accordingly. The RFC will receive initial feedback for which you will need to
+  respond, preferably both in the PR comments and reflected in the RFC text
+  itself.
+
+. After some time, and sufficient discussion and interest, and if this is a
+  proposal for a standard change (or addition) you will need to write wording for
+  the standard and create a PR in the
+  https://github.com/ecostd/standard[standard] repository. You may also be
+  directly asked to produce a wording PR if needed. When you have such a PR
+  edit the RFC `stdpr` field. The RFC will be labeled either as needing
+  wording and/or having wording as appropriate. The wording PR will be
+  discussed in that PR and/or the RFC. The discussion may incur doing changes
+  to the RFC.
+
+. After sufficient time and discussion the combined RFC and wording PR will
+  be considered ready for a decision on further progress. A member of the
+  "adoption review group" will propose taking a vote for adoption.
+
+. An adoption vote starts after three members of the review group agree. The
+  vote will last at most 28 calendar days, and at least 7 calendar days. The
+  length of the voting period will be part of the voting proposal. But the
+  length is subject to community feedback before and during the voting. The
+  RFC PR will be labeled accordingly to reflect the voting.
+
+. When the adoption vote completes the RFC is either approved or rejected. The
+  RFC will be labeled accordingly and may be closed.
+
+. A rejected RFC PR may be closed depending on the reasons for rejection. The
+  RFC may stay active, but go back to being discussed, if there are changes
+  possible and reconsidered for approval.
+
+. An approved RFC PR is closed, and labeled as adopted. The actions proscribed
+  in the RFC are then taken up by others to complete. For RFCs that affect the
+  https://github.com/ecostd/standard[standard] will continue in the related
+  PR by the "standard editors group".
+
+TIP: The preferred document format for RFCs is
+https://asciidoctor.org[Asciidoctor]. But the
+https://github.github.com/gfm/[GitHub Flavored Markdown] format is supported as
+an alternative. The extent of support is subject to what is supported by the
+conversion to Asciidoctor process as part of build the HTML for the
+https://ecostd.github.io/rfcs/[RFCs website].
+
+[#guidelines]
+== Guidelines
+
+These are a loose collection of rules to follow, things to keep in mind, and
+background information that is useful when creating RFCs. They are grouped by
+the aspect of RFCs that they apply to:
+
+<<guidelines-mechanics>>:: Guidelines for the task of the RFC and PR itself.
+<<guidelines-design>>:: Guidelines for that help with the design content of an RFC.
+
+These are _guidelines_, and not _rules_. They are expected to be true most
+times. But we allow for flexibility in the process. The goal is to reduce
+friction as much as possible without sacrificing comprehensive evaluation of
+RFCs.
+
+[#guidelines-mechanics]
+=== Mechanics
+
+Do not squash, or otherwise coalesce, changes for RFC PRs::
+After creating an RFC PR additional updates should be done as additional, plain,
+commits. Having the additional commits helps in tracking how feedback is
+addressed. When an RFC is approved it will be squash merged. Hence attempts to
+pre-squash would be wasted.
+
+Mirror external feedback in the PR::
+Any feedback you get outside of PR comments should be summarized, by you, as
+comments in the PR. And if there are changes, i.e. additional commits, to the
+RFC that are related they should be mentioned in the PR comments.
+
+Do not change approved PRs::
+After a PR is approved, and labeled as such, do not alter it. It will be merged
+in due time. If there are followup changes they should come as different RFCs.
+
+[#guidelines-design]
+=== Design
+
+Prefer solutions that cast a wide net::
+The key goal of EcoStd is to facilitate wide adoption and interoperation. Hence
+single solutions that solve a wide scope are preferred. Which means that you can
+expect questions like: "`Does this solve X, Y, and Z also?`", "`Have you
+considered use case U?`", and more.
+
+Including existing practice is essential for an RFC::
+Engineering is an iterative practice as such it makes progress from existing
+solutions towards better ones. Solutions without a problem are just dreams that
+are not likely widely shared. For those reasons, and more, it's imperative that
+an RFC is based on existing practice, i.e. demonstrate that there's a problem
+and solution that this is trying to improve.
+
+Seek consensus with proposals and when responding to feedback::
+Because of the goal of this collective work is to achieve as widespread adoption
+as possible it's important to consider the varied viewpoints when composing
+solutions to problems. You should seek consensus as much as possible at all
+times. There are many ways to achieve consensus, and it would be impossible to
+enumerate them. But some general ones are:
+* Provide rationale (pros and cons) for decisions and feedback.
+* Seek to increase factual data in your proposal.
+* Include real world examples and use cases.
+* Provide before and after comparisons if you are proposing behavior changes.
+
+// TODO: Fill with "Design" section from 0001-rfc-process proposal above.
+
+[[license]]
+== License
+
+This repository, and all contributions to it, are licensed under
+https://creativecommons.org/licenses/by/4.0/[CC BY 4.0].
+
+ifeval::["{publish}" == "html"]
+
+[[rfcs]]
+== Adopted RFCs
+
+include::.build/rfcindex.adoc[]
+
+endif::[]
+
+include::CONTRIBUTORS.adoc[leveloffset=+1]

project-root.jam

@@ -0,0 +1,175 @@
+#|
+Copyright René Ferdinand Rivera Morell
+|#
+
+require-b2 5.3 ;
+
+import asciidoctor ;
+import regex ;
+import set ;
+import "class" : new ;
+import toolset ;
+import path ;
+
+path-constant here : . ;
+
+project /ecostd.rfcs
+	: build-dir .build
+	;
+
+# Find all the RFC proposals and define targets to build html for them.
+local rfcs ;
+local rfc-proposals ;
+for local proposal in [ glob src/*/*/proposal.* ]
+{
+	local rfc = [ MATCH "^src/([0-9][0-9])/([0-9][0-9])-([^/]+)" : $(proposal) ] ;
+	local type = $(proposal:S) ;
+	if $(rfc[3])
+	{
+		rfc = $(rfc[1])$(rfc[2])-$(rfc[3]) ;
+		if .adoc = $(type)
+		{
+			rfcs += $(rfc) ;
+			rfc-proposals += $(proposal) ;
+			# ADOC => HTML target.
+			explicit [ html $(rfc).html : $(proposal) ] ;
+			# Utility target to locally build proposal html (in proposal dir).
+			explicit [ install $(rfc) : $(rfc).html : <location>$(proposal:D) ] ;
+		}
+		else if .md = $(type)
+		{
+			rfcs += $(rfc) ;
+			rfc-proposals += $(proposal) ;
+			# MD => ADOC target.
+			explicit [ make $(rfc).adoc : $(proposal) : @md_to_adoc
+				:	<dependency>project-root.jam
+					<flags>"--attribute=license=Creative Commons Attribution 4.0 International License (CC BY 4.0)"
+					<flags>"--attribute=copyright=Copyright {authors}"
+					<flags>--attribute=version-label!
+					<flags>--attribute=reproducible
+					<flags>--attribute=nofooter
+					<flags>--attribute=sectanchors
+					<flags>--attribute=sectnums
+					<flags>--attribute=sectnumlevels=10
+					<flags>--attribute=source-highlighter=rouge
+					<flags>--attribute=toc
+					<flags>--attribute=toc-title=Contents
+					<flags>--attribute=toclevels=5
+					<flags>"--attribute=revdate={docdate}"
+				] ;
+			# ADOC => HTML target.
+			explicit [ html $(rfc).html : $(rfc).adoc ] ;
+			# Utility target to locally build proposal html (in proposal dir).
+			explicit [ install $(rfc) : $(rfc).html : <location>$(proposal:D) ] ;
+		}
+		else
+		{
+			ECHO "WARNING: The RFC at $(proposal) is an unsupported document type." ;
+		}
+	}
+	else
+	{
+		ECHO "WARNING: The RFC at $(proposal) is missing a name." ;
+	}
+}
+
+# Scan RFC proposal.adoc files for information to generate various files.
+RFCINDEX_ADOC = ;
+local rfc-authors = [ new set ] ;
+local rfc-info =
+	[ regex.grep $(here)/src : proposal.adoc proposal.md
+		: "= ([^\n]+).:" "---[\n]+# ([^\n]+)" "authors: ([^\n]+)" : 1
+		: recursive ]
+	;
+while $(rfc-info)
+{
+	local prop = $(rfc-info[1]) ;
+	local title = $(rfc-info[2]) ;
+	local authors = [ SORT [ regex.split $(rfc-info[4]) ",[ ]?" ] ] ;
+	$(rfc-authors).add $(authors) ;
+	rfc-info = $(rfc-info[5-]) ;
+	local rfc = [ MATCH "src/([0-9][0-9])/([0-9][0-9])-([^/]+)" : $(prop) ] ;
+	rfc = $(rfc[1])$(rfc[2])-$(rfc[3]) ;
+	RFCINDEX_ADOC +=
+		"| link:$(rfc).html[$(rfc)] | $(title) | $(authors:J=, )"
+		;
+}
+
+# Generate asciidoctor RFC from markdown/GFM RFC.
+toolset.flags $(__name__).md_to_adoc FLAGS : <flags> : unchecked ;
+KRAMDOC = [ path.native [ path.join [ path.make
+	[ SHELL "gem environment user_gemdir" : strip-eol ] ] "bin" "kramdoc" ] ] ;
+actions md_to_adoc
+{
+	"$(KRAMDOC)" "$(>)" "--output=$(<)" --auto-ids --auto-id-prefix= "$(FLAGS)"
+}
+
+# Generate rfcindex.adoc from RFC scan. Used in html RFC site docs.
+RFCINDEX_ADOC =
+	"[cols=\"3*\",stripes=odd]"
+	"|==="
+	"| RFC | Title | Authors"
+	""
+	[ SORT $(RFCINDEX_ADOC) ]
+	"|==="
+	;
+RFCINDEX_ADOC = "$(RFCINDEX_ADOC:J=
+)" ;
+
+make rfcindex.adoc : : @make_rfcindex_adoc
+	:	<dependency>project-root.jam
+		<dependency>$(rfcs).html
+	;
+explicit rfcindex.adoc ;
+actions make_rfcindex_adoc
+{
+	echo @($(<):O=F:E=$(RFCINDEX_ADOC))
+}
+
+# Generate CONTRIBUTORS.adoc automatically from RFC authors.
+CONTRIBUTORS_ADOC =
+	"= Contributors"
+	""
+	;
+CONTRIBUTORS_ADOC +=
+	"== RFC Authors"
+	""
+	;
+for local author in [ SORT [ $(rfc-authors).list ] ]
+{
+	CONTRIBUTORS_ADOC += "* $(author)" ;
+}
+CONTRIBUTORS_ADOC = "$(CONTRIBUTORS_ADOC:J=
+)" ;
+make CONTRIBUTORS.adoc : : @make_contributors_adoc
+	: 	<dependency>project-root.jam
+		<dependency>$(rfc-proposals)
+	;
+explicit CONTRIBUTORS.adoc ;
+actions make_contributors_adoc
+{
+	echo @($(<):O=F:E=$(CONTRIBUTORS_ADOC))
+}
+
+# Generate the index.html for GH pages site of RFC database.
+html index.html : README.adoc
+	:	<dependency>rfcindex.adoc
+		<dependency>CONTRIBUTORS.adoc
+		<asciidoctor-attribute>publish=html
+	;
+explicit index.html ;
+
+# Place the GH pages files in the place we publish from (in CI).
+install pub
+	:	$(rfcs).html
+		index.html
+	:	<location>.build/pub
+	;
+explicit pub ;
+
+# Update general information files that we commit for direct visibility in GH.
+install info
+	:	CONTRIBUTORS.adoc
+	:	<location>.
+	;
+explicit info ;