From dbaacfe9812977f982aa33c12586b18640f8d8c9 Mon Sep 17 00:00:00 2001 From: Brendan Kowitz Date: Tue, 28 Jan 2025 14:36:46 -0800 Subject: [PATCH 1/3] Adds ADR readme --- docs/arch/Readme.md | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) create mode 100644 docs/arch/Readme.md diff --git a/docs/arch/Readme.md b/docs/arch/Readme.md new file mode 100644 index 0000000000..5c58bb3271 --- /dev/null +++ b/docs/arch/Readme.md @@ -0,0 +1,28 @@ +# Architecture Decision Records + +We will maintain Architecture Decision Records (ADRs) in our FHIR Server repository, placing each one under `doc/arch/adr-<000>-.md`. We have chosen to write these records using Markdown. + +Each ADR will be assigned a unique, sequential number that will never be reused. If a decision is later reversed, changed or evolved, the original record will remain in place but will be marked as superseded. Even though it’s no longer valid, it is still historically important. + +We will keep the ADR structure simple, with just a few sections in this example template: + +``` + +# Title + Each ADR should have a short, descriptive phrase, such as “ADR 001: Database Schema Changes for Version 1.5.0” or “ADR 009: Introducing Polly for Retry Logic”. + +## Context + Summarize the relevant factors (technological, organizational, or other) that influence this decision. Present these factors neutrally, highlighting any tensions or constraints that shaped the solution. + +## Decision + Clearly state the chosen approach or solution in active voice (for example, “We will…”). Describe the rationale and what will be implemented as a result. + +## Status + Indicate whether this decision is proposed, accepted, deprecated, or superseded (with a reference to the new ADR if applicable). + +## Consequences + Outline the outcomes of applying this decision. Include all effects—beneficial, adverse, or neutral—since these will affect the project over time. + +``` + +This is inspired by [documenting architecture decisions](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions). \ No newline at end of file From c6ac592b7db5d7bbff7bb20eb47e377b61b46a8c Mon Sep 17 00:00:00 2001 From: Brendan Kowitz Date: Tue, 28 Jan 2025 16:21:13 -0800 Subject: [PATCH 2/3] Date based adr number --- docs/arch/Readme.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/arch/Readme.md b/docs/arch/Readme.md index 5c58bb3271..3162149046 100644 --- a/docs/arch/Readme.md +++ b/docs/arch/Readme.md @@ -1,8 +1,8 @@ # Architecture Decision Records -We will maintain Architecture Decision Records (ADRs) in our FHIR Server repository, placing each one under `doc/arch/adr-<000>-.md`. We have chosen to write these records using Markdown. +We will maintain Architecture Decision Records (ADRs) in our FHIR Server repository, placing each one under `doc/arch/adr--.md`. We have chosen to write these records using Markdown. -Each ADR will be assigned a unique, sequential number that will never be reused. If a decision is later reversed, changed or evolved, the original record will remain in place but will be marked as superseded. Even though it’s no longer valid, it is still historically important. +Each ADR will be assigned a unique, sequential number (date based as above) that will never be reused. If a decision is later reversed, changed or evolved, the original record will remain in place but will be marked as superseded. Even though it’s no longer valid, it is still historically important. We will keep the ADR structure simple, with just a few sections in this example template: From 3ddf174853ceced25b2c0e1a88fdec7fdb4cb296 Mon Sep 17 00:00:00 2001 From: Brendan Kowitz Date: Wed, 29 Jan 2025 13:53:05 -0800 Subject: [PATCH 3/3] Update PR template --- .github/pull_request_template.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 660a239e56..b2048247b0 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -13,8 +13,9 @@ Describe how this change was tested. - Tag the PR with the type of update: **Bug**, **Build**, **Dependencies**, **Enhancement**, **New-Feature** or **Documentation** - Tag the PR with **Open source**, **Azure API for FHIR** (CosmosDB or common code) or **Azure Healthcare APIs** (SQL or common code) to specify where this change is intended to be released. - Tag the PR with **Schema Version backward compatible** or **Schema Version backward incompatible** or **Schema Version unchanged** if this adds or updates Sql script which is/is not backward compatible with the code. +- When changing or adding behavior, if your code modifies the system design or changes design assumptions, please create and include an [ADR](https://github.com/microsoft/fhir-server/blob/main/docs/arch). - [ ] CI is green before merge [![Build Status](https://microsofthealthoss.visualstudio.com/FhirServer/_apis/build/status/CI%20Build%20%26%20Deploy?branchName=main)](https://microsofthealthoss.visualstudio.com/FhirServer/_build/latest?definitionId=27&branchName=main) -- Review [squash-merge requirements](https://github.com/microsoft/fhir-server/blob/master/SquashMergeRequirements.md) +- Review [squash-merge requirements](https://github.com/microsoft/fhir-server/blob/main/SquashMergeRequirements.md) -### Semver Change ([docs](https://github.com/microsoft/fhir-server/blob/master/docs/Versioning.md)) +### Semver Change ([docs](https://github.com/microsoft/fhir-server/blob/main/docs/Versioning.md)) Patch|Skip|Feature|Breaking (reason)