feat: Propose keeping architecture design records for scaf.

[licquia]

This includes the actual ADR for this change, as well as the MADR template proposed for future ADRs.

[rochecompaan]

Before delving into specific concerns, it's important to note that Scaf is developed by a small team that generally agrees on what problems it should solve and how to solve them. To date, there have been very few, if any, disagreements about its architecture. This raises an important question: Are we looking to implement ADRs to solve a problem that doesn't actually exist in our current workflow?

While I appreciate the potential benefits of adopting ADRs for Scaf, particularly in terms of transparency and decision documentation, I have some concerns about the implementation:

1. Development Speed: Implementing ADRs may introduce additional administrative overhead, potentially slowing down our development process. We should consider whether the benefits outweigh this potential drawback for a project of Scaf's size and complexity.

2. Overlap with Existing Tools: Issues and pull requests already provide a mechanism for discussing and documenting changes to the project. While ADRs offer a more structured approach to architectural decisions, we should carefully consider how they would integrate with our existing workflow.

3. Accessibility: Issues and PRs provide a familiar interface for developers directly linked to the code. How can we ensure that ADRs are as accessible and integrated into our development process?

4. Scope and Threshold: If we adopt ADRs, we should clearly define what constitutes an "architectural decision" requiring an ADR. This will help prevent over-documentation of minor changes while ensuring important decisions are captured.

5. Maintenance: How will we ensure that ADRs remain up-to-date and relevant over time? Outdated ADRs could potentially lead to confusion.

6. Historical Context: Scaf is already a full-featured system without any existing ADRs. If we start implementing ADRs now, we need to address how we'll handle the lack of documentation for past decisions. This creates an imbalance where only new features will have ADRs to back them up, potentially leading to an incomplete or misleading architectural history.

While I see the value in ADRs, I believe we need to carefully consider these points to ensure their adoption would genuinely benefit Scaf without unduly burdening our development process. Perhaps we could consider the following options:

• A trial period to assess the impact of ADRs on our workflow
• A lightweight version of ADRs to start with
• A retrospective effort to document key historical decisions, ensuring a more complete architectural record
• Create an issue template that matches the structure of an ADR, allowing us to use our existing issue workflow for architectural decisions. This approach would ensure we continue using familiar tools while still capturing the essential information typically included in an ADR.

By addressing these concerns and considering these alternatives, we can make a more informed decision about whether and how to implement ADRs in the Scaf project. If we do decide to adopt them, we can ensure they provide maximum benefit with minimal disruption to our development process.

Ultimately, given the size and cohesion of our team, we should carefully evaluate whether formal ADRs are necessary or if our current system of issues and pull requests, perhaps with some minor adjustments, is sufficient for our needs.

[abosio]

I think our template, while largely the same with a few additions, turned out daunting and scary compared to Brian Okken's: https://github.com/okken/ok/blob/main/docs/adr/000-adr-template.md?plain=1&featured_on=pythonbytes

I know a lot of sections are marked as optional, but the visual impact of the giant template puts you in a different mindspace.

At least during a trial period, I think we should keep it very lightweight. We just need a few sentences covering the key points. I like Okken's template because I think it encourages that. This will also make is easier to add the ADRs for the project as it stands.

On Scaf in particular, I think this documentation – or something like it – is necessary not for our team but for developers we want to use Scaf. Currently, we don't explain Scaf's options or why we chose its ingredients in one place.

[clshaw01]

I agree w/Anthony and like the short and sweet template he linked.

What should our naming convention be for the files? Should we group into subdirs?

[rochecompaan]

What should our naming convention be for the files? Should we group into subdirs?

What do you think of using the lightweight ADR template as an issue template so we can use GitHub issue management to keep track of them and link PRs to them?

[abosio]

What do you think of using the lightweight ADR template as an issue template so we can use GitHub issue management to keep track of them and link PRs to them?

I would be ok with this if we can provide a single link from the documentation that gives a list of just the ADRs in some sensible order (which might not be date-based, because a semantic order might make more sense, such as big pieces to smaller pieces).

[ratmav]

i like the idea of a simple adr markdown template, with files under docs/adr, and for every significant (ymmv) decision we make, we add a new doc as we go. so, for example say we're considering swapping traefik for...idk nginx, then the end deliverable would be content in docs/adr/traefik_to_nginx_migration.md. the process to create the deliverable would start as a github issue on the project, and use the adr template as part of the issue description.

the reason i like this approach is that we get an adr in the end, which is pretty much a summary doc of what we decided, why we chose that option, and options we considered (what want to know most of the time and quick to read). along the way, we can use the github issue and pr as a way to track the discussion, and link the issue in the actual adr for a "more details" view on the decision.

[abosio]

@rochecompaan do you think a full "issue" workflow is necessary for these or is the PR process enough to distinguish a draft ADR from a final ADR?

[licquia]

I'll try refactoring my ADR into Brian Okken's template and the suggested location, and we can see if it works out better in practice.

[rochecompaan]

After some more thought about using GitHub issues, I'm again in favor of having an ADR docs dir so that we have markdown artifacts that are browsable offline rather than stored and viewed through proprietary GitHub services. This will give us the minimal PR workflow you're suggesting, @abosio.

[clshaw01]

I'm on board with the proposed changes, just a couple of additional thoughts/summary:

• The lightweight format will help us with workflow and not be too much of a bottleneck.
• Location of docs/decisions is ok; down the road we may want to categorize further into major components for ease of finding things if the volume gets large
• The PR process seems sufficient for managing the ADRs
• We may need to narrow the scope of what truly requires an ADR so we don't burden workflow on little things?
• We might want to list some of the bigger past decisions and get help documenting those for the team
• I'm still unclear on naming convention of the files so it's easy to read the list/find things

My concerns shouldn't prevent us from moving forward with this template format, so I'm approving.