Add support for Status

[koppor]

Michael Nygard's template offers a Status field. See http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions. This should be supported by MADR, too. It should, however, be optional or less prominent to make it easier for newcomers. Maybe two variants of MADR?

adr-tools offers automatic setting of the status field. MADR, however, does not want to rely on tooling: It should be possible to create an ADR by just using copy'n'paste of template.md.

[koppor]

Also add date:

Date	Status
2016-02-13	Accepted

| Date | Status |
| -- | -- |
| 2016-02-13 | Accepted |

[koppor]

That should be placed one line separated after the heading:

# Use Markdown Architectural Decision Records

| Date | Status |
| -- | -- |
| 2016-02-13 | Accepted |

Should we record the architectural decisions made in this project?
And if we do, how to structure these recordings?

[koppor]

Tooling support is provided at npryce/adr-tools#43. We "only" have to describe it in the README.md and possibly in the template.md file.

[pixelbrackets]

Hey,

I strongly support adding »status« and »date« information.

However I suggest using sections instead of tables. Tables in markdown are harder to edit, than just plain text. They limit the space for any further information (e.g. links to other documents, regarding the status). And any table should contain more than just 1 row imho.

Concerning the status field I suggest this:

Template
Right below the title, prior the User Story

**Status:** [Draft|Review|Accepted|Deprecated|Abandoned] - [optional addition like replacement ADR] <!-- optional -->

Example

Status: Deprecated - superseded by ADR 0001

Concerning the date field I suggest this:

Template
At the end of the document

*YYYY-MM-DD* <!-- optional -->

Example

2018-05-15

Edit: Oh, just recognised that npryce/adr-tools#43 implemented a MADR template which supports the table structure already. Sorry, I overlooked this issue. But shouldn’t any structure changes be documented in this repository first and then integrated into tools?

[koppor]

The experiment at npryce/adr-tools#43 was to see how the table works.

The initial status is not included in the template to keep it simple. I think that senior professionals are used to such flags, but beginners might be confused and lean against documenting something in MADR. Therefore, I wanted to keep the first lines of MADR pretty easy and the rest optional. We were also thinking of variants like template.md and template-full.md. May, template-lean.md and template-full.md. Maybe this could be a solution with both having newcomers not made afraid and professionals just using it?

There is a discussion going on whether a version control system solves the status of an ADR. Do git branches always correlate with the status of a document? Meaning, if one writes a specification using LaTeX in GitHub, does that file also need status flags?

I like your single status line. In the current version, we wanted to get rid of markdown emphasis such as **.

I wonder, what happens with multiple status lines? Like "refined-by", "see also", ...? I do not want to have multiple syntaxes for different cases. Therefore, the idea of the table was born. adr-tools just adds new lines at each status change. The user can then manually delete old status lines.

Regarding "Abandoned" and "Superseeded": In the former case, I would change the title of the ADR accordingly and keep the ADR itself in an updated state. Using a version control, one can dig deeper if one wants. If the abandoning is still interesting, it should be documented in the ADR why it was abandoned.

Similar for "Superseeded". The ADR should not kept as is, but modified according to the new setting. I am aware this could lead to inconsistencies. Especially, when embedded ADRs point to an ADR. However, keeping outdated ADRs might confuse readers...

[koppor]

Related question: How to structure "Context and Problem Statement" and "[decision drivers | forces | facing]". Currently, they are only placeholders without any format requirement. Reason was to keep the number of lines very low until "Considered Options". However, when filling out the template, one asks himself: How to write that down? Should we offer an extended format at template-full.md?

[pixelbrackets]

Followup to the tables issue: Another reason why I would reject tables. Both fields in the table are optional. If an integrator would document the status only, a table with 1 row and 1 column would occur. That should not be a table. And it is even harder to explain to people why they should use this wiki-like characters to build a table with one word.

Main reason why a single line or a section is better: The great advantage of markdown over other documentation formats like reST is the simple format. Easy to write AND easy to render. It is easy to parse a MD file and search for headlines or single fields. Eg. in my case I could build a web viewer which lists all ADRs with status "Draft" just by searching for "Status: [word]" right below the first headline. In a table with optional fields if have to write complex regex "If pipe with first word »Status« then use next line with first word… or of pipe with another pipe and second word is »Status« then…".

My Draft: https://github.com/pixelbrackets/madr/tree/20180215_status-field (or see https://github.com/pixelbrackets/madr/tree/1.3.1_patched)

[koppor]

I think @snisnisniksonah also had more effort when implementing the tables in adr-tools.

The idea was that status is not mandatory. The initial state is always "Accepted". When using adr-tools, the table is generated automatically and one "only" has to add | date | status |, which is easy to write, too 😇

In case we switch to a single-line status, what about linked issues? There can be multiple ones. E.g., "refined-by". Even "contradicts" could exist...

Then, we are back with a heading, which is IMHO disturbing, because the information below ## Status is IMHO more an administrative one in contrast to the Options and Pros and Cons.

[miwurster]

Hey,

what about using badges to visualize the current status?
Such as the build status of a project, we could simple put a "status" badge on top of each MADR.

Example:

[koppor]

+1 for badges

https://img.shields.io/badge/status-accepted-brightgreen.svg?style=flat-square

I am not sure how to deal with links. Think, we should introduce a separate ## Links section to make links explicit?

• Good, because plain markdown
• Bad, because relies on the online service https://shields.io or local badges have to be generated.

Example:

Use Angular

[koppor]

Summary:

Considered Options

• Use badge
• Use text line
• Use separate heading
• Use table

Pros and Cons of the Options

Use badge

Examples:

• 
• 

Pros/cons:

• Good, because plain markdown
• Good, because looks good
• Bad, because hard to read in markdown source
• Bad, because relies on the online service https://shields.io or local badges have to be generated
• Bad, because at local usages, many badges have to be generated (superseeded-by-ADR-0006, for each ADR number)
• Bad, because not easy to write

Use text line

Example: Status: Deprecated - superseded by ADR 0001

• Good, because plain markdown
• Good, because easy to write
• Good, because looks OK in both markdown-source (MD) and in rendered versions (HTML, PDF)
• Good, because no dependencies on external tools
• Good, because single line indicates the current state
• Bad, because "Status" line needs to be maintained
• Bad, because uses space at the beginning. When users read MADR, they should directly dive into the context and problem and not into the status

Use separate heading

Example:

• Good, because plain markdown
• Good, because easy to write
• Bad, because it uses much space: At least three lines: heading, status, separating empty line

Use table

Example:

• Good, because history can be included
• Good, because multiple entries can be made
• Bad, because not covered by the CommonMark specification 0.28 (2017-08-01)

[koppor]

Implemented. See also ADR-0008.