Architecture Decision Records (ADRs)
Summary of architecture decisions guiding the middag-io organization's operations.
| ADR | Title | Context | Decision | Status |
|---|---|---|---|---|
| 001 | Naming Convention | GitHub lacks Bitbucket's project-level grouping for repositories. | Mandatory category prefixes per family (moodle-*, wp-plugin-*, docker-*, etc). | Accepted |
| 002 | Branch Model | Bitbucket repos used mixed branch models without standardization. | main (production) + develop (integration) + feature/* + hotfix/*, with release-please. | Accepted |
| 003 | Release Strategy | Versioning and changelogs need automation with support for different audiences. | release-please with Conventional Commits; commercial products maintain a separate CHANGELOG-USER.md. | Accepted |
| 004 | Migration Strategy | ~75 active Bitbucket repos need gradual migration to GitHub. | Immediate cutover per repo, no dual-remote; Bitbucket becomes read-only after migration. | Accepted |
| 005 | 1Password + GitHub Actions | CI/CD needs secure secrets access without long-lived PATs. | Hybrid model: Service Accounts per project in CI; 1Password Connect in production. | Accepted |
| 006 | Reusable Workflows | Pipeline duplication across repos causes drift and excessive maintenance. | Centralize reusable workflows; consuming repos use thin wrappers with config inputs. | Accepted |
| 007 | Docker Registry | Docker images need a registry for CI and deploys; current setup uses dual-push to GHCR + ECR. | GHCR as default; ECR optional via PUSH_TO_ECR variable, copied with crane copy. | Accepted |
| 008 | CI Base Image | Bitbucket required a custom Docker image; GitHub Actions provides native tooling. | No custom image; use GitHub Actions native setup with shivammathur/setup-php. | Accepted |
| 009 | AI Agent Policy | AI agents generate local state that can pollute repos and cause dev conflicts. | Don't version local agent state; mandatory gitignore; document required tools. | Accepted |
| 010 | 1Password Naming | Secrets for CI, servers, and local dev need consistent naming and access control. | Vaults CI-{PROJECT}, items {SERVICE}-{context}, fields snake_case EN; 3 consumption patterns. | Accepted |
| 011 | Docker + Dev Container | Docker projects need standardized setup for Dev Containers, CI, and production. | Multi-stage Dockerfile, base+override compose, toggleable Xdebug, secrets via 1Password. | Accepted |