joshrotenberg / adrs Goto Github PK

It would be cool if maybe MADR was also built in and selectable via a flag/env variable as the default, as well as pointing to a custom template. I have some basic ideas around this, but there are probably some cases that are trickier than I think they'll be (for example, supporting nested files/directories).

I'm hoping to deprecate this in favor of something like an environment variable such as ADRS_DIRECTORY, but in the meantime, I see a bug where reading the string read from the file doesn't get the newline trimmed, and hence adrs doesn't think the directory exists. This definitely happens in the new command, so the short term fix is to trim whatever is read. This file gets read enough that the call should get abstracted out into adrs.rs at the very least.

adr-tools has a suite of tests here: https://github.com/npryce/adr-tools/tree/master/tests

adrs should probably be able to pass most or all of them. Integrate them here somehow, either as a rewrite into rust or by calling adrs directly.

https://docs.brew.sh/Formula-Cookbook

For example, the format of a link for the new command isn't currently documented.

Need to write a function to remove the Accepted line.

Errors are kinda weak, lots of unwraps that could at least be expect.

Right now the new command sets the status to Accepted. It might make sense to allow an optional config to set this to something like Pending first.

adrs-tools new first will create doc/adr/0001-first.md if a) no doc/ already exists and b) no .adr-dir file is present.

Some lint ideas:

• Lint the markdown
• Validate that file numbering is unique.
• Validate file names (i.e. everything should have a 4 digit id padded with zeros).
• Validate that the .adr-dir and the ADR directory match
• Validate that all ADRs have at least one status
• Validate links between ADRs

I picture this using mdBook to dynamically open and serve the ADR directory in a book format.

I'd like to keep the README and in-app docs simple. There should be a more complete documentation site deployed to GitHub pages with some basic information about the tool and ADRs, and documentation and examples for all of the commands.

adr-tools creates the .adr-dir file on init and then uses that for subsequent runs to decide where to put/get ADRs. This works fine, and I've reproduced this behavior in adrs, but I think it would be cleaner to use a global flag tied to an environment variable, as well as just use the docs/adr as a default everywhere.

The flow would be something like this:

• If no .adr-dir exists, and no docs/adr exists, default to docs/adr without writing a .adr-dir file
• If the global --directory flag is set for any command, use that value for all operations, even if a .adr-dir exists.
• If the ADR_DIRECTORY environment variable is set, use that value for all operations even if a .adr-dir exists.
• If no .adr-dir exists but the docs/adr directory does exist, use the docs/adr directory.

I think this covers most potential situations while maintaining backwards compatibility and keeping sane defaults.

Steps off the top of my head:

1. Add the directory flag in main.rs as a global flag, with the env marker to also pull it from the environment.
2. Process the flag before calling the subcommand, and pass the directory value to any subcommand as a Path (or maybe PathBuf?).
3. Change anything that uses .adr-dir now to always use that value.

I split the new and init templates but it would be a lot cleaner to support a single file, and make more sense for custom templates.

The template ends up with extra new lines because of the templating stuff for supercedes and links.