I want to collect all available ADRs.

I place following yml file in my repo

project:
  repository:
    url: https://git.example.com/org/project
    provider: github
    adrFolder: ./subproject/docs/adr

I run

$ log4brains-web build

I get following output:

Building Log4brains...
info  - Creating an optimized production build

However, the folder is still empty:

$ dir
...

22.12.2020  11:38    <DIR>          .
22.12.2020  11:38    <DIR>          ..
22.12.2020  11:38                 0 .gitignore
22.12.2020  11:40               139 .log4brains.yml
22.12.2020  10:16               293 README.md
               3 Datei(en),            432 Bytes
...

Is it possible to provide some more output to enable debugging the usage?

Oliver Kopp [email protected], Mercedes-Benz AG on behalf of MBition GmbH.

Imprint

Bug Report

Description

On the first invocation of log4brains build after adding a new ADR markdown doc, an HTML version of that doc is not created in the .log4brains/out/adr directory. On subsequent invocations of log4brains build, the HTML doc is correctly generated.

Steps to Reproduce

1. Create a new markdown file in docs/adr
2. Run log4brains build
3. Observe that .log4brains/out/adr does not contain an HTML file matching the name of your markdown file
4. Run log4brains build
5. Observe that .log4brains/out/adr does contain an HTML file matching the name of your markdown file

Expected Behavior

All markdown files should be compiled into HTML on the first invocation of log4brains build.

Context

We notice this in CI (Github Actions), which is generally the first time we run log4brains build. But it is reproducible locally on MacOS 10.15.

Environment

• Log4brains version: 1.0.0-beta.11
• Node.js version: 14.15.4
• Yarn version: 1.22.10
• OS and its version: Reproducible on MacOS 10.15 and Ubuntu 20.04 (via GitHub Actions)

Bug Report

Description

We want to use superseded adrs.
We updated Status of the superseded doc like below:

- Status: superseded by [20201029-superseder](20201029-superseder.md)

And we added link to superseded doc in superseder doc like below:

- Supersedes [20201028-superseded-adr](20201028-superseded-adr.md)

When we clicked to superseded adr from adr list it returns 500 response and we got Error: You forgot to pass the superseder error from terminal.

Steps to Reproduce

project:
  name: my adrs
  tz: Europe/Istanbul
  packages:
    - name: mypackage
      path: ./mypackage
      adrFolder: ./mypackage/docs/adr

Directory structure is like below:

.
├── mypackage
│ ├── docs
│ │ └── adr
│ │     ├── 20201028-superseded-adr.md
│ │     └── 20201029-superseder.md

Expected Behavior

Superseded ADRs in multi package project should be work like mono package project.
We tried with mono package structure and it worked like expected.

Context

We want to create ADRs in multi package project structure.

Environment

• Log4brains version: 1.0.1
• Node.js version: v19.6.0
• OS and its version: MacOs Darwin 22.4.0 Darwin Kernel Version 22.4.0:

Bug Report

Description

Regression of a previous bug report from last year regarding a NextJS Hack. issue #27

Steps to Reproduce

1. Installed the latest version of the log4brains.
2. log4brains init
3. log4brains preview fails with the error:
   FATAL Cannot read property 'incrementalOptions' of undefined
4. log4brains build works and the output is generated but not entirely.

Environment

Log4brains version: 1.0.0-beta.8
Node.js version: v14.19.0 & v16.15.0
OS and its version: MacOS v12.3.1
Browser information: NA

Possible Solution

Fixed reference to NextJS

Feature Request

Feature Suggestion

As github supports mermaid.js diagrams in markdown, it would be nice to also support it in the generated html files.

Context

writing mermaid diagrams in the adr markdowns using Githubs mermaid diagrams, should be rendered as diagram in the html files generated by "log4brains build".

I tryed to make it work by writing accoring the sample on mermaid.js direclty in the markdoww adr.

<pre class="mermaid">
  graph LR
      A --- B
      B-->C[fa:fa-ban forbidden]
      B-->D(fa:fa-spinner);
</pre>
<script src="https://cdnjs.cloudflare.com/ajax/libs/mermaid/9.2.1/mermaid.min.js"/>
<script>
  mermaid.initialize({ startOnLoad: true });
</script>

works for html files in gh-pages but editing the mardkown with a previewer locally wouldnt render the diagram correctly.
So by writing mermaid markdown syntax, like following, the rendered index file should render something like above.

