thomvaill / log4brains Goto Github PK
View Code? Open in Web Editor NEW✍️ Log and publish your architecture decisions (ADR)
License: Apache License 2.0
✍️ Log and publish your architecture decisions (ADR)
License: Apache License 2.0
log4brains-web build
also deploys a PNG badge to display in the project's README that displays the number of ADRs.
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.
Ctrl-C does not stop log4brains preview when run in Docker
docker run --rm -ti -v $(pwd):/workdir -p 4004:4004 thomvaill/log4brains preview
In step 3, log4brains and the container should stop.
You can stop the container by running docker ps
and running docker stop <container id>
but this is cumbersome.
thomvaill/log4brains latest 7bb84c921b02 6 weeks ago 412MB
I do not have a solution right now, but maybe playing with the Docker entrypoint / cmd can fix this.
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:
<!-- optional -->
#<!-- #optional #-->
[list everyone involved in the decision]
and <!-- optional -->
is enough to trigger the behaviourHTML comments should be ignored in generated output.
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
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).
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.
master
It should not lead to a 404 page and instead show the ADR as commited into the repository.
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
.
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.
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 😉
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.
docs/adr
log4brains build
.log4brains/out/adr
does not contain an HTML file matching the name of your markdown filelog4brains build
.log4brains/out/adr
does contain an HTML file matching the name of your markdown fileAll markdown files should be compiled into HTML on the first invocation of log4brains build
.
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.
Originally posted by raghuwarrier September 30, 2022
I am looking forward to using this tool locally. One of the requests I received was to customise the color theme. Is there an easy way to do this? Thanks.
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
It shall be possible to host the generated static website within a sub-path of the web server.
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).
Suggestion: convert all generated path elements to be relative.
Code formatting causes long lines in the web interface.
Open an adr and create a markdown section that has a ```````` formatting section that has overly long text.
Line should not overflow.
This bug makes the markdown unreadable and unprintable (with ink and toner).
In css: usually you set width and then use overflow: auto on <code> elements.
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.
The browser page should refresh itself, i need to force reload to see updates.
I was just exploring features, but the hot reload is something that boost DX, so hope to solve with your help 🙂
I cant find any workaround or root cause
PS: thanks for all your time and effort 🙏
Deploy core TypeDoc documentation on GitHub Pages and update its link in core README.
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
)
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?
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).
I had some issues with comments.
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)
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).
Comment is ignored.
log4brains preview
Looking at rendered pages in the previewer.
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'
}
Should work :-)
Probably some dependency updates.
I am waiting for user feedback before going further.
Support diagraming with nomnoml.
I wanted to add one diagram to every decision.
Allow the logo of the project to be set
Add branding.
Add a yml config for this and change the web ui.
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'
See the above steps. I literally just used the default options, except for choosing a multi-package project.
I'm not sure what the command is trying to do. Perhaps replacing {DATE_YESTERDAY}
with the actual date.
Regression of a previous bug report from last year regarding a NextJS Hack. issue #27
log4brains init
log4brains preview
fails with the error:FATAL Cannot read property 'incrementalOptions' of undefined
log4brains build
works and the output is generated but not entirely.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
Fixed reference to NextJS
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.
Fix the reference to the NEXTJS.
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.
It would be of great value if we could get some views that were filtered down by a given package.
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.
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.
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.
<!-- 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.
The knowledge base should not crash.
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.
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
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!
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)
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
.
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.
log4brains init
log4brains adr new
log4brains build
The command should build the static pages for hosting
I tried to run the build command and it failed due to sharp not being found.
❯ 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.
To build the site successfully.
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.
Add sharp
to list of dependencies.
Print CSS issues:
Executing log4brains preview
fails with Fatal Cannot read property 'incrementalOptions' of undefined
message
The full log can be seen below, but it is quite easy:
log4brains init
log4brains preview
Seeing the preview
I cannot see a preview of the ADRs
links in index.html does not contain .html
suffix, but generated html files has.
log4brains build -o public
should generated links with .html
suffix
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.
As github supports mermaid.js diagrams in markdown, it would be nice to also support it in the generated html files.
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;
\```
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
log4brains --version
log4brains --version
(and the majority of other commands) should be instant.
Either fix the esm
package or get rid of it by compiling to commonJS all of our packages... (like the core
one).
Originally posted by qrush July 7, 2021
Is there a way we could easily copy over a jpg, png, etc with an ADR? It seems like the build/preview process ignores images.
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.
I get an error when I run log4brains init on a new install:
Error: Cannot find module '@hapi/hoek/assert'
npm i -g log4brains
log4brains init
It should not throw an error
Unable to build / run yarn dev from either latest main branch or v1.0.1 tag branch
Successful build without errors.
NAME="Ubuntu"
VERSION="20.04.5 LTS (Focal Fossa)"
node v16.19.1
yarn 1.22.19
For now, the e2e tests only cover the CLI.
We also want to check at least that:
log4brains-web preview
starts without errorhttp://localhost:4004
log4brains-web build
finishes without errorserve
log4brains-web preview
Cypress vs Puppeteer
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
?
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
the output generated by log4brains build
is broken
npm install -g log4brains
log4brains init
log4brains build
.log4brains/out
The static website should work
I can't deploy to gitlab pages or whatever using the procedure explained in the README.md
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'
Log4brains should work as expecte...
Simply trying to init log4brains
npm -g list
/usr/local/lib
├── [email protected]
└── [email protected]
Homebrew availability to install on macOS
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
For now, the default directory for ADRs is docs/adr
, because it was commonly documented like this:
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.
docs/adr
in the READMEdocs/adr
in the code, only when it is used as a default valueLog4Brain does not SEO the project. Instead it SEOs log4brains.
Use the Log4Brains to export a website. Look at the title.
It should use the project name and not log4brains
.
Want to brand the repository.
Log4brains should be able to serve local images that are displayed in the markdown files.
Have a look at next/image
Offer a custom cli cmd name when setting up the project instead of the fixed log4brains
.
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
.
When templates do not exist, the --from
flag is ignored, and an error is thrown.
See the sample repository
--from
flagA new ADR is generated from the file specified by --from
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.
^1.0.0-beta.11
v16.13.0
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.
Have "complete" CLI commands for workflow/lifecycle management of ADRs
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 🤔
proposed
to accepted
#27 has been open for 1 month and has not been resolved.
Run cicd Github Actions and watch the build break.
Resolved breakage within a month.
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.
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.
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
Superseded ADRs in multi package project should be work like mono package project.
We tried with mono package structure and it worked like expected.
We want to create ADRs in multi package project structure.
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.