- Docs-as-code: ADRs are written in markdown, stored in your git repository, close to your code - Local preview with Hot Reload - Interactive ADR creation from the CLI - Static site generation to publish to GitHub/GitLab Pages or S3 - Timeline menu - Searchable - ADR metadata automatically guessed from its raw text and git logs - No enforced markdown structure: you are free to write however you want - No required file numbering schema (i.e., `adr-0001.md`, `adr-0002.md`...): avoids git merge issues - Customizable template (default: [MADR](https://adr.github.io/madr/)) - Multi-package projects support (mono or multi repo): notion of global and package-specific ADRs **Coming soon**: - Local images and diagrams support - RSS feed to be notified of new ADRs - Decision backlog - `@adr` annotation to include code references in ADRs - ADR creation/edition from the UI - Create a new GitHub/GitLab issue from the UI - ... let's [suggest a new feature](https://github.com/thomvaill/log4brains/issues/new?labels=feature&template=feature.md) if you have other needs!
🎞️ Watch the full screencast - ⚡ See an example (Log4brains' own ADRs)
## Table of contents - [🚀 Getting started](#-getting-started) - [🤔 What is an ADR and why should you use them](#-what-is-an-adr-and-why-should-you-use-them) - [📨 CI/CD configuration examples](#-cicd-configuration-examples) - [❓ FAQ](#-faq) - [What are the prerequisites?](#what-are-the-prerequisites) - [Is Log4brains only for JS projects?](#is-log4brains-only-for-js-projects) - [What about multi-package projects?](#what-about-multi-package-projects) - [How to configure `.log4brains.yml`?](#how-to-configure-log4brainsyml) - [Is Log4brains also available as a Docker image?](#is-log4brains-also-available-as-a-docker-image) - [📣 Your feedback is welcome!](#-your-feedback-is-welcome) - [Contributing](#contributing) - [Acknowledgments](#acknowledgments) - [License](#license) ## 🚀 Getting started We recommend storing your Architecture Decision Records (ADR) next to the source code of your project, in the same git repository, to keep them in sync. To get started, run these commands inside your project root folder: ```bash npm install -g log4brains # if you want to install the latest beta version, run `npm install -g log4brains@beta` instead log4brains init ``` It will ask you several questions to get Log4brains properly configured. It will also create the required template files and your first ADR as well. Then, you can start the web UI to preview your knowledge base locally: ```bash log4brains preview ``` In this mode, the Hot Reload feature is enabled: any change you make to a markdown file from your IDE is applied live. To create a new ADR from your template, run this command: ```bash log4brains adr new ``` Get all the available commands and options by running `log4brains --help`. Finally, do not forget to [set up your CI/CD pipeline](#-cicd-configuration-examples) to automatically publish your knowledge base on a static website service like GitHub/GitLab Pages or S3. ## 🤔 What is an ADR and why should you use them The term ADR became popular in 2011 with Michael Nygard's article: [documenting architecture decisions](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions). He aimed to reconcile Agile methods with software documentation by creating a very concise template to record functional or non-functional "architecturally significant" decisions in a lightweight format like markdown. The original template had only a few parts: - **Title**: Which sums up the solved problem and its solution - **Context**: Probably the essential part, which describes "the forces at play, including technological, political, social, and project local" - **Decision** - **Status**: Proposed, accepted, deprecated, superseded... - **Consequences**: The positive and negative ones for the future of the project There are other ADR templates like [Y-Statements](https://medium.com/olzzio/y-statements-10eb07b5a177) or [MADR](https://adr.github.io/madr/), which is the default one that is shipped with Log4brains. As you can guess from the template above, an ADR is immutable. Only its status can change. Thanks to this, your documentation is never out-of-date! Yes, an ADR can be deprecated or superseded by another one, but it was at least true one day! And even if it's not the case anymore, it is still a precious piece of information. This leads us to the main goals of this methodology: - Avoid blind acceptance and blind reversal when you face past decisions - Speed up the onboarding of new developers on a project - Formalize a collaborative decision-making process To learn more on this topic, I recommend you to read these great resources: - [Documenting architecture decisions](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions), by Michael Nygard - [ADR GitHub organization](https://adr.github.io/), home of the [MADR](https://adr.github.io/madr/) template, by [Oliver Kopp](https://github.com/koppor/) and [Olaf Zimmermann](https://ozimmer.ch/) - [Collection of ADR templates and examples](https://github.com/joelparkerhenderson/architecture_decision_record) by [Joel Parker Henderson](https://github.com/joelparkerhenderson) ## 📨 CI/CD configuration examples Log4brains lets you publish automatically your knowledge base on the static hosting service of your choice, thanks to the `log4brains-web build` command. Here are some configuration examples for the most common hosting services / CI runners.
First, create `.github/workflows/publish-log4brains.yml` and adapt it to your case:
```yml
name: Publish Log4brains
on:
push:
branches:
- main
jobs:
build-and-publish:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
persist-credentials: false # required by JamesIves/github-pages-deploy-action
fetch-depth: 0 # required by Log4brains to work correctly (needs the whole Git history)
- uses: actions/setup-node@v4
with:
node-version: lts/*
- name: Install and Build Log4brains
run: |
npm install -g log4brains
log4brains build --basePath /${GITHUB_REPOSITORY#*/}/log4brains
- name: Deploy
uses: JamesIves/github-pages-deploy-action@3.7.1
with:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
BRANCH: gh-pages
FOLDER: .log4brains/out
TARGET_FOLDER: log4brains
```
After the first run, this workflow will create a `gh-pages` branch in your repository containing the generated static files to serve.
Then, we have to tell GitHub that we [don't want to use Jekyll](https://github.com/vercel/next.js/issues/2029), otherwise, you will get a 404 error:
```bash
git checkout gh-pages
touch .nojekyll
git add .nojekyll
git commit -m "Add .nojekyll for Log4brains"
git push
```
Finally, you can [enable your GitHub page](https://docs.github.com/en/free-pro-team@latest/github/working-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site):
- On GitHub, go to `Settings > GitHub Pages`
- Select the `gh-pages` branch as the "Source"
- Then, select the `/ (root)` folder
You should now be able to see your knowledge base at `https://
Create your `.gitlab-ci.yml` and adapt it to your case:
```yml
image: node:lts-alpine
pages:
stage: deploy
variables:
GIT_DEPTH: 0 # required by Log4brains to work correctly (needs the whole Git history)
script:
- mkdir -p public
- npm install -g --unsafe-perm log4brains
- log4brains build --basePath /$CI_PROJECT_NAME/log4brains --out public/log4brains
artifacts:
paths:
- public
rules:
- if: "$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH"
```
You should now be able to see your knowledge base at `https://
First, create a bucket with the "Static website hosting" feature enabled:
```bash
# This is an example: replace with the bucket name of your choice
export BUCKET_NAME=yourcompany-yourproject-log4brains
aws s3api create-bucket --acl public-read --bucket ${BUCKET_NAME}
read -r -d '' BUCKET_POLICY << EOP
{
"Statement": [
{
"Effect": "Allow",
"Principal": "*",
"Action": "s3:GetObject",
"Resource": "arn:aws:s3:::${BUCKET_NAME}/*"
}
]
}
EOP
aws s3api put-bucket-policy --bucket ${BUCKET_NAME} --policy "$BUCKET_POLICY"
aws s3 website s3://${BUCKET_NAME} --index-document index.html
```
Then, configure your CI to run these commands:
- Install Node and the AWS CLI
- Checkout your Git repository **with the full history**. Otherwise, Log4brains won't work correctly (see previous examples)
- `npm install -g log4brains`
- `log4brains build`
- `aws s3 sync .log4brains/out s3://
|
[](http://URL-of-your-knowledge-base/) |
``` project-root ├── docs | └── adr | ├── 20200101-your-first-adr.md | ├── 20200115-your-second-adr.md | ├── [...] | ├── index.md | └── template.md [...] ```
``` project-root ├── docs | └── adr | ├── 20200101-your-first-global-adr.md | ├── 20200115-your-second-global-adr.md | ├── [...] | ├── index.md | └── template.md ├── packages | ├── package1 | | ├── docs | | | └── adr | | | ├── 20200102-your-first-package-specific-adr.md | | | ├── 20200116-your-second-package-specific-adr.md | | | [...] | | [...] | ├── package2 | | ├── docs | | | └── adr | | | ├── [...] | | | [...] | | [...] | [...] [...] ```
For the moment in one central repository (specific for the docs, or not): ``` project-docs ├── adr | ├── global | | ├── 20200101-your-first-global-adr.md | | ├── 20200115-your-second-global-adr.md | | ├── [...] | | ├── index.md | | └── template.md | ├── package1 | | ├── 20200102-your-first-package-specific-adr.md | | ├── 20200116-your-second-package-specific-adr.md | | [...] | ├── package2 | | ├── [...] | | [...] | [...] [...] ``` In the future: ``` project-docs ├── adr | ├── 20200101-your-first-global-adr.md | ├── 20200115-your-second-global-adr.md | ├── [...] | ├── index.md | └── template.md [...] repo1 ├── docs | └── adr | ├── 20200102-your-first-package-specific-adr.md | ├── 20200116-your-second-package-specific-adr.md | [...] [...] repo2 ├── docs | └── adr | ├── [...] | [...] [...] ```