```mermaid
graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;
\```

Bug Report

Description

Log4brains init does'nt work and produce following error with node 18.2 clean install.

/usr/local/lib/node_modules/log4brains/node_modules/esm/esm.js:1
const __global__ = 

.../... (long source code)

/usr/local/lib/node_modules/log4brains/node_modules/@log4brains/core/dist/index.module.js:1
Error [ERR_REQUIRE_ESM]: require() of ES Module /usr/local/lib/node_modules/log4brains/node_modules/cheerio/lib/esm/index.js not supported.
Instead change the require of index.js in null to a dynamic import() which is available in all CommonJS modules.
    at Object.<anonymous> (/usr/local/lib/node_modules/log4brains/node_modules/@log4brains/core/dist/index.module.js:1)
    at Generator.next (<anonymous>)
    at Object.<anonymous> (/usr/local/lib/node_modules/log4brains/node_modules/@log4brains/cli/dist/cli.js:1)
    at Generator.next (<anonymous>)
    at Object.<anonymous> (/usr/local/lib/node_modules/log4brains/node_modules/@log4brains/cli/dist/index.js:1)
    at Generator.next (<anonymous>)
    at Object.<anonymous> (/usr/local/lib/node_modules/log4brains/dist/cli.js:1)
    at Generator.next (<anonymous>)
    at Object.<anonymous> (/usr/local/lib/node_modules/log4brains/dist/main.js:1)
    at Generator.next (<anonymous>)
    at Object.<anonymous> (/usr/local/lib/node_modules/log4brains/dist/log4brains:5:18) {
  code: 'ERR_REQUIRE_ESM'

Steps to Reproduce

1. npm y -g log4brains
2. log4brains init

Expected Behavior

Log4brains should work as expecte...

Context

Simply trying to init log4brains

Environment

• Log4brains version: 1.0.0-beta.11
• Node.js version: v18.2.0
• OS and its version: MacOS X
• Browser information: NA

npm -g list
/usr/local/lib
├── [email protected]
└── [email protected]

Bug Report

Description

Executing log4brains preview fails with Fatal Cannot read property 'incrementalOptions' of undefined message

Steps to Reproduce

The full log can be seen below, but it is quite easy:

1. Install log4brains as by instructions from ReadMe
2. Execute log4brains init
3. Execute log4brains preview

Expected Behavior

Seeing the preview

Context

I cannot see a preview of the ADRs

Environment

• Log4brains version: 1.0.0-beta.13
  

• Node.js version: 12.18.0
  

• OS and its version: Windows 10.0.19044 N/A Build 19044

Feature Request

Feature Suggestion

log4brains-web build also deploys a PNG badge to display in the project's README that displays the number of ADRs.

Bug Report

Description

build doesn't work in CI

Steps to Reproduce

Expected Behavior

to build correctly or at least display errors

Bug Report

Description

#27 has been open for 1 month and has not been resolved.

Steps to Reproduce

Run cicd Github Actions and watch the build break.

Expected Behavior

Resolved breakage within a month.

Context

• Unable to use log4brains
• Evaluating use for documentation

Feature Request

Feature Suggestion

Allow the logo of the project to be set

Context

Add branding.

Possible Implementation

Add a yml config for this and change the web ui.

Bug Report

Description

the output generated by log4brains build is broken

Steps to Reproduce

1. Install node lts/fermium v14.21.3
2. install log4brains:latest: npm install -g log4brains
3. initiate a log4brains project: log4brains init
4. build a deployable static website: log4brains build
5. launch the index.html at .log4brains/out
   6: See how the navigation, search and images are broken

Expected Behavior

The static website should work

Context

I can't deploy to gitlab pages or whatever using the procedure explained in the README.md

Environment

• Log4brains version: 1.0.1
• Node.js version: 14.21.3
• OS and its version: Ubuntu 20 on WSL
• Browser information: Microsoft Edge

Feature Request

Offer a custom cli cmd name when setting up the project instead of the fixed log4brains.

Feature Suggestion

Having a custom cmd name would help with implementing the tool at an organizational level, or a department level even e.g. <company> adr new.

Bug Report

Great project, thanks for your work! I am trying to run log4brains in Docker and I encounter the following. If I have time I will try to submit a PR fixing this, but for now I will submit the issue.

Description

Ctrl-C does not stop log4brains preview when run in Docker

Steps to Reproduce

1. Run 'log4brains preview' in Docker with the following command:

docker run --rm -ti -v $(pwd):/workdir -p 4004:4004 thomvaill/log4brains preview 

2. Press ctrl-c
3. The container does not stop

Expected Behavior

In step 3, log4brains and the container should stop.

Context

You can stop the container by running docker ps and running docker stop <container id> but this is cumbersome.

Environment

• Log4brains version: the version in Docker image (1.0.0-beta.11)
  thomvaill/log4brains latest 7bb84c921b02 6 weeks ago 412MB
• Node.js version: version in Docker image
• OS and its version: version in Docker image
• Browser information: Firefox

Possible Solution

I do not have a solution right now, but maybe playing with the Docker entrypoint / cmd can fix this.

Bug Report

Description

I had some issues with comments.

Steps to Reproduce

Observation 1)

Put this comment at the end of any MD file:
<!-- Chosen option: "Log4brains", because it includes the features of all the other tools, and even more. -->

I get this error message in the previewer
An unexpected error has occurred.

framework.5ab3178105b977ab7f59.js:1 TypeError: Cannot read properties of null (reading 'type')
at xa (45d2d314fc8da5e3d79852782e4a432ad4da6771.744cf221144f0adb686a.js:1:911930)
at 45d2d314fc8da5e3d79852782e4a432ad4da6771.744cf221144f0adb686a.js:1:912391
at framework.5ab3178105b977ab7f59.js:1:4353
at framework.5ab3178105b977ab7f59.js:1:3787
at P (framework.5ab3178105b977ab7f59.js:1:2919)
at P (framework.5ab3178105b977ab7f59.js:1:3332)
at N (framework.5ab3178105b977ab7f59.js:1:3753)
at Object.forEach (framework.5ab3178105b977ab7f59.js:1:4335)
at 45d2d314fc8da5e3d79852782e4a432ad4da6771.744cf221144f0adb686a.js:1:912368
at Ma (45d2d314fc8da5e3d79852782e4a432ad4da6771.744cf221144f0adb686a.js:1:912478)
uu @ framework.5ab3178105b977ab7f59.js:1
main-319220bbc2fa7828d1ea.js:1 TypeError: Cannot read properties of null (reading 'type')
at xa (45d2d314fc8da5e3d79852782e4a432ad4da6771.744cf221144f0adb686a.js:1:911930)
at 45d2d314fc8da5e3d79852782e4a432ad4da6771.744cf221144f0adb686a.js:1:912391
at framework.5ab3178105b977ab7f59.js:1:4353
at framework.5ab3178105b977ab7f59.js:1:3787
at P (framework.5ab3178105b977ab7f59.js:1:2919)
at P (framework.5ab3178105b977ab7f59.js:1:3332)
at N (framework.5ab3178105b977ab7f59.js:1:3753)
at Object.forEach (framework.5ab3178105b977ab7f59.js:1:4335)
at 45d2d314fc8da5e3d79852782e4a432ad4da6771.744cf221144f0adb686a.js:1:912368
at Ma (45d2d314fc8da5e3d79852782e4a432ad4da6771.744cf221144f0adb686a.js:1:912478)

Observation 2)

Sometimes I was just putting the possible statuses as comment afterwards.
- Status: accepted <!-- [draft | proposed | rejected | accepted | deprecated | … | superseded by [xxx](yyyymmdd-xxx.md)] -->

This renders in the previewer surprisingly to "Draft" (and not accepted as it would be if the comment is removed).

Expected Behavior

Comment is ignored.

Context

log4brains preview
Looking at rendered pages in the previewer.

Environment

• Log4brains version: 1.0.0-beta.13
• Node.js version: v14.18.1
• OS and its version: Windows 10
• Browser information: Chrome

Bug Report

Description

For any call to the CLI, there is a constant startup time of ~3 sec, whatever the command is. Even a very simple one like log4brains --version.
After a quick debug, it looks like this is due to esm package we use to provide on-the-fly ESM imports capabilities.
My doubts are reinforced by this issue: standard-things/esm#844

Steps to reproduce

log4brains --version

Expected Behavior

log4brains --version (and the majority of other commands) should be instant.

Possible Solution

Either fix the esm package or get rid of it by compiling to commonJS all of our packages... (like the core one).

Bug Report

Description

When templates do not exist, the --from flag is ignored, and an error is thrown.

Steps to Reproduce

See the sample repository

1. Delete the template from a boilerplate project
2. Attempt to generate a new ADR with the --from flag

Expected Behavior

A new ADR is generated from the file specified by --from

Context

Didn't have a need for the base template. Only two packages are used, each with their own template.
Before I figured out that putting template.md in the adrFolder directory worked, I tried using the --from CLI argument.

Environment

• Log4brains version: ^1.0.0-beta.11
• Node.js version: v16.13.0
• OS and its version: MacOS 12.0.1 (Apple M1)
• Browser information: N/A

Possible Solution

The error is thrown from AdrTemplateRepository.ts. It would seem that this template check is done before checking the path provided with --from.

You can just define a template in any of the adrFolder directories to get around this, and the --from flag works just fine, but it would seem to me that that argument, and the presence of a template, are independent of one another.

Feature Request

Feature Suggestion

It would be of great value if we could get some views that were filtered down by a given package.

Context

Managing a long lived monorepo with lots of ADRs could grow cumbersome. We are also adopting ADR for decision making for our enterprise where we intend to model certain business and technical areas as packages, where it would be valuable to view those decision areas separately from the global adr population.

Possible Implementation

On the left side in the visual representation of the decision log, a drop down or method of picking a package that filters it down to the decisions in the package would be one way to implement this.

Bug Report

Description

The "next" package is being referred internally and it installed the latest automatically. Earlier this week, when I installed [email protected] "next 10.0.7" was being used and everything is working as expected, Now it's referring to the "next 10.0.8" and things started to break.

Steps to Reproduce

1. Installed the latest version of the log4brains.
2. Ran "log4brains init" to create the .log4brains.yml and docs folder.
3. "log4brains preview" is failing with the below error.
   
4. "log4brains build" is executing till the end but the outputs are not being generated.

Environment

• Log4brains version: 1.0.0-beta.8
• Node.js version: v15.10.0
• OS and its version: Windows 10
• Browser information: NA

Possible Solution

Fix the reference to the NEXTJS.

Description

For now, the e2e tests only cover the CLI.
We also want to check at least that:

Preview:

• log4brains-web preview starts without error
• A webpage is served on http://localhost:4004
• "E2E test ADR" exists in the left menu
• Check additional information on ADRs

Build:

• log4brains-web build finishes without error
• Serve it with serve
• Same checks as log4brains-web preview

Possible Implementation

Cypress vs Puppeteer

Deploy core TypeDoc documentation on GitHub Pages and update its link in core README.

Bug Report

Description

Print CSS issues:

• Search bar appears
• Footer can be improved

Bug Report

Steps to Reproduce

nvm use 18
log4brains build

# output:
Building Log4brains...
[Next]  Error: error:0308010C:digital envelope routines::unsupported
    at new Hash (node:internal/crypto/hash:71:19)
    at Proxy.createHash (node:crypto:133:10)
    at module.exports.__webpack_modules__.15660.module.exports (/opt/hostedtoolcache/node/18.9.0/x64/lib/node_modules/log4brains/node_modules/next/dist/compiled/webpack/bundle4.js:111680:62)
    at NormalModule._initBuildHash (/opt/hostedtoolcache/node/18.9.0/x64/lib/node_modules/log4brains/node_modules/next/dist/compiled/webpack/bundle4.js:85092:16)
    at handleParseError (/opt/hostedtoolcache/node/18.9.0/x64/lib/node_modules/log4brains/node_modules/next/dist/compiled/webpack/bundle4.js:85146:10)
    at /opt/hostedtoolcache/node/18.9.0/x64/lib/node_modules/log4brains/node_modules/next/dist/compiled/webpack/bundle4.js:85178:5
    at /opt/hostedtoolcache/node/18.9.0/x64/lib/node_modules/log4brains/node_modules/next/dist/compiled/webpack/bundle4.js:85033:12
    at /opt/hostedtoolcache/node/18.9.0/x64/lib/node_modules/log4brains/node_modules/next/dist/compiled/webpack/bundle4.js:51096:3
    at iterateNormalLoaders (/opt/hostedtoolcache/node/18.9.0/x64/lib/node_modules/log4brains/node_modules/next/dist/compiled/webpack/bundle4.js:50937:10)
    at iterateNormalLoaders (/opt/hostedtoolcache/node/18.9.0/x64/lib/node_modules/log4brains/node_modules/next/dist/compiled/webpack/bundle4.js:509[44](https://github.com/thomvaill/log4brains/actions/runs/3107331593/jobs/5035316854#step:4:45):10)
    at /opt/hostedtoolcache/node/18.9.0/x64/lib/node_modules/log4brains/node_modules/next/dist/compiled/webpack/bundle4.js:50959:3
    at runSyncOrAsync (/opt/hostedtoolcache/node/18.9.0/x64/lib/node_modules/log4brains/node_modules/next/dist/compiled/webpack/bundle4.js:50853:11)
    at iterateNormalLoaders (/opt/hostedtoolcache/node/18.9.0/x64/lib/node_modules/log4brains/node_modules/next/dist/compiled/webpack/bundle4.js:50955:2)
    at processResource (/opt/hostedtoolcache/node/18.9.0/x64/lib/node_modules/log4brains/node_modules/next/dist/compiled/webpack/bundle4.js:50931:3)
    at iteratePitchingLoaders (/opt/hostedtoolcache/node/18.9.0/x64/lib/node_modules/log4brains/node_modules/next/dist/compiled/webpack/bundle4.js:50881:10)
    at iteratePitchingLoaders (/opt/hostedtoolcache/node/18.9.0/x64/lib/node_modules/log4brains/node_modules/next/dist/compiled/webpack/bundle4.js:50888:10)
[Next]  Error: error:0308010C:digital envelope routines::unsupported
    at new Hash (node:internal/crypto/hash:71:19)
    at Proxy.createHash (node:crypto:133:10)
    at module.exports.__webpack_modules__.15660.module.exports (/opt/hostedtoolcache/node/18.9.0/x64/lib/node_modules/log4brains/node_modules/next/dist/compiled/webpack/bundle4.js:111680:62)
    at NormalModule._initBuildHash (/opt/hostedtoolcache/node/18.9.0/x64/lib/node_modules/log4brains/node_modules/next/dist/compiled/webpack/bundle4.js:85092:16)
    at handleParseError (/opt/hostedtoolcache/node/18.9.0/x64/lib/node_modules/log4brains/node_modules/next/dist/compiled/webpack/bundle4.js:851[46](https://github.com/thomvaill/log4brains/actions/runs/3107331593/jobs/5035316854#step:4:47):10)
    at /opt/hostedtoolcache/node/18.9.0/x64/lib/node_modules/log4brains/node_modules/next/dist/compiled/webpack/bundle4.js:85178:5
    at /opt/hostedtoolcache/node/18.9.0/x64/lib/node_modules/log4brains/node_modules/next/dist/compiled/webpack/bundle4.js:85033:12
    at /opt/hostedtoolcache/node/18.9.0/x64/lib/node_modules/log4brains/node_modules/next/dist/compiled/webpack/bundle4.js:51096:3
    at iterateNormalLoaders (/opt/hostedtoolcache/node/18.9.0/x64/lib/node_modules/log4brains/node_modules/next/dist/compiled/webpack/bundle4.js:50937:10)
    at iterateNormalLoaders (/opt/hostedtoolcache/node/18.9.0/x64/lib/node_modules/log4brains/node_modules/next/dist/compiled/webpack/bundle4.js:50944:10)
    at /opt/hostedtoolcache/node/18.9.0/x64/lib/node_modules/log4brains/node_modules/next/dist/compiled/webpack/bundle4.js:50959:3
    at runSyncOrAsync (/opt/hostedtoolcache/node/18.9.0/x64/lib/node_modules/log4brains/node_modules/next/dist/compiled/webpack/bundle4.js:50853:11)
    at iterateNormalLoaders (/opt/hostedtoolcache/node/18.9.0/x64/lib/node_modules/log4brains/node_modules/next/dist/compiled/webpack/bundle4.js:50955:2)
    at processResource (/opt/hostedtoolcache/node/18.9.0/x64/lib/node_modules/log4brains/node_modules/next/dist/compiled/webpack/bundle4.js:50931:3)
    at iteratePitchingLoaders (/opt/hostedtoolcache/node/18.9.0/x64/lib/node_modules/log4brains/node_modules/next/dist/compiled/webpack/bundle4.js:50881:10)
    at iteratePitchingLoaders (/opt/hostedtoolcache/node/18.9.0/x64/lib/node_modules/log4brains/node_modules/next/dist/compiled/webpack/bundle4.js:50888:10)
[Next]  Error: error:0308010C:digital envelope routines::unsupported
    at new Hash (node:internal/crypto/hash:71:19)
    at Proxy.createHash (node:crypto:133:10)
    at module.exports.__webpack_modules__.15660.module.exports (/opt/hostedtoolcache/node/18.9.0/x64/lib/node_modules/log4brains/node_modules/next/dist/compiled/webpack/bundle4.js:111680:62)
    at NormalModule._initBuildHash (/opt/hostedtoolcache/node/18.9.0/x64/lib/node_modules/log4brains/node_modules/next/dist/compiled/webpack/bundle4.js:85092:16)
    at handleParseError (/opt/hostedtoolcache/node/18.9.0/x64/lib/node_modules/log4brains/node_modules/next/dist/compiled/webpack/bundle4.js:85146:10)
    at /opt/hostedtoolcache/node/18.9.0/x64/lib/node_modules/log4brains/node_modules/next/dist/compiled/webpack/bundle4.js:85178:5
    at /opt/hostedtoolcache/node/18.9.0/x64/lib/node_modules/log4brains/node_modules/next/dist/compiled/webpack/bundle4.js:85033:12
    at /opt/hostedtoolcache/node/18.9.0/x64/lib/node_modules/log4brains/node_modules/next/dist/compiled/webpack/bundle4.js:51096:3
    at iterateNormalLoaders (/opt/hostedtoolcache/node/18.9.0/x64/lib/node_modules/log4brains/node_modules/next/dist/compiled/webpack/bundle4.js:50937:10)
    at iterateNormalLoaders (/opt/hostedtoolcache/node/18.9.0/x64/lib/node_modules/log4brains/node_modules/next/dist/compiled/webpack/bundle4.js:50944:10)
    at /opt/hostedtoolcache/node/18.9.0/x64/lib/node_modules/log4brains/node_modules/next/dist/compiled/webpack/bundle4.js:50959:3
    at runSyncOrAsync (/opt/hostedtoolcache/node/18.9.0/x64/lib/node_modules/log4brains/node_modules/next/dist/compiled/webpack/bundle4.js:50853:11)
    at iterateNormalLoaders (/opt/hostedtoolcache/node/18.9.0/x64/lib/node_modules/log4brains/node_modules/next/dist/compiled/webpack/bundle4.js:50955:2)
    at processResource (/opt/hostedtoolcache/node/18.9.0/x64/lib/node_modules/log4brains/node_modules/next/dist/compiled/webpack/bundle4.js:50931:3)
    at iteratePitchingLoaders (/opt/hostedtoolcache/node/18.9.0/x64/lib/node_modules/log4brains/node_modules/next/dist/compiled/webpack/bundle4.js:50881:10)
    at iteratePitchingLoaders (/opt/hostedtoolcache/node/18.9.0/x64/lib/node_modules/log4brains/node_modules/next/dist/compiled/webpack/bundle4.js:50888:10)
[Next]  Error: error:0308010C:digital envelope routines::unsupported
    at new Hash (node:internal/crypto/hash:71:19)
    at Proxy.createHash (node:crypto:133:10)
    at module.exports.__webpack_modules__.15660.module.exports (/opt/hostedtoolcache/node/18.9.0/x64/lib/node_modules/log4brains/node_modules/next/dist/compiled/webpack/bundle4.js:111680:62)
    at NormalModule._initBuildHash (/opt/hostedtoolcache/node/18.9.0/x64/lib/node_modules/log4brains/node_modules/next/dist/compiled/webpack/bundle4.js:85092:16)
    at handleParseError (/opt/hostedtoolcache/node/18.9.0/x64/lib/node_modules/log4brains/node_modules/next/dist/compiled/webpack/bundle4.js:85146:10)
    at /opt/hostedtoolcache/node/18.9.0/x64/lib/node_modules/log4brains/node_modules/next/dist/compiled/webpack/bundle4.js:85178:5
    at /opt/hostedtoolcache/node/18.9.0/x64/lib/node_modules/log4brains/node_modules/next/dist/compiled/webpack/bundle4.js:85033:12
    at /opt/hostedtoolcache/node/18.9.0/x64/lib/node_modules/log4brains/node_modules/next/dist/compiled/webpack/bundle4.js:51096:3
    at iterateNormalLoaders (/opt/hostedtoolcache/node/18.9.0/x64/lib/node_modules/log4brains/node_modules/next/dist/compiled/webpack/bundle4.js:50937:10)
    at iterateNormalLoaders (/opt/hostedtoolcache/node/18.9.0/x64/lib/node_modules/log4brains/node_modules/next/dist/compiled/webpack/bundle4.js:50944:10)
    at /opt/hostedtoolcache/node/18.9.0/x64/lib/node_modules/log4brains/node_modules/next/dist/compiled/webpack/bundle4.js:50959:3
    at runSyncOrAsync (/opt/hostedtoolcache/node/18.9.0/x64/lib/node_modules/log4brains/node_modules/next/dist/compiled/webpack/bundle4.js:50853:11)
    at iterateNormalLoaders (/opt/hostedtoolcache/node/18.9.0/x64/lib/node_modules/log4brains/node_modules/next/dist/compiled/webpack/bundle4.js:50955:2)
    at processResource (/opt/hostedtoolcache/node/18.9.0/x64/lib/node_modules/log4brains/node_modules/next/dist/compiled/webpack/bundle4.js:50931:3)
    at iteratePitchingLoaders (/opt/hostedtoolcache/node/18.9.0/x64/lib/node_modules/log4brains/node_modules/next/dist/compiled/webpack/bundle4.js:50881:10)
    at iteratePitchingLoaders (/opt/hostedtoolcache/node/18.9.0/x64/lib/node_modules/log4brains/node_modules/next/dist/compiled/webpack/bundle4.js:50888:10)
node:internal/crypto/hash:71
  this[kHandle] = new _Hash(algorithm, xofLen);
                  ^

Error: error:0308010C:digital envelope routines::unsupported
    at new Hash (node:internal/crypto/hash:71:19)
    at Proxy.createHash (node:crypto:133:10)
    at module.exports.__webpack_modules__.15660.module.exports (/opt/hostedtoolcache/node/18.9.0/x64/lib/node_modules/log4brains/node_modules/next/dist/compiled/webpack/bundle4.js:111680:62)
    at NormalModule._initBuildHash (/opt/hostedtoolcache/node/18.9.0/x64/lib/node_modules/log4brains/node_modules/next/dist/compiled/webpack/bundle4.js:85092:16)
    at /opt/hostedtoolcache/node/18.9.0/x64/lib/node_modules/log4brains/node_modules/next/dist/compiled/webpack/bundle4.js:85127:10
    at /opt/hostedtoolcache/node/18.9.0/x64/lib/node_modules/log4brains/node_modules/next/dist/compiled/webpack/bundle4.js:8[49](https://github.com/thomvaill/log4brains/actions/runs/3107331593/jobs/5035316854#step:4:50)98:13
    at /opt/hostedtoolcache/node/18.9.0/x64/lib/node_modules/log4brains/node_modules/next/dist/compiled/webpack/bundle4.js:51090:11
    at /opt/hostedtoolcache/node/18.9.0/x64/lib/node_modules/log4brains/node_modules/next/dist/compiled/webpack/bundle4.js:[50](https://github.com/thomvaill/log4brains/actions/runs/3107331593/jobs/5035316854#step:4:51)9[56](https://github.com/thomvaill/log4brains/actions/runs/3107331593/jobs/5035316854#step:4:57):18
    at context.callback (/opt/hostedtoolcache/node/18.9.0/x[64](https://github.com/thomvaill/log4brains/actions/runs/3107331593/jobs/5035316854#step:4:65)/lib/node_modules/log4brains/node_modules/next/dist/compiled/webpack/bundle4.js:50[83](https://github.com/thomvaill/log4brains/actions/runs/3107331593/jobs/5035316854#step:4:84)4:13)
    at /opt/hostedtoolcache/node/18.9.0/x64/lib/node_modules/log4brains/node_modules/next/dist/build/webpack/loaders/babel-loader/src/index.js:4:106 {
  opensslErrorStack: [ 'error:030000[86](https://github.com/thomvaill/log4brains/actions/runs/3107331593/jobs/5035316854#step:4:87):digital envelope routines::initialization error' ],
  library: 'digital envelope routines',
  reason: 'unsupported',
  code: 'ERR_OSSL_EVP_UNSUPPORTED'
}

Expected Behavior

Should work :-)

Environment

• Log4brains version: 1.0.1
• Node.js version: 18.9.0
• OS and its version: all
• Browser information: n/a

Possible Solution

Probably some dependency updates.

Feature Request

Feature Suggestion

Have "complete" CLI commands for workflow/lifecycle management of ADRs

Context

I would like to have CLI commands to manage the suggested workflow and "automate" some kind of GitHub integration.

Like:

log4brains adr new

-> ✅

log4brains adr status

-> Basically does a git status scoped to the directory where ADRs files live or get opened and/or closed PRs related to ADRs

log4brains adr propose (or submit)

-> Does a git commit + opens PRs with predefined commit message format, PR title style, labels and so on 😇

I am also wondering how ease/automate the rest of the process via Pull requests 🤔

• when an ADR PR is merged, automatically update the state from proposed to accepted
• How to still merge a PR even when an ADR is rejected but set the proper status value ...

Possible Implementation

Feature Request

Feature Suggestion

In addition to the wonderful Docker image built for amd64, would it be possible to set it up to also automatically build and publish for arm64?

Context

Running both locally on Mac M1, and remotely in arm64 CI system, is made easier if toolchains have arm64 docker images. The alternative is to make local builds or to forgo the use of the Docker images

Bug Report

Description

When any section of the MADR contains an HTML comment in a separate paragraph, the front end just crashes with "An unexpected error has occurred". Live reload seems to break down in that moment as the front end does not recover when the offending comment is reverted. A reload is required for it to work again.

Not reverting and navigating to the URL of another ADR also works, however the knowledge base will crash again when clicking on the ADR holding the offending HTML comment paragraph.

HTML comments beginning and ending at the end of a list entry or heading do not trigger this error.

Crashed knowledge base

Console error

Steps to Reproduce

1. Create a new ADR
2. Start up log4brains preview (can also be running already, does not matter)
3. Move any of the comments in the template on their own paragraph, i.e. place the mouse course in front of <!-- optional -->, hit enter, and save the file.

Alternatively you can enter any HTML comment anywhere (except at the end of lists or headings) in an existing ADR.

Expected Behavior

The knowledge base should not crash.

Context

While drafting, I like to keep some of the initial comments found in square brackets in every template as a guideline for the team members that i am currently introducing to the ADR process, as i find them pretty well written and thus, helpful.

So i wanted to make them HTML comments that's how i discovered this behaviour.

Environment

Log4brains version: 1.0.0-beta.11
Node.js version: v17.3.0
OS and its version: Manjaro Linux
Browser information: Firefox 96.0.2 | Chromium 97.0.4692.99

Possible Solution

Bug Report

Description

Log4Brain does not SEO the project. Instead it SEOs log4brains.

Steps to Reproduce

Use the Log4Brains to export a website. Look at the title.

Expected Behavior

It should use the project name and not log4brains.

Context

Want to brand the repository.

Environment

• Log4brains version: 6c82030
• Node.js version: ?
• OS and its version: win10
• Browser information: firefox

Bug Report

Description

I get an error when I run log4brains init on a new install:

Error: Cannot find module '@hapi/hoek/assert'

Steps to Reproduce

npm i -g log4brains
log4brains init

Expected Behavior

It should not throw an error

Environment

• Log4brains version: 1.0.1
• Node.js version: 18.14.1
• OS and its version: Windows 11
• Browser information:

Bug Report

Description

I tried to run the build command and it failed due to sharp not being found.

Steps to Reproduce

1. yarn install --dev log4brains
2. yarn run log4brains init
3. yarn run log4brains build

❯ yarn run log4brains build
yarn run v1.22.10
$ /Users/user/workspace/work/project/node_modules/.bin/log4brains build
Building Log4brains...
[Next]
[Next]   FATAL  Cannot find module 'sharp'
Require stack:
- /Users/user/workspace/work/project/node_modules/@log4brains/web/node_modules/next/dist/build/index.js
- /Users/user/workspace/work/project/node_modules/@log4brains/web/dist/cli/commands/build.js
- /Users/user/workspace/work/project/node_modules/@log4brains/web/dist/cli/commands/index.js
- /Users/user/workspace/work/project/node_modules/@log4brains/web/dist/cli/cli.js
- /Users/user/workspace/work/project/node_modules/@log4brains/web/dist/cli/index.js
- /Users/user/workspace/work/project/node_modules/@log4brains/web/dist/index.js
- /Users/user/workspace/work/project/node_modules/log4brains/dist/cli.js
- /Users/user/workspace/work/project/node_modules/log4brains/dist/main.js
- /Users/user/workspace/work/project/node_modules/log4brains/dist/log4brains
[Next]
error Command failed with exit code 1.
info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.

Expected Behavior

To build the site successfully.

Context

I did not want to tell all users to globally install the command, so I added it to the project as a dev dependency.

I did not find sharp in the package.json of this project.

After adding sharp with yarn add -dev sharp the project was built correctly.

Environment

• Log4brains version: 1.22.10
• Node.js version: v16.3.0
• OS and its version: macOS 11.4 / Apple Silicon M1
• Browser information: N/A

Possible Solution

Add sharp to list of dependencies.

Feature Request

Feature Suggestion

Log4brains should be able to serve local images that are displayed in the markdown files.

Possible Implementation

Have a look at next/image

Feature Request

Feature Suggestion

Homebrew availability to install on macOS

Context

We are a mobile devs, as we might need to have our local ADRs, a simple tools we are currently used: https://github.com/npryce/adr-tools

Possible Implementation

Feature Request

Feature Suggestion

It shall be possible to host the generated static website within a sub-path of the web server.

Context

Our web server hosts several projects with associated documentation/adrs. Each one is accessible through a url path prefix.

The generated static website from log4brains assumes to be hosted in the web server root. The generated files refer to other content via absolute paths (with leading "/"). This prevents the hosting within a sub-path (e.g. http://example.com/project1/docs/decisions).

Possible Implementation

Suggestion: convert all generated path elements to be relative.

Discussed in #88

It would be nice to be able to alter the theme colors applied to .MuiAppBar-colorPrimary class thus resulting in a different top app bar. The current value for this is 2176AE

Feature Request

Feature Suggestion

For now, the default directory for ADRs is docs/adr, because it was commonly documented like this:

• https://adr.github.io/madr/
• https://github.com/joelparkerhenderson/architecture_decision_record

But @joelparkerhenderson recently gave me this interesting feedback:

Some teams much prefer the name "decisions" over the abbreviation "ADRs". When some teams use the directory name "decisions", then it's as if a light bulb turns on, and the team starts putting more information inton the directory, such as vendor decisions, planning decisions, scheduling decisions, etc. All of these kinds of information can use the same template. We hypothesize that people learn faster with words ("decisions") over abbreviations ("ADRs"), and people are more motivated to write work-in-progress docs when the word "record" is removed, and also some developers and some managers dislike the word "architecture".

So I propose to change the default value in Log4brains, because I am convinced that ADRs should not be reserved only for important architectural decisions. They are also beneficial for all kind of decisions, and we should promote that.

Possible Implementation

• Search and replace all occurrences of docs/adr in the README
• Search and replace all occurrences of docs/adr in the code, only when it is used as a default value
• Create an ADR for this :-)

Discussed in #43

Bug Report

Description

log4brains init fails with an error after completing the wizard in Mac OS - possibly due to differences in how sed works (unconfirmed).

$ npx log4brains init

👋 Welcome to Log4brains!

This interactive script will help you configure Log4brains for your project.
It will create the .log4brains.yml config file,
        copy the default ADR template,
        and create your first ADR for you!

Before going further, please check that you are running this command
from the root folder of your project's git repository:
/Users/tommy.brunn/workspace/log4brains-test

? Continue? Yes

👍 We will now ask you several questions to get you started:

? What is the name of your project? log4brains-test

? Which statement describes the best your project? Multi-package project

? In which directory do you plan to store your global ADRs? (will be automatically created) ./docs/adr

We will now define your packages...


  Package #1:

? Name? (short, lowercase, without special characters, nor spaces) foo

? Where is located the source code of this package? ./packages/foo

? In which directory do you plan to store the ADRs of this package? (will be automatically created) ./packages/foo/docs/adr

? We are done with package #1. Do you want to add another one? No
[==  ] Creating your first ADR... Error


 FATAL  Command failed with exit code 1: sed -i s/{DATE_YESTERDAY}/2021-01-18/g /Users/tommy.brunn/workspace/log4brains-test/docs/adr/20210119-use-log4brains-to-manage-the-adrs.md
sed: 1: "/Users/tommy.brunn/work ...": undefined label 'ommy.brunn/workspace/log4brains-test/docs/adr/20210119-use-log4brains-to-manage-the-adrs.md'

Steps to Reproduce

See the above steps. I literally just used the default options, except for choosing a multi-package project.

Expected Behavior

I'm not sure what the command is trying to do. Perhaps replacing {DATE_YESTERDAY} with the actual date.

Environment

• Log4brains version: 1.0.0-beta.6
• Node.js version: v14.15.1
• OS and its version: Mac OS 10.15.7

Bug Report

Description

When attempting to run the log4brains build command I am meet with the following error

Building Log4brains...
[Next]  
[Next]   FATAL  > Build directory is not writeable. https://err.sh/vercel/next.js/build-dir-not-writeable

I have tried multiple versions of node 12+, modifying permissions on directories and passing in basePath arguments, etc.

Steps to Reproduce

1. Initialize new repo
   log4brains init
2. Create adr
   log4brains adr new
3. Build
   log4brains build

Expected Behavior

The command should build the static pages for hosting

Environment

• Log4brains version: 1.0.0-beta.11
• Node.js version: v14.0.0
• OS and its version: Ubuntu 18.04
• Browser information: Brave Version 1.21.77 Chromium: 89.0.4389.90 (Official Build) (64-bit)

Bug Report

Description

links in index.html does not contain .html suffix, but generated html files has.

Steps to Reproduce

log4brains build -o public

Expected Behavior

should generated links with .html suffix

Context

Environment

• Log4brains version: (v1.0.0-beta.11)
• Node.js version:
• OS and its version:
• Browser information: Chrome latest

Possible Solution

found this question: https://stackoverflow.com/questions/62867105/how-to-deal-with-nextjs-exporting-files-with-html-extension-but-inlink-there

maybe we should add this for Next framework.

I am waiting for user feedback before going further.

Feature Request

Feature Suggestion

Support diagraming with nomnoml.

Context

I wanted to add one diagram to every decision.

Possible Implementation

Add https://github.com/tonykero/markdown-it-nomnoml.

Bug Report

Description

After some edit to adr file and save no reload is in place to see the page updated, i have to manually reload the page in the browser and then i correctly see the updates.

Steps to Reproduce

1. log4brains preview
2. edit any adr file
3. save

Expected Behavior

The browser page should refresh itself, i need to force reload to see updates.

Context

I was just exploring features, but the hot reload is something that boost DX, so hope to solve with your help 🙂

Environment

• Log4brains version: 1.0.0-beta.11
• Node.js version: v12.18.4
• OS and its version: Windows 10
• Browser information: Chrome 91.0.4472.124
• Command line: Windows Termina, git bash, cmd
• IDE: phpstorm 2021.1.4, Notepad++ 7.9.5

Possible Solution

I cant find any workaround or root cause

PS: thanks for all your time and effort 🙏

Feature Request

Feature Suggestion

Highlight matched keywords in search results in both title and body.
Also pay attention to remove HTML and Markdown tags in the body (cf packages/web/src/lib/search/Search.ts:71)

Bug Report

Description

Code formatting causes long lines in the web interface.

Steps to Reproduce

Open an adr and create a markdown section that has a ```````` formatting section that has overly long text.

Expected Behavior

Line should not overflow.

Context

This bug makes the markdown unreadable and unprintable (with ink and toner).

Environment

• Log4brains version: v1.0.0-beta.11 (not sure)
• Node.js version: Whatever the cicd uses on Github
• OS and its version: Firefox
• Browser information: 88.0.1 (64-bit)

Possible Solution

In css: usually you set width and then use overflow: auto on <code> elements.

Bug Report

Description

After upgrading log4brains to a newer version, the ESM cache is not cleared.
As a result, the old code is still executing.

Issue encountered for now only on macOS. Haven't tried yet on other platforms.

Bug Report

Description

When viewing ADRs in the log4brains web presentation (preview or live on gitlab / github pages), clicking on the "View in gitlab button" () leads to a 404 page.

This is due to the fact that my repository's default branch (such as any recent new repos on gitlab/github) is called main and there exists no master-branch.

Steps to Reproduce

1. Initialize a repository whose default branch is not named master
2. Set up ADR management with log4brains
3. Start up the preview server and/or publish via gitlab / github pages
4. Call up the knowledge base in the browser and click the aforementioned button in the right upper corner of any ADR

Expected Behavior

It should not lead to a 404 page and instead show the ADR as commited into the repository.

Environment

• Log4brains version: 1.0.0-beta.11
• Node.js version: v17.3.0.
• OS and its version: Manjaro linux / whatever gitlab.com uses
• Browser information: Firefox

Possible Solution

There is already a TODO comment in adr-transformers.ts. Making it configurable would be a nice-to-have feature addition, however it may not be needed to fix this bug for now. For instance, i do not have any repository url configured in .log4brains.yml – nevertheless log4brains correctly guesses the repository origin (pretty impressive btw 👏). I assume this magic happens somewhere in guessGitRepositoryConfig.ts.

Dirty fix

The details in guessGitRepositoryConfig.ts are currently a bit over my head, however it could simply check if a master branch exists at all, and if it doesn't, check for main. Having said that, as the whole industry is shifting towards calling the default branch main, so that should be checked first i guess.

Better fix

As far as my research and quick tests show, git remote show origin should reliably print the default HEAD branch .

Using git remote show origin | grep 'HEAD branch' | cut -d' ' -f5 in the extracts the name straightaway, though that cryptic foo is better of done in clean coded type script 😉

Bug Report

Description

As soon as one starts filling out the "Deciders" or "Tags" section, any HTML comments start are showing up as such in the knowledge base (i.e. the <!-- optional --> comment).

Looking at the generated HTML, it transpires that:

• The "Deciders" section renders the comment to <!-- optional -->
• The Tags section renders the comment #<!-- #optional #-->

Steps to Reproduce

1. create an ADR
2. Fill out either "Deciders:" or "Tags"
   Actually: just putting an additional space between [list everyone involved in the decision] and <!-- optional --> is enough to trigger the behaviour
3. Deploy or preview the knowledge base → the former HTML comments become visible

Expected Behavior

HTML comments should be ignored in generated output.

Environment

Log4brains version: 1.0.0-beta.11
Node.js version: v17.3.0.
OS and its version: Manjaro linux / whatever gitlab.com uses
Browser information: Firefox 96.0.2

Possible Solution

The parser that processes the "Deciders:" and "Tags:" section needs to be changed to recognize <!-- content --> and ignore them for processing (while still making them appear in the generated HTML output).

Feature Request

Feature Suggestion

So, huge fan of the project so far, but I would love to see some more customization. I have multiple ideas, but I think this is great start. Since Log4brains is intended to be installed into a subfolder (i.e. log4brains), why not have the ability to return back to the documentation/project site?

Context

• This would improve usability
• It allows for separation of concerns (one of the main things ADRs attempt to accomplish)
• Prevents a user from needing to navigate around manually
• Allows for better engagement on the analytics end (I don't really care about this, but some do)
• It's a no brainer

Possible Implementation

I could see two ways to accomplish this solution. One kinda easy and one kinda janky. The easy solution would be to have an option in the .log4brains.yml file to enable a link back to root (maybe linkToRoot: boolean). The janky solution would be to attempt to have the web application itself attempt to determine if it is indeed in a subdirectory and automatically generate the link back to the root. Either solution should be easy to implement since we have access to the location in the browser:

// You can have this one for free
const url = `${window.location.scheme}://${window.location.host}/`;

