I started documenting my understanding of our process after @miqui's question today about how we were going to resolve the various discussions. I realized we needed a bit more detail than "ADRs!" since not everyone is familiar with them, and even then it's not quite clear how we're getting from a pile of discussions to a spec and how ADRs fit in.
The obvious place to put this would be the repository's README. But the README was already used for the initial Moonwalk proposal... except that we're now focusing on ADRs and only using those proposals as a reference point. As @darrelmiller noted when I asked last week about how references could be either objects or arrays of references in the original README, and how references were just strings in the Deployments proposal, those proposals weren't really intended as formal documents. And we're not deciding things by opening PRs on them.
So... I took the possibly controversial approach of moving all of the documents and examples from the root to a /doc/initial-proposals tree parallel to the /doc/architecture tree. I feel like this approach preserves the state of those proposals (the internal links still work) while acknowledging that they're not necessarily accepted in the ADR sense.
As we accept more ADRs, we'd either need to keep the proposal-README updated with a mix of accepted and tentative syntax, or just let things get increasingly out of sync. That doesn't seem ideal to me. Originally, we needed a proposal in the README to build excitement, but Moonwalk is pretty well established as a project now, so asking folks to click a bit more shouldn't be too burdensome, and shows more clearly where the work is happening.
The new README prominently links to the proposals under the "Contributing" section, and also features a condensed form of the principles from the blog post (I also removed the note that had been added to the original README about the blog post). I think the only other file that got linked to was Deployments.md, and I'll go update links in the discussions if this is accepted.
While I think this is an improvement, I'm not at all attached to it and wrote it very quickly. I'm happy to rework it or abandon it entirely if it doesn't seem like the right move.
I started documenting my understanding of our process after @miqui's question today about how we were going to resolve the various discussions. I realized we needed a bit more detail than "ADRs!" since not everyone is familiar with them, and even then it's not quite clear how we're getting from a pile of discussions to a spec and how ADRs fit in.
Note: You can see the rendered changes on my branch in my fork.
The obvious place to put this would be the repository's README. But the README was already used for the initial Moonwalk proposal... except that we're now focusing on ADRs and only using those proposals as a reference point. As @darrelmiller noted when I asked last week about how references could be either objects or arrays of references in the original README, and how references were just strings in the Deployments proposal, those proposals weren't really intended as formal documents. And we're not deciding things by opening PRs on them.
So... I took the possibly controversial approach of moving all of the documents and examples from the root to a
/doc/initial-proposalstree parallel to the/doc/architecturetree. I feel like this approach preserves the state of those proposals (the internal links still work) while acknowledging that they're not necessarily accepted in the ADR sense.As we accept more ADRs, we'd either need to keep the proposal-README updated with a mix of accepted and tentative syntax, or just let things get increasingly out of sync. That doesn't seem ideal to me. Originally, we needed a proposal in the README to build excitement, but Moonwalk is pretty well established as a project now, so asking folks to click a bit more shouldn't be too burdensome, and shows more clearly where the work is happening.
The new README prominently links to the proposals under the "Contributing" section, and also features a condensed form of the principles from the blog post (I also removed the note that had been added to the original README about the blog post). I think the only other file that got linked to was Deployments.md, and I'll go update links in the discussions if this is accepted.
While I think this is an improvement, I'm not at all attached to it and wrote it very quickly. I'm happy to rework it or abandon it entirely if it doesn't seem like the right move.