Skip to content

Latest commit

 

History

History

adr

ADR

ADR stands for Architectural Decision Records and is a way to capture architectural decisions over time. This directory contains the ADR for the Quarkus Core project.

Proposing a new ADR

ADRs are contributed and edited using pull requests.

  • Create an asciidoc (.adoc) document in the adr directory named "n+1-my-adr-title.adoc", with n+1 the id. Use 4 digits as id (0001, 0002…​)

  • The document can be created by duplicating the 0000-template.adoc file. It is based on MADR.

  • The initial state of any ADR is proposed.

  • Once written, open a pull request to drive the discussion. Add the adr label to the pull request, as well as any related area labels.

  • Before merging the ADR pull request, update the state to accepted.

  • Email Quarkus Dev Mailing List to inform everyone about the new ADR.

The discussion around an ADR happens on the pull request. When the participant agrees, the ADR is marked as accepted, and the PR is merged. Be sure that all the members impacted by the ADR have the chance to read it. Typically, extension owners and knowledgeable people in this area should be involved in the discussion. If the participants disagree, the ADR is rejected, the pull request is closed.

ADR lifecycle

An ADR can have the following states:

  • proposed - Initial state

  • accepted

  • deprecated - The ADR is not applied anymore or is out of date

  • superseded - Another ADR replaces the current one. The ADR is updated with a link to the replacement.

IMPORTANT: Once accepted, an ADR is immutable. Only its status and date can be updated.

All modifications must be done through pull requests:

  • Deprecating an ADR should indicate the reason for the deprecation.

  • Superseding an ADR should be done in the same PR as the replacement ADR.