Alternatively, you could take the MKDocs or Docsify approach and allow users to define a top level navigation menu in the configuration file. For example (this is an MKDocs example since it seems like log4brains drew a lot of inspiration from that project):

nav:
  - Home: 'index.md'
  - Docs: '/'

I don't really know the structure of your project, so I don't think a PR would be all that helpful, plus I have my own style that doesn't always mesh well with other projects very well (hint: I am a former C# developer/TypeScript is the bee's knees).

Following the incident caused by a breaking change released in a dependency which does not follow semver: #74
And because of these reasons: https://gajus.medium.com/stop-using-package-lock-json-or-yarn-lock-909035e94328
I think we should not use yarn.lock anymore, and pin the versions of the project dependencies more strictly, and maybe use a tool like Renovate to assist us with their upgrades.

Feature Request

Feature Suggestion

This is working:

- Status: superseded by [20201016-use-the-adr-slug-as-its-unique-id](20201016-use-the-adr-slug-as-its-unique-id.md)

This is not working:

- Status: superseded by [custom name](20201016-use-the-adr-slug-as-its-unique-id.md)

-> Let's make it work!

Context

Today, the link name MUST be the ADR slug.
This choice was temporary to reduce the technical complexity of the project but it's too restrictive, especially when we have already existing ADRs.

See the discussion started by @ckolumbus (#22)

Possible Implementation

Have a look at the implementation on the links between ADRs, which is a feature that was added after this one, and which allows custom link names. It involves the MarkdownAdrLinkResolver.

Bug Report

Description

Unable to build / run yarn dev from either latest main branch or v1.0.1 tag branch

Steps to Reproduce

1. Forked Repo
2. Checkout branch for tag v1.0.1
3. using node v16.19.1 and yarn 1.22.19 run:
4. yarn install
5. yarn link-cli
6. yarn dev

Expected Behavior

Successful build without errors.

Environment

NAME="Ubuntu"
VERSION="20.04.5 LTS (Focal Fossa)"
node v16.19.1
yarn 1.22.19