Refactor design.xwiki.org into adr.xwiki.org + best practice to use it

Development
#1

Hi devs,

At Use Architecture Decision Records (ADR) for Cristal? - #8 by vmassol we discussed about using an ADR for Cristal. This has been agreed so far (only 2 devs have agreed though).

We also discussed about ADR vs design.xwiki.org and agreed that it would be nice to use the same application and generalize it (see Use Architecture Decision Records (ADR) for Cristal? - #4 by vmassol).

Now this was in the context of Cristal but we think it’s an opportunity to generalize the decision to XWiki and all projects (contrib project included).

In summary the differences from now would be:

  • Use adr.xwiki.org instead of design.xwiki.org. Architecture or Design are kind of synonyms in our usage but the important aspect for adr.xwiki.org is that it’s about proposals and decisions taken.
  • Right now design.xwiki.org is mostly (if not only) recording proposals. They are then discussed on forum.xwiki.org and we almost never record the decision on design.xwiki.org. The decision is recorded in the reference documentation with no easy way to find the discussion that happened later on. Thus the idea that when refactoring design.xwiki.org into adr.xwiki.org a new field would be added: “decision” (to record to agreed decision).
  • The process would be the following:
    • Someone makes a proposal on the forum (either by pre-creating a page on adr.xwiki.org or not)
    • Once agreed on the forum, in order to close the thread, the following must happen:
      • An adr.xwiki.org page must exist with the “decision” field filled, and the “proposal” one updated if the page was created before the forum proposal was sent, or simply filled if it wasn’t.
        • Note: this is only for proposals about the product or development processes. It doesn’t include other proposals (e.g. roadmap proposals, or Clean up of xwiki.org recycle bins)
      • The “links” field of the ADR page should link to a documentation page proper if it exists or makes sense (for example a UI design proposal doesn’t need to link to any page since we don’t document that anywhere else).
      • The forum post is closed with the link to the ADR page.
    • Pages on dev.xwiki.org can link to ADRs but reference documentation page shouldn’t (since these pages are for users and not developers of the XWiki product).

The main difference with the current practice is the sentence in bold above.

If we agree, I’m proposing myself to:

WDYT?

Thanks

Use Architecture Decision Records (ADR) for Cristal?
#2

I have a few questions:

  • This seems to assume that there is a one-to-one mapping between proposals on the forum and pages on adr.xwiki.org. What about bigger ideas that are split into several forum proposals? Could we still have overview pages for them?
  • We have quite some pages on extensions.xwiki.org that describe developer APIs, usually for API modules. Wouldn’t it make sense for at least some of them to link to adr.xwiki.org?
  • Would we retire design.xwiki.org, or would we still keep it for content that doesn’t fit the new structure?
  • How would we document decisions that are later reversed, for example, because we notice during the actual implementation or testing that there are important arguments against it?

I’m also wondering if for migration purposes, it wouldn’t be simpler to change the application on design.xwiki.org to add the decision field and to set it on the existing content where applicable. That way, we wouldn’t have two places to look for potential design/architecture decisions/proposals

#3

This part is especially important for my line of work here =) . Sometimes when revisiting past proposals I may not have the full context of their decisions, when they are available.