npryce / adr-tools Goto Github PK
View Code? Open in Web Editor NEWCommand-line tools for working with Architecture Decision Records
License: Other
Command-line tools for working with Architecture Decision Records
License: Other
Hi @npryce , I discovered your adr-tools via ruthmalan. And now successfully using it in 3 existing projects and going on for more.
I like to ask if there's a way for me to change the default 0001 decision script without changing the code. Not looking to remove your existing content. but just to add 2 or 3 extra lines unique to my company under decision and context section.
Let me know roughly how and I be happy to try to make this my first contribution to your wonderful tool.
Thank you π with much β€οΈ for your ADR tools π
Something like this installs it
class AdrTools < Formula
desc "A command-line tool for working with Architecture Decision Records (ADRs)."
homepage "https://github.com/npryce/adr-tools"
url "https://codeload.github.com/npryce/adr-tools/tar.gz/1.0.0"
sha256 "ceeba995d2319ba2735dd3c613bf145070efb8984886887a9edde7d498354b4b"
def install
bin.install Dir["src/*"] - Dir["src/*.md"]
end
test do
system "true"
end
end
Hi there,
I love this project and want to use it internally. We like to use adoc (asciidoctor) and judging from some time I spent reading the source code it seems pretty simple to support an alternative format. Would you be interested in accepting a PR that adds support for arbitrary extensions, so we (and others) can use the markup language we feel comfortable with?
GitHub pages allows for publishing websites on github. As source, they have following sources
gh-pages
branch, folder /
master
branch, folder /
master
branch, folder /docs
. - https://help.github.com/articles/configuring-a-publishing-source-for-github-pages/#publishing-your-github-pages-site-from-a-docs-folder-on-your-master-branchNote the s
in the folder name.
In the (unrelated) project Eclipse Winery, the homepage is rendered from docs/
. The ADRs are placed into the folder docs/adr
. As a consequence, the ADRs are browsable in the homepage: http://eclipse.github.io/winery/adr/
In case the ADRs resided in doc/adr
, there would be two folders, docs/
for the whole homepage and doc/adr
for all the ADRs.
Therefore, I propose to rename the folder doc
to docs
. I would submit a pull request, but seeing a nice test coverage (refs #30 (comment)), I would only start if this is a consensus to rename the directory.
Would be nice, for reasons of language for example
It'd be great if the app could be downloaded as a single binary, like the ones provided by an AppImage.
I found this repository via a link from the latest ThoughtWorks tech radar. Congrats on the publicity--I hope you enjoy some internet popularity because of it.
I was a little confused by the format of dates in the generated markdown files. Being in the United States, I'm used to seeing mm/dd/yyyy instead of dd/mm/yyyy. When I first read 0001-record-architecture-decisions.md, I thought the file was dated in the future.
Since ADR is a communication tool, it should be as unambiguous as possible. With that goal in mind, I think it makes sense to follow the ISO 8601 recommendations for date formatting--yyyy-mm-dd.
I see that it's possible to override the default date format via config.sh, but I still think it makes sense for the tool's default to be the ISO standard--it would make the tool friendlier to adopt, and save new users some head-scratching.
Hi, I am unable to get adr-tools working with cmder on Windows 10. Is it supported?
ad-help changed in 2.2.0 to use PAGER:-more which results in more command not available error when using Git Bash on Windows. Prior to this it did work.
I get the following issue when I call the adr
command:
usage: /usr/bin/adr-help COMMAND [ARG] ...
COMMAND is on of:
find: invalid mode β+111β
Run 'adr help COMMAND' for help on a specific command.
Though unrelated in terms of hardware, I attempted the fix outlined here. And after making the following changes everything seems to work as it should.
diff --git a/src/_adr_commands b/src/_adr_commands
index f70dc86..df6c5d5 100755
--- a/src/_adr_commands
+++ b/src/_adr_commands
@@ -2,4 +2,4 @@
set -e
source "$(dirname $0)/config.sh"
-(cd "$adr_bin_dir" && find . -name 'adr-*' -perm +111) | cut -c 7-
+(cd "$adr_bin_dir" && find . -name 'adr-*' -perm /111) | cut -c 7-
diff --git a/src/adr-generate b/src/adr-generate
index cee7767..221897c 100755
--- a/src/adr-generate
+++ b/src/adr-generate
@@ -13,7 +13,7 @@ cmd=$1
if [ -z $cmd ]
then
- (cd "$adr_bin_dir" && find . -name '_adr_generate_*' -perm +111) | cut -c 17-
+ (cd "$adr_bin_dir" && find . -name '_adr_generate_*' -perm /111) | cut -c 17-
else
"$adr_bin_dir/_adr_generate_$cmd" "${@:2}"
fi
The output of find --version
is the following:
find (GNU findutils) 4.6.0
Copyright (C) 2015 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
Written by Eric B. Decker, James Youngman, and Kevin Dalley.
Features enabled: D_TYPE O_NOFOLLOW(enabled) LEAF_OPTIMISATION FTS(FTS_CWDFD) CBO(level=2)
I am running Arch Linux x86_64 with kernel 4.5.4-1-ARCH.
I am not sure what source of this issue is but thought that it would be useful to have an issue and a solution for anyone else that comes by this problem.
@npryce @npryce-springer are you still maintaining this tool? Do you want or need help with reviewing & merging pull requests?
I am noticing a steady influx of unaddressed PRs. I was packaging this script for NixOS. That made me curious whether there is enough momentum on this project to keep it well maintained.
Doing an adr init
with a path that has spaces in it fails; then uses the default.
:~$ mkdir path\ with\ spaces
:~$ cd path\ with\ spaces/
:~/path with spaces$ adr init
/usr/local/Cellar/adr-tools/3.0.0/bin/_adr_dir: line 16: [: too many arguments
doc/adr/0001-record-architecture-decisions.md
Refer to Homebrew/homebrew-core#3947 for details.
I'd like to output the TOC to an MD file on root of project, but links to the MD files are made so that file would have to be in the decisions dir itself.
I.e.
* [1. Record architecture decisions](0001-record-architecture-decisions.md)
I'd like a flag in generate toc
to generate links with the decisions dir added, or perhaps relative to the current folder, or as a string to prefix every path. Which (if any) do you prefer?
I.e.
* [1. Record architecture decisions](decisions/0001-record-architecture-decisions.md)
(and thanks for making the tool, it's fun and useful :)
Hi,
I am not finding any userful resource to setup ADR tools on windows system. Can you please point me to the right documentation..
Thanks,
Hari
On the INSTALL.md, it states that this can be installed with brew install olleolleolle/adr-tools/adr_tools
, but this throws the error:
Error: inreplace failed
src/adr-init:
expected replacement of "/usr/local/Cellar/adr_tools/2.0.0/config.sh" with "/usr/local/Cellar/adr_tools/2.0.0/bin/config.sh"
I'm guessing this is due to config.sh
being removed in 2.0.0
. It might be worth removing the brew command, or linking to a working variant? I think there is a working tap by @olleolleolle https://github.com/olleolleolle/homebrew-adr-tools. I've not tried it though, so maybe it doesn't.
Currently the Table of Contents title is hard coded. Being able to change this would be advantageous where others may want the project name instead, especially as this is always before the intro
contents.
https://github.com/npryce/adr-tools/blob/master/src/_adr_generate_toc#L47
Overwriting with -t
or a similar arg could be used to achieve this.
Support autocompletion of adr
sub-commands and options in the Bash shell.
See https://en.m.wikipedia.org/wiki/ICalendar
This would allow project history to be visualised in calendar apps
I've been assessing the tool (great work!) and found that it took me a while to discover the format of the generate graph option. I had to run adr help generate graph
in order to find it, but took me a while to realise that there was help for generate graph and generate toc independently.
Maybe split the actions into adr graph and adr toc?
Env vars, default pager etc
In a larger organization it could be useful to collect ADR files from different projects (maintained by different teams) and 'publish' them on some central WEB portal for visibility.
Did anyone thought / implemented something like that?
While browsing the ADR for ISO date format, I noticed the card itself wasn't using that format:
https://github.com/npryce/adr-tools/blob/master/doc/adr/0008-use-iso-8601-format-for-dates.md
# 8. Use ISO 8601 Format for Dates
Date: 21/02/2017
Have you run upgrade-repository
on this repo?
Having a file like .adr-dir
at the root of a repo is somewhat of a thorn in the eye of people trying to keep the root of their repo as clean/approachable as possible.
Instead of configuring adr-tools
using files it would be nice if we could use an env var to specify the ADR dir. By allowing that users could easily wrap adr
itself in scripts which configure it in whatever way desired.
Would you be open for a PR that enables setting the ADR dir via an env var?
$ADR_DIR
.adr-dir
file but not super important to our specific use.I created a adr-tools plugin for asdf-vm and have an opened PR to register it.
asdf gives osx and linux users (ci jobs) a 'universal' path to managing tool versions. Anyone care to test it out? especially osx users? Here is a quicky, but read the asdf README.md too. Once the asdf-plugin PR is approved, the git urls will not be needed:
$ asdf plugin-add adr-tools https://gitlab.com/td7x/asdf/adr-tools
$ asdf list-all adr-tools
$ asdf install adr-tools 2.0.1
$ asdf (global | local) adr-tools 2.0.1
$ adr
It would be nice to have others try it out and make sure it works beyond my pipeline & computer.
If I create a decision by mistake should I manually delete the decision document or there is a command for that?
This is a feature request.
Overload template file name and directory file name with arguments.
Use case would be to use adr
command to manage other type of markdown files, e.g.:
alias prd='adr --template-file prd_template.md --dir-file .prd-dir'
This way we could create PRD files with the very same tool while steel being able to create ADR files:
adr new Use adr-toolset to manage PRDs as well
prd init doc/architecture/drivers/
prd new Needs to be testable
prd new Needs to be expandable
prd link 1 "Mentioned in" 2 "Can't break"
adr list # lists existing ADR documents
prd list # lists existing PRD documents
... to report the location of the ADR directory relative to the current working directory.
Useful for writing scripts that manipulate ADRs, Makefiles for publishing ADRs, etc.
I understand that adr generate toc
outputs its content to stdout for deployment scriptability.
But on the other hand, I like adr-log's -i
parameter which generates directly the index.md
file.
I propose to create a new command: adr generate index
which accepts the same parameters as adr generate toc
.
This command would call _adr_generate_toc
and _adr_dir
to create an index.md
directly in the adr directory.
For small projects, when you don't want to setup deployment scripts for your doc, I think it simplifies the process:
adr new ...
adr generate index
git commit
versus:
adr new ...
adr generate toc > docs/adr/index.md
git commit
Eventually, you can add adr generate index
to a pre-commit hook ;)
If you are OK with this issue, I can work on a pull request.
Github users have been conditioned to look for shields.io tags as a quick way to understand the state of a repo. It'd be great if the Status section that is generated could replace the STATUS with a shields.io image instead of using just plain text.
For clarity I'm thinking of a command line switch:
adr --shields new URL Scheme
adr --shields new -s 1 Updated URL Scheme
I hastily made a PR to the homebrew package, without testing. Silly me.
On closer inspection, it looks like adr-config needs to be executable.
Otherwise I get:
> adr upgrade-repository
/opt/boxen/homebrew/bin/adr: line 3: /opt/boxen/homebrew/bin/adr-config: Permission denied
I would make a PR, but I've broken enough things for one day. Will test again tomorrow.
I just tried using an alternative dir as suggested in the tests, however the dir was ignored, and the default used:
$ brew install olleolleolle/adr-tools/adr_tools
==> Installing adr_tools from olleolleolle/adr-tools
==> Downloading https://codeload.github.com/npryce/adr-tools/tar.gz/1.1.0
$ adr init alternative-dir
doc/adr/0001-record-architecture-decisions.md
Chrome's certificate warnings, and cross-site request blocking prevents many users from reading the original text.
Providing a different perspective on the feature request in #51
We're looking into using this tool to manage a centralised adr repository for adrs spanning multiple repos and teams.
For organisational purposes we would like to reflect our internal team structure through the usage of (sub-)directories.
Would it be possible to have the adr new
command accept a relative path to the root (where adr init
was run/where .adr-dir points to).
I do recognise this would probably create problematic interactions with the link and supersede functionality but I'm open for a discussion on those potentially problematic areas.
Hello
I wonder if it would be possible to configure the date format ? I would like use a dd/MMM/yyyy format, which will be less confusing for my team.
I see there is a sort of config file, could we add the date format here ? Does it make sense ?
I can work on the code, but I would need some guidances to know if it's make sense and if I pinpoint the impacted file(s) :)
Hi I am managing a folder structure as belows:
doc > architecture > front-end
doc > architecture > back-end
Every time I use adr new I had to overwrite .adr-dir file.
Is there a way to accommodate multiple folder structure.
See issue #1 for an example why this is needed.
Current thoughts:
Have a config.sh
file that is sourced at the top of every script, and defines location of files.
E.g.:
#!/bin/bash
set -e
source $(dirname $0)/config.sh
...
And config.sh would define shell variables (not environment variables). The default would be:
adr_bin_dir="$(dirname $0)"
adr_template_dir="$adr_bin_dir"
Packaging scripts could replace the entire file. E.g.
adr_prefix=/usr/local
adr_bin_dir=$adr_prefix/bin
adr_template_dir=$adr_prefix/share/adr-tools/templates
Comments from packaging experts welcome.
After installing adr to /opt/adr-tools/1.2.0/
on Ubuntu 16.04 and running adr
, the following error is shown:
usage: /opt/adr-tools/1.2.0/adr-help COMMAND [ARG] ...
COMMAND is one of:
find: invalid mode β+111β
Run 'adr help COMMAND' for help on a specific command.
After running sudo sed -i 's@-perm +111@-perm /111@' /opt/adr-tools/1.2.0/*
, running adr
produces:
usage: /opt/adr-tools/1.2.0/adr-help COMMAND [ARG] ...
COMMAND is one of:
init
new
generate
help
list
Run 'adr help COMMAND' for help on a specific command.
http://man7.org/linux/man-pages/man1/find.1.html sayeth:
The syntax -perm +MODE was removed in findutils-4.5.12, in favour of
-perm /MODE. The +MODE syntax had been deprecated since
findutils-4.2.21 which was released in 2005.
On my system, find --version
gives find (GNU findutils) 4.7.0-git
The linux toolset included with git bash is missing more
which means that adr help (f.e.) doesn't work.
git bash does have less
which works just as well, so my initial workaround was to copy less.exe to more.exe in the git bash usr/bin/ folder.
Is there a technical reason why adr-tools uses more
rather than less
? Could it be changed without breaking other platforms?
I can submit a PR with an updated INSTALL.md which includes a note about copying less to more, or I can submit a PR with the shell script change to use less instead of more.
In my company, ADRs live in architecture/
.
I was in the architecture/
dir, and ran adr new ...
, and was surprised to find that a architecture/doc/adr
folder was created.
It'd be great if _adr_dir
searched in parent directories to see if there was a .adr-dir
, just as git
searches parent directories for a .git
.
Thanks for this great project, by the way! :)
I am somewhat confused by this clause in the LICENSE.txt
Content that this tool adds to your project is under the
Creative Commons Attribution 4.0 (CC BY 4.0) licence.
Does this only apply to the automatically generated phrasing of the ADRs? It surely does not apply to the content that you fill in, does it? It may be helpful to clarify this.
Would it be possible to package up this set of tools such that make install
will work?
##We are collaborating on several teams each with their own requirements for ADR specifications. We would like to use a .adr-config in the current directory, then ~/.adr-config and then use the system wide package adr in $(directory $0)/adr-config
Hi !
I definitely love this !
But would it be possible to add some i18n support so that
adr generate toc
command outputs a locale aware titleadr init [...]
creates a localized version of the first decisionThanks in advance !
The output of adr-config
could be more useful if the absolute path to the directory is known, especially when using its output from a different directory to the one adr-config
was executing in.
However, it's not necessary or even desirable to use the physical structure (resolved symlinks). The following incantation will, on MacOS and various Linuxes (including BusyBox), emit the full path to the script's directory.
$(cd -L $(dirname $0) >/dev/null 2>&1 && pwd -L)
This would emit something like /home/nat/code/adr-tools/src
rather than just .
or ../adr-tools/src
.
While not absolutely vital for the adr-config
provided as a default for when executing from the source distribution, it is a good practice and might help binary package maintainers.
The consequence is if the output is used in anything that would traverse hosts, the absolute file path would probably be invalid (but that is the case for most ..
paths anyway).
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.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
π Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. πππ
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google β€οΈ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.