libp2p specs framework: document header format #171
Conversation
| [@author1]: https://github.com/author1 | ||
| [@author2]: https://github.com/author2 | ||
| [@interested1]: https://github.com/interested1 | ||
| [@interested2]: https://github.com/interested2 |
There was a problem hiding this comment.
This looks redundant, the @ mentions suffice.
There was a problem hiding this comment.
On github.com, yes, but that's not the only reading venue from these specs. If we remove the links, we'd being relying on a proprietary backend to fill in the blanks for us, which is something I don't want to do. People should be able to view these specs locally, in raw format, and follow the links manually. In the future, we'll want to compile them in a PDF book as well, or even a different site. Or export them to https://docs.libp2p.io.
I don't agree, can you elaborate on how you see a descriptive name successfully supporting spec development? While any members of the community may review a spec, having clearly defined/responsible individuals help create a clearer path for moving specs forward. Right now, I think ambiguity of reviewers is contributing to specs stalling. It's not really clear who should review the spec and when the spec is ready to merge. Having clearly responsible individuals helps remove that ambiguity and avoid deferral of responsibility. |
| [@author1]: https://github.com/author1 | ||
| [@author2]: https://github.com/author2 | ||
| [@interested1]: https://github.com/interested1 | ||
| [@interested2]: https://github.com/interested2 |
There was a problem hiding this comment.
On github.com, yes, but that's not the only reading venue from these specs. If we remove the links, we'd being relying on a proprietary backend to fill in the blanks for us, which is something I don't want to do. People should be able to view these specs locally, in raw format, and follow the links manually. In the future, we'll want to compile them in a PDF book as well, or even a different site. Or export them to https://docs.libp2p.io.
|
|
||
| Each spec begins with its title, formatted as an H1 markdown header. | ||
|
|
||
| The title can optionally be followed by a short block-quote introducing the |
00-framework-02-document-header.md
Outdated
| - The full name of the status that the spec is currently in. | ||
| - For `Candidate Recommendation` or `Recommendation` specs, valid values are | ||
| `Active` and `Deprecated` | ||
| - For `Working Draft` specs, valid values are: `Active` and `Terminated` |
There was a problem hiding this comment.
| - For `Working Draft` specs, valid values are: `Active` and `Terminated` | |
| - For `Working Draft` specs, valid values are: `Active` and `Terminated`. |
00-framework-02-document-header.md
Outdated
|
|
||
| To make the list readable in the markdown source, we use the [shortcut reference | ||
| link syntax][gfm-shortcut-refs], which allows us to wrap the author name in | ||
| square brackets in the list and define the link target below. For example: |
There was a problem hiding this comment.
Albeit this may appear redundant when viewing in github.com with the GitHub renderer, it's necessary to avoid losing information when viewing elsewhere.
| The Authors and Interest Group lists must be separated by a newline, which | ||
| causes them to render as distinct paragraphs. | ||
|
|
||
| When proposing a new `Working Draft` where the Interest Group is unknown, use |
00-framework-02-document-header.md
Outdated
|
|
||
| Authors: [@yusefnapora] | ||
|
|
||
| Interest Group: TBD |
There was a problem hiding this comment.
Maybe declare 5 people, since this spec looks pretty finalised and promotion to Candidate Recommendation and then Recommendation should be imminent? Suggestions: @raulk, @vyzo, @mgoelzer, @jacobheun, @tomaka?
|
@yusefnapora should we have two categories of labels for status and maturity? This could be a: |
Co-Authored-By: Raúl Kripalani <raul.kripalani@gmail.com>
Co-Authored-By: Raúl Kripalani <raul.kripalani@gmail.com>
Co-Authored-By: Raúl Kripalani <raul.kripalani@gmail.com>
|
@raulk I hadn't really thought about the status label - I guess I was thinking that open PR = active, but it may be useful to have labels for status as well. I like using |
|
I went ahead and put @raulk, @vyzo, @mgoelzer, @jacobheun, @tomaka as Interest Group members. Give this comment a 👍 or 👎 to signal whether you're on board 😄 I think @vyzo has a point that the real interest group is the people that show up to talk about the spec, but I also think it's valuable having a fixed set of people who agree to be involved. I think the key is to socialize that being in an Interest Group is a lightweight thing that anyone can do. It's basically the same thing as showing up in the PR thread and commenting, except that you're agreeing to do it on a schedule. We should also be clear that everyone is still welcome to show up on PRs and discuss; you don't need to be in an Interest Group to be interested. |
|
prodding @vyzo @tomaka @jacobheun @mgoelzer; see the above comment ^^ |
Following up with #169, this adds a spec for a small header to put at the top of our spec documents to convey the current lifecycle information, spec authors & interest group.
I've added these to the peer id and secio spec PRs, if anyone wants to see a real-world example.
In the spirit of the new lifecycle framework, I set the maturity level for this PR to
Working Draft, so we can try sending this through the whole process.Who wants to be in the Interest Group for this?