Architecture Decision Records

[shendaras]

Hello,

As someone who is interested in this project but hasn't followed it in great detail, I've had trouble determining what the current design looks like. For example, I was reviewing issues involved with the structure/format of the Manifest file and came away a bit confused. At one point, it appeared that the dep command itself was supposed to handle the file programmatically but later on it appears the design changed and the Manifest file was meant to be created by dep and then maintained by hand.

The decision involving the switch between two different approaches to the Manifest file happened elsewhere and it isn't clear to me where to go to find the latest. One thing that I've found helpful in the past is the use of "Architecture decision records" which are committed with the project. Here's a link to an informative blog post about them: http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions . Additionally, there's some tooling others have developed to make working with ADRs a bit easier: https://github.com/npryce/adr-tools

What are the thoughts about incorporating ADRs or something like them to help keep the current design clear to everyone, especially newbies who might be looking for ways to help out?

[sdboyer]

Interesting. I hadn't heard about ADRs before.

I completely agree that following the architectural path - generally, knowing what is correct and intended - is difficult. Getting the roadmap together was one important step in getting the project better organized, but is quite orthogonal to the purpose ADRs seem to serve. And I care tremendously about making this a project that [new] folks feel able to contribute to.

The only problem I see is that the maintainers here are already pretty stretched, and adding another meta-responsibility like this isn't easy. So, basically, I'm fine to try to abide by this, but it'd be a lot easier if someone else - perhaps you, since you're familiar with them? 😄 - could at least help guide, initially.

Note also that I expect we'd abandon the ADR model if/when dep makes it into the toolchain.

[sdboyer]

While this seems like it could add value, I just don't think we have the bandwidth to do it ourselves. What I'm doing for #294 will have to suffice, at least for now.

Closing this out.