search

npryce / adr-tools

Command-line tools for working with Architecture Decision Records
Other
4.56k stars 578 forks source link

Create new ADRs in the "Proposed" state by default #61

Open npryce opened 6 years ago

npryce commented 6 years ago

Currently a new ADR is created in the Accepted state by default.

I suggest it is better to create new ADRs in the Proposed state. ADRs are meant to be discussed and agreed within a team. When team members are not all colocated, discussion can occur around or within the ADR document itself, until the team agree that the ADR is ready to be marked as Accepted.

This would also encourage teams to record proposed architecture decisions that are discussed and then rejected, along with the reasons for rejection.

retnuh commented 6 years ago

Makes sense to me. Another place we've seen discussion take place is on the PR for the ADR itself, but even then there was a "Proposal" phase that gets committed and a follow up with the relevant points from the discussion.

npryce commented 6 years ago

This is not as easy as I first thought. Some commands treat the status "Accepted" as a special case (e.g. adr-new with the -s option). They would have to be changed to support Proposed and Accepted, or be more general (e.g. assume that the first non-blank line of the Status section is the status, handle the case when that is a link, etc.

Any conventions like this should be made "official": see #60

simkimsia commented 5 years ago

Out of curiosity, how many states are there for ADR assumed by this tool and what are they? Btw, I like the idea of having a Proposed state by default.

All in all, I have seen Pending, Accepted, and Proposed. Are there more I'm not aware of?

npryce commented 5 years ago

At the moment it’s free-form apart from apart from Accepted and Superceded

On Thu, 17 Jan 2019 at 11:30, simkimsia notifications@github.com wrote:

Out of curiosity, how many states are there for ADR assumed by this tool? Btw, I like the idea of having a Proposed state by default.

— You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub https://github.com/npryce/adr-tools/issues/61#issuecomment-455139913, or mute the thread https://github.com/notifications/unsubscribe-auth/AADbm49aUOuzMRHeWJXpJ7A6tiRE6fMSks5vEF7dgaJpZM4U8IU5 .

simkimsia commented 5 years ago

At the moment it’s free-form apart from apart from Accepted and Superceded

May I suggest documenting this? I be happy to make a PR on the README

PeterMTaylor commented 5 years ago

This is a good idea. I guess for a use case example would be that all incoming work and their definitions for discussion for the next period/cycle of time would show proposed status which triggers discussion. Once the conversations are over, majority of the items becomes approved or rejected, any left over in proposed status shows up in the next period/cycle.