Decision Logs

Decision Logs

QQQ 4.0 release. Final 4.0.0 is available. See QQQ 4.0 for release scope and migration guidance.

QQQ uses Architecture Decision Records (ADRs) to document important technical decisions. This keeps our small team aligned and provides a searchable history of why we made certain choices.

Quick Links

• Home
• Team Roles
• Contribution Guidelines
• Feature Development
• High-Level Architecture

What Are ADRs?

Architecture Decision Records are short documents that capture:

• What we decided
• Why we made that choice
• What the consequences are
• When we made the decision

Purpose: Help us remember why we chose certain approaches and avoid repeating past mistakes.

When to Create an ADR

Create ADR For:

• Breaking changes that affect users
• New architectural patterns we're introducing
• Technology choices (new frameworks, libraries)
• Performance optimizations that change behavior
• API design decisions that affect external users
• Database schema changes that impact data structure

Don't Create ADR For:

• Bug fixes and small improvements
• Code refactoring that doesn't change behavior
• Documentation updates
• Test improvements
• Minor dependency updates

ADR Process

Simple Workflow

1. Identify need - Something important needs deciding
2. Create ADR - Use the template below
3. Discuss - Team reviews and gives feedback
4. Update - Incorporate feedback and finalize
5. Implement - Execute the decision
6. Review - Update status as we learn more

Team Involvement

• Proposer: Creates the ADR and drives discussion
• Team: Reviews, asks questions, suggests alternatives
• Decision: Record the decision and its approving maintainers in the relevant issue or ADR
• Documentation: Update status and add lessons learned

ADR Index

ADR	Title	Status	Date
ADR-001	Pluggable Themes for Material Dashboard	Accepted	2024-12-28

ADR Template

File Naming

ADRs are wiki pages named: ADR-XXX-Short-Title.md

Examples:

• ADR-001-Pluggable-Themes.md
• ADR-002-Maven-Module-Structure.md
• ADR-003-Javalin-HTTP-Server.md

Template Content

# ADR-XXX: [Short, Clear Title]

**Status**: Proposed | Accepted | Superseded | Deprecated  
**Date**: YYYY-MM-DD  
**Deciders**: [Names of team members involved]  
**Tags**: [architecture, performance, breaking-change, etc.]

## Context

[What problem are we solving? What constraints exist? What forces are at play?]

## Decision

[What did we decide? Be specific and clear.]

## Rationale

[Why did we choose this option? What alternatives did we consider?]

## Consequences

### Positive
- [What good things will happen?]

### Negative  
- [What problems might this cause?]

### Neutral
- [What won't change?]

## Implementation

[How will we implement this? What steps are needed?]

## Status

[Current status and any updates since the decision was made.]

Example ADR

Illustrative template: Maven Module Structure

Status: Accepted
Date: 2024-01-15
Deciders: QQQ Team
Tags: architecture, build-system

Context: QQQ needs a clear module structure that supports independent development while maintaining consistency.

Decision: Use Maven parent-child structure with revision property for version management.

Rationale: Maven's module system provides dependency management, while revision property enables automated versioning in CI/CD.

Consequences:

• Positive: Consistent versions across modules, automated CI/CD integration
• Negative: More complex build setup, requires Maven 3.8+
• Neutral: Standard Maven practices

Managing ADRs

Wiki Organization

All ADRs live in the wiki as pages named ADR-XXX-Short-Title. The ADR Index above tracks all decisions.

Status Tracking

• Proposed: Under discussion
• Accepted: Decision made, ready to implement
• Superseded: Replaced by newer decision
• Deprecated: No longer relevant

Best Practices

Writing Good ADRs

• Be concise - One page maximum
• Focus on why - Not just what we decided
• Include alternatives - Show what we considered
• Update status - Keep current as we learn

Keeping ADRs Current

• Review regularly - Check if decisions still make sense
• Update status - Mark superseded or deprecated
• Add lessons learned - What worked, what didn't
• Archive old ones - Move to separate folder

Team Process

• Create when needed - Don't force ADRs for everything
• Discuss as team - Get input from everyone
• Reference in code - Link ADRs to implementation
• Learn from outcomes - Update based on results

Integration with Workflow

Feature Development

• Big changes: Create ADR first
• Implementation: Reference ADR in PRs
• Review: Check if ADR is still valid

Code Review

• Check ADRs: Are we following documented decisions?
• Update if needed: Has the decision changed?
• Reference: Link PRs to relevant ADRs

Release Planning

• Review ADRs: What decisions affect this release?
• Breaking changes: Are they documented in ADRs?
• User impact: What decisions affect users?

See Also

• Team Roles - Team structure
• Contribution Guidelines - PR process
• High-Level Architecture - Architecture