Re: Proposal for TSC RFCs?
We should have a process in which proposals are well-formed and documented in a standard way prior to the TSC adopting them. A minimum amount of rigor should be expected and demanded from the proposer and the TSC itself when making decisions which impact the projects. At the same time, we should keep the process reasonably lightweight. The Rust RFC process strikes a good balance, especially in terms of what is required in its template, and I think we can define a similarly good and lightweight process and template for TSC decisions while achieving that desired amount of rigor.
I do not believe that all TSC decisions need an RFC-like document; the threshold should be ones that set a policy or define a process. It should not be required for ad-hoc/operational decisions. A log or index of decisions and links to RFC-like documents and/or meeting notes is a fairly good idea regardless.
The proposals should capture a few things (derived from the Rust RFC template):
- Summary - a paragraph or two which summarizes the document
- Motivation - explanation why the proposal is being brought forward
- Guide-level explanation - fairly high-level description that describes the proposal; maybe we call this "High-level instead of Guide-level"
- Reference-level explanation - an detailed explanation; details about how it will be achieved are appropriate here; maybe we call this "Detailed explanation"
- Drawbacks - "Why should we *not* do this?"
- Rationale and alternatives - This should explain why this proposal is the best option, and also describe other alternatives which were consider or suggested by others
- Prior Art - discussion about other solutions we are taking inspiration from and links
- Unresolved questions - questions that still exist, but that are not addressed by the proposal as-is.
One of the very important aspects of a template like this is that it attempts to provide context. Motivation, Drawbacks, Rationale and alternatives, and Prior Art all provide context. The document should attempt to fairly describe other points of view in it's Rationale and alternatives section. And in that way, it should capture and summarize the discussion and debate (if any) to everyone's satisfaction, even those that may be opposed to the proposal.
In addition to the template, the surrounding process should use the proposal as a vehicle to drive consensus prior to the TSC's adoption of the document.
The process should also encourage maintainer review - which is only possible if it is well-documented ahead of the decision. Not all maintainers that are impacted may be able to attend TSC meetings (and certainly not every TSC meeting), and this process should provide an artifact (the document) that the maintainers can look at and comment on prior to the decision (and then the TSC, as the reps for the projects, should take the maintainer feedback into account).
Wiki changes are recorded and can be reversed. Also, only logged in users can edit, so we know who the culprit is. If decisions are recorded in the wiki next to the link to the minutes, then makes searching much easierCheers,
Christopher Ferris
IBM Fellow, CTO Open Technology
IBM Digital Business Group, Open Technologies
email: chrisfer@...
twitter: @christo4ferrisIBM Open Source white paper: https://developer.ibm.com/articles/cl-open-architecture-update/
phone: +1 508 667 0402I don't think meeting minutes or the wiki do quite the same job as what is being proposed here. In particular:- Although meeting minutes may be canonical, and certainly votes, not all utterances represent a deliberate decision, they are open to a lot of interpretation and its not that user friendly searching through minutes that are meant to be complete as opposed to declarative- The wiki is useful and we should encourage contribution but we would not want anyone to edit an RFC or decision record after it has been finalised - it should be immutable like statute and may be superseded by later RFCs. They are not living policies documents but point-in-time records.There are a number of overlapping types of document in this general vein - my understanding is RFCs are often more about standards, whereas Architecture Decision Records (ADRs) are more about answering 'why the hell was/wasn't it done this way'. I have found the latter useful even just for my future self.Neither of these are probably perfect fit for organisational decision and policy, but for decisions that are fairly technical in nature I can see them being adapted well. Are we trying to record decisions and why they were made or to document standards?The question is whether keeping these records is worth the extra book-keeping?? If we introduce such a record, I suggest:- We make it a light-weight decision record (rather than extensive or complete standard-making exercise - more ADR less RFC)- Official written policy should be authoritative (like code is over RFCs)- Decision records should be allowed to go stale and not be updated (less overhead, 'point-in-time records')- Not everything needs to go in a decision record - it should happen when some members of the TSC think it would be useful - at which point all members of the TSC (and community) should scrutinise it- If there is insufficient consensus to say something definiitive we should probably wait until there is- A single TSC member should be given the task of making sure the decision record gets finalised and published (if its worth doing, hopefully there are volunteers, otherwise perhaps its not...)- These records should be 'of the TSC' not 'of Hyperledger' or 'of the community' so I think it is more acceptable to use git, and publish to a known location. Not to say we should adopt a top-down style, but this record represents what the TSC decided at a time (which isn't the law, but it is from a fairly coherent entity) after taking advice and evidence. It might be completely wrong, but I wouldn't want someone to fix it in the future.SilasOn Fri, 2 Aug 2019 at 00:56, Ashok Malhotra <malhotrasahib@...> wrote:I have long argued that working groups need a simple way toanswer questions like "When did we make this decision?" and "Wheredid this paragraph in the spec come from". I have some ideas on how to'facilitate this but would love to see a proposal.Ashok MalhotraOn Thu, Aug 1, 2019 at 10:46 AM Christopher Ferris <chrisfer@...> wrote:I agree, pouring through old minutes looking for decisions etc is tedious at best. I also agree that we don't need to over-engineer this. It could be implemented in the wiki pretty easily. I've been thinking that where we link the posted minutes and recording, we could also list the relevant decisions.eg2019 07 25 minutes (link)Motion on accepting the Diversity, Civility, and Inclusion WG Proposal APPROVED2019 07 18 minutes (link)...IBM Open Source white paper: https://developer.ibm.com/articles/cl-open-architecture-update/
phone: +1 508 667 0402----- Original message -----
From: "Arnaud Le Hors" <lehors@...>
Sent by: tsc@...
To: "hmontgomery@..." <hmontgomery@...>
Cc: Brian Behlendorf <bbehlendorf@...>, "tsc@..." <tsc@...>
Subject: [EXTERNAL] Re: [Hyperledger TSC] Proposal for TSC RFCs?
Date: Tue, Jul 30, 2019 10:59 PM
I'm not sure where we ended with this discussion. I agree that we should do a better job at recording decisions and fully support the idea of building a compilation of all the TSC decisions.
For reference, this is something I did in the past when I chaired the W3C RDF Data Shapes WG and this info was extremely valuable. You can see what it looked like on the following page. Each resolution is listed with a pointer to the relevant minutes.
https://www.w3.org/2014/shapes-resolutions
--
Arnaud Le Hors - Senior Technical Staff Member, Blockchain & Web Open Technologies - IBM
From: "hmontgomery@..." <hmontgomery@...>
To: Brian Behlendorf <bbehlendorf@...>, "tsc@..." <tsc@...>
Date: 06/12/2019 08:57 AM
Subject: [EXTERNAL] Re: [Hyperledger TSC] Proposal for TSC RFCs?
Sent by: tsc@...
Hi Brian,
You bring up good points. I don’t think it’s necessary that such a decision/workflow tracker use git, or other heavyweight systems. I obviously cannot speak for Shawn but I am pretty sure he didn’t mean that we needed to use git for this, either—just the essence of the rust RFC system. But, as you point out, it would be nice if we had a single, searchable place for TSC-implemented policies and rules. As Shawn points out, it would also be nice if we had a formal way to capture some of the decisions the TSC has made over the years.
Several times the TSC has had to remake decisions, or go back and think “did we formally say this? Does rule X extend to Y?” We have even “forgotten” about entire projects, as I alluded to in the subproject discussion. So I think that a little bit of (very lightweight) formalism around this might go a long way into saving the TSC time in the long run and making it easier for people to know what rules and procedures they need to follow.
Thanks,
Hart
From:tsc@... [mailto:tsc@...] On Behalf Of Brian Behlendorf
Sent: Tuesday, June 11, 2019 9:48 PM
To: tsc@...
Subject: Re: [Hyperledger TSC] Proposal for TSC RFCs?
The minutes and recordings of the TSC meetings are the formal recording of decisions made and should be considered canonical. Since Jan 24th of this year, those notes are taken & stored on the Wiki:
https://wiki.hyperledger.org/display/HYP/TSC+Meeting+Minutes
Previously, minutes were taken either as emails to the TSC list or as pages on Google Docs, and then posted along with recordings on a similar page, but on our older wiki:
https://wiki-archive.hyperledger.org/groups/tsc/technical-steering-committee
It would be Really Cool if volunteers emerged to do two things:
1) Faithfully copy over the hypertext from the old Wiki's archive page to the current one
2) Migrate all the minutes stored on Google Docs to wiki pages.
Doing both will make it easier to search across the minutes, ensure they don't get modified without visibility, etc. Any takers? This is on the long long backlog for HL's small staffed community architecture team, but seems like an easy thing we could ask for help with.
New project proposals are formally tracked:
https://wiki.hyperledger.org/display/HYP/Project+Proposals
However, it's clearly not kept up to date well enough, and that's another example of history that has not been ported over to the new Wiki. Any volunteers to help clean that up? It's annoying enough to me in its current state and the air temperature is still too warm to fall asleep so I may get to it myself tonight. But if someone feels up for it, feel free to tag in.
Requiring a formal proposal template for all topics for TSC conversations, or those that would result in decisions, feels a bit process-heavy, as often small suggestions during a conversation become decisions made. But for the larger concepts, such as new graphical takes on the greenhouse, I've been encouraging people to make these suggestions in longer form ahead of time, giving TSC members a chance to read & consider before discussing on the calls. I'm also completely happy (as anyone who knows my antipathy for calls knows) to see issues opened, discussed, and decided completely outside of the calls. Getting people to at least use the mailing list and Wiki for these proposals rather than Google Docs would be an improvement; seeing a page in the TSC space of outstanding issues (much like the "backlog" queue maintained in the current agenda) would as well. But the calls are at least a place where the TSC can reach and formally record a consensus on an issue, even if that only takes 5 minutes to reflect the consensus arrived at over an email conversation. So the minutes to those meetings should still be the canonical source of what was decided, even if the why and rationales are a bit more spread out.
While using Git to manage RFCs makes sense for code-level decisions, using Git/Github for TSC proposals and discussions feels like it might exclude quite a few people. Needing to do a git clone to change text is a fair uplift from going to a wiki page and clicking edit - totally justified when you're all maintainers and already have git copies of your core projects' repos locally, but harder outside that context. In both systems you get visibility into who's changed what. In a wiki you get search for free (yes, one could grep locally...). In either scenario you need gardeners, which feels like the most precious resource we have.
Brian
On 6/11/19 3:22 PM, hmontgomery@...wrote:
I think this is a great idea. We have forgotten and/or reinvented so many things over the years, and good documentation would help us keep track of policy, as well as help newcomers unused to the TSC workflow.
I don’t know what the exact best way for this to happen is—as Shawn mentions, all of the projects that used the Rust template have tweaked it, sometimes substantially. But I think something like this would help us from making mistakes related to lack of information on previous TSC decisions. I’d support such a task force.
Thanks,
Hart
From:tsc@...[mailto:tsc@...] On Behalf Of Shawn Amundson
Sent: Tuesday, June 11, 2019 1:48 PM
To: hyperledger-tsc <hyperledger-tsc@...>
Subject: [Hyperledger TSC] Proposal for TSC RFCs?
As a project maintainer and part of the Hyperledger community, it is difficult to track what past decisions (especially related to policy) have been made by the TSC. The quality of proposals going to the TSC also seem to vary quite a bit, as does the amount of discussion about them.
In several of the projects, we have adopted an RFC process based on the one used for Rust (why invent a new one, if there is already a great one) - https://github.com/rust-lang/rfcs. Each project has adjusted it to its own needs.
Proposals like those coming out of the lifecycle and CI/CD discussions could be captured in this manner. Something like - https://github.com/rust-lang/rfcs/blob/master/0000-template.md. It's a really nice format, with sections to capture drawbacks, rationale, and alternatives -- which leads to a more informed decision.
Would the TSC be open to adopting something like this?If so, could we form a task force to put together a solid proposal for it? (Yes, I'm volunteering.)
-Shawn
--
Brian Behlendorf
Executive Director, Hyperledger
bbehlendorf@...Twitter: @brianbehlendorf
--All the best, Ashok
