Meta design doc

[andyk]

This is a proposal to update our design doc and design review process.

The current process is documented in the README of the design_doc repo. Currently, if a developer has a new idea for a significant feature, they:

1. Write a draft design doc and submit it for review via a PR.
2. Discussion happens via comment threads in the PR.
3. If/when it is approved by a committer, the PR is merged.
4. Subsequent updates to the doc are submitted as new PRs, and discussions associated with them are done via comments in those PRs.

The advantages of this are:

• Discussions are done in public forums
• No new dependencies (e.g., google docs) are added. It is all in GitHub/git.

The major disadvantages of this are:

• discussion for a feature will end up fractured across multiple PRs.
• It is confusing that the version of a design doc currently committed to the design_docs repo is not the newest version.
  • Instead, the newest version of a design doc--while it is being reviewed--lives in document owner's GitHub fork of the design_docs repo.
• It is cumbersome to find a human readable version of the design dock before it is merged into the repo.
• Commenting on specific lines of the doc is still not easy/possible (compared to google docs).

I propose that we:

• update our process to use GitHub Discussions for all feature proposals, design docs, and design doc discussions
• migrate everything from the separate design_docs repo into the agentos repo in the documentation/design_docs folder, and move these discussions over there too.

The new flow will be as follows:

1. submit your feature idea as a new discussion under the "Ideas" category.
2. iterate on the idea via discussion in that #Ideas thread
3. if/when it is approved by a committer, the #Ideas discussion is migrated to a #Designs discussion (either by creating a new discussion or changing the category in the original discussion), and..
   • For smaller features, the body text of the discussion thread acts as the design doc, reviews happen via comments in the discussion thread and feedback is merged into the doc by editing the original discussion text (version history is not available).
   • For especially large designs, a document written in ReStructuredText may be created in the documentation/design_docs folder and edited at will by the design owner (without PRs). This way editing history of the document is retained.

This new process addresses several of the disadvantages of the current process, specifically:

• we shouldn't need links to versions that live in GitHub forks
• the master branch of the design_doc repo should contain the most recent version of the design doc
• all historical discussion is maintained in a sensible centralized place

One disadvantage with the above process is that it is difficult to reference specific lines of a version of a ReStructedText file (like one can with code files), so we will just have to copy and paste quotes into our comments instead.

[nickjalbert]

Just wanted to comment that I like this idea.

If we move to a discussions-based flow, though, is there much value in also requiring a formal design doc in the repo? I'd suggest we consider something like:

• Submit your feature idea as a new discussion under the "Ideas" category.
• Iterate on the idea via discussion in that Ideas thread
• Once it is approved by a committer, then the #Ideas discussion is migrated to a #Designs discussion (either by creating a new discussion or changing the category in the original discussion).

I like that this is relatively lightweight. Perhaps we could also provide a template (similar to the current design docs) for the Ideas discussion.

[andyk]

Yeah your proposal does seem like a much cleaner flow to me. I’ll update my idea :-)

…

On Thu, Feb 25, 2021 at 3:26 PM Nick Jalbert ***@***.***> wrote: Just wanted to comment that I like this idea. If we move to a discussions-based flow, though, is there much value in also requiring a formal design doc in the repo? I'd suggest we consider something like: - Submit your feature idea as a new discussion under the "Ideas" category. - Iterate on the idea via discussion in that Ideas thread - Once it is approved by a committer, then the #Ideas discussion is migrated to a #Designs discussion (either by creating a new discussion or changing the category in the original discussion). I like that this is relatively lightweight. Perhaps we could also provide a template (similar to the current design docs) for the Ideas discussion. — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <https://github.com/agentos-project/design_docs/discussions/8#discussioncomment-407589>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AABX5BTHIUW4Y7D42NFZM63TA3MCJANCNFSM4XPUXAKQ> .

[andyk]

Updated the original proposal text.

For large features it is nice to still have a living doc with a version history, but PRs & reviews have felt to heavy weight for that. So I propose the document can just push edits to his design doc w/o PRs or reviews.

Also, I’m more inclined after trying out this separate repo to just keep everything in the agentos repo, and design docs can live in a folder and committers can push edits to docs they own without PRs or reviews.

What do you think of these two ideas? (My proposal above reflects both.)

[nickjalbert]

I dig both these ideas; the updated proposal SGTM! :)

[andyk]

This proposal has been implemented now. Everything is consolidated into https://github.com/agentos-project/agentos/discussions and https://github.com/agentos-project/agentos/tree/master/documentation/design_docs