A web-based application for the efficient creation and management of architectural decision records (ADRs) in Markdown (MADR)
MADR is a Markdown template for quickly capturing architectural decisions.
It offers a naming scheme and template to keep the layout of recorded decisions consistent.
Each decision is stored in a separate file.
The ADR Manager currently only supports the management of MADRs stored in the folder docs/adr
in GitHub repositories.
You can find the tool at https://adr.github.io/adr-manager.
Currently, the tool has been successfully tested in Chrome, Firefox, and Opera.
- After opening the tool, connect to GitHub. The tool needs your permission to access your GitHub repositories and email address.
- Add a GitHub repository. If your account does not have access to a repository with MADRs, you can simply fork one, e.g., https://github.com/JabRef/jabref or https://github.com/adr/adr-log.
- Now, you can edit any files in
docs/adr
of the GitHub repository. Edit existing ADRs or create new ones. One of the most important features is the MADR Editor that allows you to quickly draft a MADR while ensuring a consistent format. - Do not forget to push your changes to GitHub, once you are done with editing the files.
Some technical notes:
- The
authID
(which enables the connection to GitHub) and changes to ADRs are stored in the local storage. That way they are not lost when you reload the page or restart the browser. However, changes will be lost when you either- Clear local storage or
- Press the
Disconnect
button.
- The general idea is that you directly push your changes to GitHub after editing.
- During development, we may remove permissions for the OAuth App from time to time. Do not be surprised, if you have to give permissions repeatedly.
- Node.js and npm
- A GitHub account with access to a repository with MADRs
To run the project locally, follow these steps:
- Clone this repository.
- Install dependencies with
npm install
. - Compile and start the application with
npm start
.
Note that, even when you run it locally, you need to connect to GitHub to use any functionality.
We use Cypress for e2e testing.
The CI pipeline provides the necessary Oauth authId
as an ENV variable.
Locally, however, you'll need to provide one yourself.
You can either set CYPRESS_OAUTH_E2E_AUTH_ID
and CYPRESS_USER
containing the authId
and user
or create a cypress.env.json
file and fill it with the following content:
{
"OAUTH_E2E_AUTH_ID": "*********",
"USER": "***********"
}
The value of OAUTH_E2E_AUTH_ID
and USER
needs to be a valid authId
and user
from an active OAuth session, which you can obtain in the local storage (Chrome developer console -> Application -> Storage -> Local Storage -> http://localhost:8080
-> authId
, user
)
The involved GitHub account also needs to have developer access to the repo adr/adr-test-repository-empty
.
Lastly, don't forget to start the app before running the e2e tests (npm start
).
The following commands are useful for development:
# install dependencies
npm install
# build and start with hot-reload for development
npm start
# build and minify for production
npm run build
# run unit tests
npm test
# run e2e tests
npm run e2e:test
# open cypress GUI for e2e tests
npx cypress open
# run a single e2e test
npx cypress run --spec ./cypress/e2e/adrManagerTest/<file-name>
# format code with prettier (do this before you commit and push)
npm run format
The project uses [OAuth] for the authentication to GitHub. If you do not want to use this instance, you can easily set up your own by following these steps:
- Create an OAuth application on GitHub (see here).
- Copy the Client ID and Client Secret of the app (you'll need them later).
- Create a Github app on Firebase and in its configurations, set the Client ID and Client Secret as copied from the above Github app
- Set the callback URL in Github Oauth app configuration to the one provided by Firebase.
This project was started as an undergraduate research project at the Institute of Software Engineering of the University of Stuttgart, Germany. It was also submitted to the ICSE Score Contest 2021. Since then, it has been given over to the ADR organization on GitHub, where it is maintained and extended.