Quarto proposal

[jwindhager]

I've had a quick shot at a simple quarto-based page for tracking ADRs, as one potential way how we could structure things.

To be discussed at the meeting, therefore marking this as a draft PR.

To test locally, run:

quarto preview

Note, before merging this PR:

Before configuring the publishing action, it’s important that you run quarto publish gh-pages locally, once. This will create the _publish.yml configuration required by the subsequent invocations of the GitHub Action.

https://quarto.org/docs/publishing/github-pages.html#publish-action

[jhagberg]

This looks nice!

I have done some thinking about your suggestion to look at RFC process at https://ngff.openmicroscopy.org/rfc/1/index.html#implementation

Maybe we should have different tiers

like

Tier 1: Lightweight ADRs (Primary Workflow)

Use for: Most architecture decisions, project review outcomes, technical guidance
Process:

1. Issue created → Discussion (async, 1-2 weeks)
2. Draft ADR in PR → Review by board
3. Meeting decision (if needed) → Merge ADR
4. Auto-publish to GitHub Pages

Tier 2: RFC Process (When Needed)

Use for: Major cross-platform standards, significant specification changes, controversial decisions
Process:

1. RFC PR opened with template
2. Public comment period (2-4 weeks)
3. Stakeholder review (platforms, PMT, etc.)
4. Board discussion & decision
5. Merge → becomes standard
6. Auto-publish to GitHub Pages

When to use RFC instead of ADR:

• Affects ALL platforms significantly
• Requires broad stakeholder input
• Major breaking changes to existing standards
• New technical specifications (APIs, metadata schemas)

Tier 3: Quick Reviews (Lightweight)

Use for: Project consultation requests, clarifications, simple guidance

Process:

1. Issue with review template
2. Board member assigned
3. Async feedback (target: 2 weeks)
4. Meeting discussion if complex
5. Close issue with decision summary
6. Create ADR if precedent-setting

A suggestion for directory structure

architecture/
├── adr/                          # Architecture Decision Records
│   ├── 0001-use-rest-apis.md
│   ├── 0002-metadata-standard.md
│   └── template.md
├── rfc/                          # Request for Comments (major specs)
│   ├── 0001-federated-auth.md
│   ├── 0002-sample-tracking-api.md
│   └── template.md
├── reviews/                      # Project review outcomes
│   └── 2024-11-user-portal/
│       ├── request.md
│       ├── decision.md
│       └── meeting-notes.md
├── standards/                    # Current active standards
│   ├── api-guidelines.md
│   ├── metadata-schemas.md
│   └── integration-patterns.md
└── process/
    ├── adr-process.md
    ├── rfc-process.md
    └── review-process.md

[jwindhager]

Happy to adopt any structure/mode of operation. However, I would try to keep the number of tiers to a minimum and make the process(es) as simple as possible, to avoid procedural confusion or having to migrate requests between tiers.