search

endjin / dotnet-adr

A cross platform .NET Global Tool for creating and managing Architectural Decision Records (ADRs).
https://endjin.com
Apache License 2.0
82 stars 10 forks source link

Clarify terminology for "repository" #227

Open nbarnwell opened 2 months ago

nbarnwell commented 2 months ago

Hello, me again. I'm just wondering, before I make a mistake, what this project means when the word "repository" is used?

Is it expected to mean:

  1. The git repository that the ADRs are being stored in (i.e. the folder containing the .git folder)?
  2. The folder containing the ADRs (bearing in mind it's possible to provide a path to almost anywhere within the working copy when creating new ADRs)?

My confusion comes from https://github.com/endjin/dotnet-adr/blob/main/Solutions/Endjin.Adr.Cli.Specs/Features/Init.feature, which I think makes it sound like "an ADR repository within a source code repository". But then, with that said, I don't see anywhere that actually creates a readme.md, so I can't tell if that is meant to go in the root of the git repo, or in the docs/adr folder?

HowardvanRooijen commented 2 months ago

Hey! Sorry for the delay. Gotta love overused terms! Yes adr repository is meant to signify whatever folder structure you create to contain the documents. I think the idea to have sensible defaults (or strong opinions weakly held) i.e. docs/adr which can easily be overridden or configured based on your org / team engineering practices / coding conventions.

The original motivation for creating this tool was that all the existing ADR tools were far too much "strong opinions, codified" for example there was only a single template and it was hard coded into the script / tool. I wanted people to adopt the process, but tailor it to their needs / existing processes / conventions / standard / repo structure.

Even across our own OSS estate we have a few different configurations:

And it wasn't until I published v1.0 that the notion that someone wouldn't want to build a nuget package to container their custom template, and instead they would want to point to a template within the adr repository.... 🤦

HowardvanRooijen commented 2 months ago

Oh and #228 lists a bunch of other good ideas that hadn't occurred to me, which dovetails into your mention of a readme.md...