From 9e5cb6d28e8a98d16a093a254250d84be20fbc13 Mon Sep 17 00:00:00 2001 From: Jonas Hagberg Date: Wed, 26 Nov 2025 12:24:06 +0100 Subject: [PATCH 1/4] Add architecture question issue template and decision document for unified architecture request process --- .../ISSUE_TEMPLATE/architecture-question.md | 45 +++++++++ ...cess-approach-for-architecture-requests.md | 98 +++++++++++++++++++ 2 files changed, 143 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/architecture-question.md create mode 100644 docs/decisions/0003-use-single-process-approach-for-architecture-requests.md diff --git a/.github/ISSUE_TEMPLATE/architecture-question.md b/.github/ISSUE_TEMPLATE/architecture-question.md new file mode 100644 index 0000000..784c14d --- /dev/null +++ b/.github/ISSUE_TEMPLATE/architecture-question.md @@ -0,0 +1,45 @@ +--- +name: Architecture Question +about: Ask the architecture board for guidance or consultation +title: '' +labels: architecture-question +assignees: '' +--- + +## What do you need help with? + + + +## Context + + + +## What you've considered (optional) + + + +## Timeline + + + +## Additional Information + + + +--- + +💡 **Tip:** For urgent requests, add the `urgent` label. For decisions affecting all platforms, consider adding `high-impact`. + +🤝 **We're here to help!** Response time target: 2 weeks for initial feedback. + diff --git a/docs/decisions/0003-use-single-process-approach-for-architecture-requests.md b/docs/decisions/0003-use-single-process-approach-for-architecture-requests.md new file mode 100644 index 0000000..2ca1ef3 --- /dev/null +++ b/docs/decisions/0003-use-single-process-approach-for-architecture-requests.md @@ -0,0 +1,98 @@ +# 3. Use Single-Process Approach for Architecture Requests + +Date: 2025-11-26 + +## Status + +Accepted + +## Context + +Architecture governance can use tiered processes (Quick Reviews → ADRs → RFCs) where requesters must choose the appropriate tier. However, this creates: + +- Cognitive overhead: "Which tier is this?" +- Procedural confusion about process selection +- Need to migrate requests between tiers +- Higher barrier to asking questions + +We want to encourage early engagement before problems become expensive. + +## Decision + +Use a **single unified process** where formality emerges naturally from impact. + +**Process:** + +```mermaid +flowchart LR + A[Open Issue] --> B{Discussion
Time varies} + B -->|Simple| C[Close with
Answer] + B -->|Complex| D[Create ADR PR] + D --> E[Publish] + + style A fill:#e1f5ff + style D fill:#fff4e1 + style E fill:#e8f5e9 +``` + +**Key insight:** Same process, different discussion length based on natural impact. + +**Label:** `architecture-question` + +**Optional:** `high-impact`, `urgent` + +## Rationale + +**Single process eliminates confusion:** + +- No tier selection needed +- No migrations between systems +- Natural scaling based on impact + +**Formality emerges from context:** + +| Impact | Discussion | Outcome | +| ------ | ---------- | --------------- | +| Low | 3-5 days | Answer in issue | +| Medium | 1-2 weeks | Likely ADR | +| High | 2-4 weeks | Definitely ADR | + +**"Question" lowers barrier:** + +- Less intimidating than "decision" +- Encourages early consultation +- Welcomes exploratory discussion + +## Consequences + +**Positive:** + +- Simple for requesters +- Lower barrier to engagement +- Fast for simple questions +- Still rigorous for important decisions +- Everything transparent (issues + ADRs) + +**Negative:** + +- Less formal than traditional governance +- Board must identify when to create ADR + +**Implementation:** + +- Issue template: `architecture-question` +- Process docs emphasize "ask early, ask often" +- ADRs for precedent-setting decisions only + +## Alternatives Considered + +**Three-tier system:** Clear separation but high cognitive overhead + +**ADR-only:** Everything documented but too slow for simple questions + +**RFC-heavy:** Very formal but overkill for our multi-project context + +## References + +- [OME-NGFF RFC Process](https://ngff.openmicroscopy.org) +- [ADR GitHub Repository](https://adr.github.io/) From 63b8b122be4db4c7ba3d66b1d52f2c84a3a4b422 Mon Sep 17 00:00:00 2001 From: Jonas Hagberg Date: Wed, 26 Nov 2025 12:32:19 +0100 Subject: [PATCH 2/4] Add issue template configuration for architecture inquiries and direct contact options --- .github/ISSUE_TEMPLATE/architecture-question.md | 1 + .github/ISSUE_TEMPLATE/config.yml | 8 ++++++++ 2 files changed, 9 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/config.yml diff --git a/.github/ISSUE_TEMPLATE/architecture-question.md b/.github/ISSUE_TEMPLATE/architecture-question.md index 784c14d..e7edcc2 100644 --- a/.github/ISSUE_TEMPLATE/architecture-question.md +++ b/.github/ISSUE_TEMPLATE/architecture-question.md @@ -43,3 +43,4 @@ We're here to help you think through it. 🤝 **We're here to help!** Response time target: 2 weeks for initial feedback. + diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..9afb0de --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,8 @@ +blank_issues_enabled: true +contact_links: + - name: 📚 Documentation + url: https://scilifelab.github.io/architecture/ + about: Read our process documentation and existing decisions + - name: 💬 Direct Contact + url: mailto:architecture@scilifelab.se + about: Email the architecture board directly From 97e5935b55a47cd31a7458ed328e15009c62880a Mon Sep 17 00:00:00 2001 From: Jonas Hagberg Date: Tue, 9 Dec 2025 12:19:47 +0100 Subject: [PATCH 3/4] Update title of architecture decision record to include ADR prefix for consistency --- ...003-use-single-process-approach-for-architecture-requests.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/decisions/0003-use-single-process-approach-for-architecture-requests.md b/docs/decisions/0003-use-single-process-approach-for-architecture-requests.md index 2ca1ef3..43304cf 100644 --- a/docs/decisions/0003-use-single-process-approach-for-architecture-requests.md +++ b/docs/decisions/0003-use-single-process-approach-for-architecture-requests.md @@ -1,4 +1,4 @@ -# 3. Use Single-Process Approach for Architecture Requests +# ADR-0003. Use Single-Process Approach for Architecture Requests Date: 2025-11-26 From 0372db97c29df3934f3b0ab1e5c60b75ed75124e Mon Sep 17 00:00:00 2001 From: Jonas Hagberg Date: Wed, 10 Dec 2025 12:08:56 +0100 Subject: [PATCH 4/4] Refine architecture question issue template by updating title and assignees fields for consistency, and adding additional example questions to guide users in seeking architectural guidance. --- .github/ISSUE_TEMPLATE/architecture-question.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/architecture-question.md b/.github/ISSUE_TEMPLATE/architecture-question.md index e7edcc2..dac83ac 100644 --- a/.github/ISSUE_TEMPLATE/architecture-question.md +++ b/.github/ISSUE_TEMPLATE/architecture-question.md @@ -1,14 +1,14 @@ --- name: Architecture Question about: Ask the architecture board for guidance or consultation -title: '' +title: "" labels: architecture-question -assignees: '' +assignees: "" --- ## What do you need help with? - ## Context @@ -24,7 +28,7 @@ Examples: ## What you've considered (optional) - @@ -42,5 +46,3 @@ We're here to help you think through it. 💡 **Tip:** For urgent requests, add the `urgent` label. For decisions affecting all platforms, consider adding `high-impact`. 🤝 **We're here to help!** Response time target: 2 weeks for initial feedback. - -