Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update ADR homepage with links and advice #3

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
+34 −8
Open

Update ADR homepage with links and advice #3

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 34 additions & 8 deletions index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,26 +1,36 @@
<!-- This file is the homepage of your Log4brains knowledge base. You are free to edit it as you want -->

# Architecture knowledge base

Welcome 👋 to the architecture knowledge base of Commanded Ecosystem.
You will find here all the Architecture Decision Records (ADR) of the project.

## Definition and purpose

> An Architectural Decision (AD) is a software design choice that addresses a functional or non-functional requirement that is architecturally significant.
> An Architectural Decision Record (ADR) captures a single AD, such as often done when writing personal notes or meeting minutes; the collection of ADRs created and maintained in a project constitutes its decision log.
> An Architectural Decision (AD) is a software design choice that addresses a
> functional or non-functional requirement that is architecturally significant.
>
> An Architectural Decision Record (ADR) captures a single AD, such as often
> done when writing personal notes or meeting minutes; the collection of ADRs
> created and maintained in a project constitutes its decision log.

An ADR is immutable: only its status can change (i.e., become deprecated or
superseded). That way, you can become familiar with the whole project history
just by reading its decision log in chronological order.

An ADR is immutable: only its status can change (i.e., become deprecated or superseded). That way, you can become familiar with the whole project history just by reading its decision log in chronological order.
Moreover, maintaining this documentation aims at:

- 🚀 Improving and speeding up the onboarding of a new team member
- 🔭 Avoiding blind acceptance/reversal of a past decision (cf [Michael Nygard's famous article on ADRs](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions.html))
- 🔭 Avoiding blind acceptance/reversal of a past decision (cf [Michael
Nygard's famous article on
ADRs](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions.html))
- 🤝 Formalizing the decision process of the team

## Usage

This website is automatically updated after a change on the `main` branch of the project's Git repository.
In fact, the developers manage this documentation directly with markdown files located next to their code, so it is more convenient for them to keep it up-to-date.
This website is automatically updated after a change on [the `main` branch of
the Git repository](https://github.com/commanded/adr). In fact, the developers
manage this documentation directly with markdown files located next to their
code, so it is more convenient for them to keep it up-to-date.

You can browse the ADRs by using the left menu or the search bar.

The typical workflow of an ADR is the following:
Expand All @@ -29,6 +39,22 @@ The typical workflow of an ADR is the following:

The decision process is entirely collaborative and backed by pull requests.

### Pro-tip

Before proposing an ADR, it's a good idea to do the following:

- Search for existing, related ADRs to make sure you aren't proposing something
that has already been proposed.

- Search through [the
discussions](https://github.com/commanded/adr/discussions) to see if anyone
else is already thinking of similar ideas and you could join them in
championing an ADR.

- Start a new discussion in the "Ideas" category to do some initial
information-gathering and determine the likelihood of your proposal being
accepted.

## More information

- [Log4brains documentation](https://github.com/thomvaill/log4brains/tree/develop#readme)
Expand Down