Submitting and Archiving Proposals

[mickael-menu]

So far we've been using Google Doc for any non-trivial proposal regarding the Readium Toolkit, but it's not a great solution:

• The proposals are not easily discoverable by contributors.
• Since we don't archive them, it's difficult to find them again later on.
• Ownership is unclear.
• Reviewing updates is not convenient.
• Converting a Google Doc to a Markdown document is not straightforward.

Using GitHub issues is not convenient either, because there's a single thread that becomes quickly difficult to follow. There's no easy way to update a proposal while notifying other contributors (as we can see in this recent issue from @JayPanoz).

I suggest following Apple's lead with the Swift Evolution repo and write proposals as Markdown document in GitHub. This has a number of advantages:

• We can submit a review as a pull request, which allows commenting specific lines, following different threads of discussion and approve/reject the proposal explicitly as a reviewer.
• We can follow updates in the PR and GitHub even marks comments that are outdated when the content changes.
• The proposals would be nicely archived and easy to browse. All the discussions would be kept in the Pull Request history.
• These proposals should link to related GitHub issues and implementation PRs to serve as a reference for other implementers.
• Since they are already Markdown document, they can serve as a quick source to write technical documentation.

I've published a PR following this model, as a proof of concept.

If there're enough contributors interested in this approach, I'll draft a guideline to write the proposals.

[JayPanoz]

+ 1 since, as you mentioned, dealing with that today was quite an awful experience in the issue I opened.

[jccr]

Very much in favour of this +1

This matches with the concept of "Architecture Decision Records" that I've mentioned.

[mickael-menu]

This matches with the concept of "Architecture Decision Records" that I've mentioned.

Yes that's what I had in mind as well

[mickael-menu]

I submitted a template that we can use to quickstart a proposal: #129

[jccr]

Is there any work left here? Can this be closed since #129 was merged?

[mickael-menu]

I don't think so, we can close it.