I’ve been wondering more about this because we need to answer the following questions:
- When do we create an ADR? Do we do it for all decisions (cumbersome) or only for large decisions?
- Do we link from ADR to design.xwiki.org or from design.xwiki.org to ADR? Which one is the source of truth?
For 1), I think that one easy rule is that any forum thread tagged with proposal should lead to an ADR.
For 2), I’ve started to review if there’s really a difference between ADR and design.xwiki.org. Let’s look at the XClass for design.xwiki.or (i.e. ProposalCode.ProposalClass):
- Product: needed in the ADR too if we want to use it for different products (and we have it already)
- Name: same as ADR’s title
- Type (Design, Requirements, Feature, Implementation, etc): not in our current ADR impl but could be. Not sure we really need this field and not sure we’ve ever really used it.
- Status: there’s a difference here. An ADR is something that was agreed on while design.xwiki.org currently contains work in progress, or stuff that were dropped. However, it’s not a problem to have this concept for an ADR and only focus on the “Completed” ones.
- Participants: would be ok for an ADR. Not sure we need it, anyone replying on the forum is actually a participant, yet we often don’t update the participants field. I think I’d change that field to be “Proposers” instead (ie the list of people who are proposing it).
- Issues/Mails/Other URLs: this could all be merged in a single Links field (which we have in our current ADR impl)
- Description: We don’t really have it in our ADR. We have a Decision and a Alternatives with pros/cons. The way I see it, we could rename Description into Proposal, and it would list the alternatives with pros/cons, and have another Decision xproperty which would be used to explicitly list the decided/agreed decision (something we’re lacking on design.xwiki.org ATM as we never know if the entries have been updated after the discussion on the forum or not).
- Then we could add a Consequences field, which we have in our ADR for registering future consequences of the decision taken.
- We should also add a decision date as we have in the ADR impl.
- Last, we could add a Context field to define what the proposal is about and the context of the proposal (why is it proposed).
So, all in all, I think an design.xwiki.org is an ADR and we just need to massage it a bit.
What we could imagine:
- Create the next version of design.xwiki.or and export it as ADR app on contrib.
- Make the changes mentioned above.
- Create https://adr.xwiki.org and use the ADR app
- Make design.xwiki.org read only and direct users to adr.xwiki.org for creating new entries
- Migrate active proposals on design.xwiki.org to adr.xwiki.org
The general process would be:
- Make a proposal on the forum (with the full proposal in the forum post or by pre-creating an entry on adr.xwiki.org and linking to it)
- Once the proposal is agreed on the forum, create or update adr.xwiki.org to record the decision and the decision date (and make sure the Proposal xproperty is also up to date), set the status to Closed/Completed/Agreed.
- Close the forum post as solved, with a link to adr.xwiki.org
WDYT? Should I send a proposal on the https://forum.xwiki.org/c/dev/13 category to propose this for all and not just for Cristal?