Should we have a supplementary spec template for proposals?

[gregsdennis]

Since we've decided that new feature proposals will be defined in external documents, should we have a template document?

[gregsdennis]

Part of #1444 will be extracting some keywords into their own documents. If we can just go ahead and do one, and then I can take that an make a template from it.

[Relequestual]

I see the document's purpose as two fold.
Firslty, to convince others beyond the champion and proposer (which may be the same) that it has value, and secondly, to allow implementers to implement.

It might make senes to have two individual documents for each proposal. There will be a need for tests later, so each proposal is going to be a folder anyway and not just a single file.

This relates to #1449 (comment) and I think we need further discussion to understand and define the requirements and purpose of a proposal.

[gregsdennis]

The proposal document (as I originally envisioned it) has two audiences:

• Business/mgmt, who need to be convinced by their devs that an experimental feature is worth including in their code. This is critical to adoption of the experimental feature.
• Devs, who need to know how the feature works. This would describe the changes to the spec documents (core & validation) that would need to be made to include this feature.

While this is two different ways of describing the feature, I believe they should co-exist in the same document.

In #1450, @jdesrosiers split my single document into two: one for the reasoning behind the feature and one to describe the feature.

However in re-reading the comments in that issue, I think some things were being conflated. I believe Jason was wanting an additional internal document that served as a sort of ADR. An ADR would contain additional information that doesn't need to go into the proposal:

• summary of the discussion & its participants
• alternatives considered with pro/con lists
• reasoning why we chose the solution we did

In making the changes, he broke out what I had included for the "business" audience thinking its purpose was more akin to an ADR, but I think these are separate things. Business/mgmt doesn't need to know the things that go into an ADR, but they do need to have a plain-language summary of the feature. Further, managing the feature description(s) in separate documents (one for business, one for devs) I think is inconvenient.

I propose possibly two documents:

• a public-facing feature description document as I had originally posted in extract propertyDependencies #1450, which includes both the high-level description and the spec changes
• an internal-use ADR-style document (maybe just an actual ADR)

Secondly, do these really need to be in the same PR? Maybe we add a requirement to the process that a concept must have an ADR written and accepted before the proposal is written. That would be an official statement of "yes, this deserves to be a built-in feature."

EDIT I've reconsidered this last paragraph. Please see my comment below.

[gregsdennis]

For the purposes of extracting existing features in order to move us toward the first stable release, I could write a single ADR that includes them all.

[gregsdennis]

We'll probably also want an ADR (or amend the existing one) if we decide to reject a proposal to explain why.

[gregsdennis]

Secondly, do these really need to be in the same PR? Maybe we add a requirement to the process that a concept must have an ADR written and accepted before the proposal is written. That would be an official statement of "yes, this deserves to be a built-in feature."

Thinking about this again, a feature could go through changes between entering the proposal/experimental stages and being promoted to stable. I think it makes more sense to have an ADR draft as part of the proposal, and then it's finalized when the proposal is promoted. This way, the ADR can contain all of the relevant details.

[jdesrosiers]

Business/mgmt, who need to be convinced by their devs that an experimental feature is worth including in their code. This is critical to adoption of the experimental feature.

Could you clarify this audience for me. I think of the main audiences as implementers and schema authors. We want implementers to build it and we want schema authors to use it. By "code" do you mean "schemas"? Is this about convincing business/mgmt to use the feature in their schemas or convincing business/mgmt to implement the feature? I'm not sure the latter makes sense as most implementations are individual projects, but I want to make sure I understand you correctly. Is the idea that because the feature is experimental, there is some risk to use it and therefore requires approval from business/mgmt and you want to speak to that concern?