adr / adr-log Goto Github PK

The name "adr-log" confused people, to this tool should be renamed to "adr-toc"

adr-log supports other formats such such as https://github.com/npryce/adr-tools/blob/master/doc/adr/0003-single-command-with-subcommands.md

When generating the log, the number at the beginning should be removed

Add a CHANGELOG.md in the format as described at http://keepachangelog.com/.

Example: Raw: https://raw.githubusercontent.com/eclipse/winery/master/CHANGELOG.md; Rendered: https://github.com/eclipse/winery/blob/master/CHANGELOG.md

Long example: https://github.com/JabRef/jabref/blob/master/CHANGELOG.md

Doc:

(Without this flag, the current working directory will be chosen as default)

But when runnign inside docs/adr, ../../index.md is generated. I tried it inside the madr repository.

For the purpose of continuous integration (CI), I'd like a script that will fail (as in exit non-zero) when someone adds a new ADR record but forgets to update the table of contents.

It could look something like:

adr-log -d ./docs/adrs/ -i --disallow-changes

If that command would otherwise require updating / creating a file, it would fail. Such a failure probably indicates that the commit author forgot to re-generate the table of contents.

The current work around is something like this in a CI script:

adr-log -d ./docs/adrs/ -i 
# Check to see if any files were modified and exit non-zero:
git status ...

The workaround is not too bad but it requires relying on something like git within CI and some bash magic.

As a point of reference prettier --check exists for a similar use case.

When running adr-log -i, the template is considered to be an ADR, and therefore included in the ToC of index.md.

This is not desierable, and template.md should be excluded.

I believe this is a result of "fallback to auto-numbering for ADRs without filename prefixes or frontmatter".

I'd considser this also not desierable.

Cloning this repo and running adr-log -h . in the docs/adr folder includes template.md.

I would like to enable

<!-- adr-log -- Regenerate the content by using "adr-log -i". You can install it via "npm install -g adr-log" -->

For me, it would also be OK, to support that string only in addition to <!-- adr-log -->.

When reading the documentation, I expect that adr-log -d . outputs the log to stdout. Currently, it prints the help.

Hi,

The last change seems to have introduced an error in the generation, such that the links to the ADRs are broken.
suggested fix: Either insert an extra slash or remove redundant ../[adr-dir]

• environment: Windows 10, using WinGit console
• ADR location within project structure:

/docs/[adr-dir]/  
    | 0000-first.md  
    | index.md   

from within [adr-dir], run
adr-log -i

Expected output:

<!-- adrlog -->

- [ADR-0000](0000-first.md) - First

<!-- adrlogstop -->

Actual output:

<!-- adrlog -->

- [ADR-0000](../[adr-dir]0000-first.md) - First

<!-- adrlogstop -->

adr-log -d ./ does produce correct output

Refs #18

When executing it on git bash on Windows without an existing index.md, the index.md is generated as follows:

This mirrors a security problem that exists in the forked package. Is there a chance you can fix it? jonschlinkert#135

While generating TOC and injecting it to the target file with command adr-log -d "adr" -i "index.md" additional new line is added every time after <!-- adrlogstop --><!-- adrlogstop -->. In the end even if there is no changes in ADR TOC, still the target file is reported as changed by git because of this additional empty line(s).

TOC links generated by Adr-log should take in consideration the path of the input and the directory of the adr-logs

Scenario

• with a following tree

.
├── docs
│   ├── README.md
│   ├── adr
│   │   ├── 0001-adr.md
│   │   ├── 0002-adr.md
│   │   ├── 0003-adr.md

• with the <!-- adrlog --><!-- adrlogstop --> on the docs/README.md
• if I execute this command

adr-log docs/README.md -d docs/adr/ -i

Expected Result:

- [ADR-0001](adr/0001-adr.md) - adr
- [ADR-0002](adr/0002-adr.md) - adr
- [ADR-0003](adr/0003-adr.md) - adr

Actual result:

- [ADR-0001](0001-adr.md) - adr
- [ADR-0002](0002-adr.md) - adr
- [ADR-0003](0003-adr.md) - adr

adr-log alone prints the help and does print a log into std out. adr-loc -d . should do that. Refs #1.

A set of architectural decision records is a architectural decision log. See first paragraph at https://adr.github.io/.

Therefore, all TOCs in the cli.js should be replaced with LOG:

E.g.,

The markdown file to contain the table of contents,
If no <file> file is specified, a index.md file containing the TOC is created in the given directory.

should change to

The markdown file to contain the decision log,
If no <file> file is specified, a index.md file containing the LOG is created in the given directory.

Take following MADR:

# Use Eclipse Orion as Editor
Editor should provide syntax highlighting and work in browser.

Then, Use Eclipse Orion as Editor should be the title, not Use Eclipse Orion as EditorEditor should provide syntax highlighting and work in browser.

Refs #5

Windows line endings are changed to Unix line endings in parts of the file. Either ALL line endings should be changed or the new line endings should be Windows, too (preferred).

How to design command line?

Options:

1. File always has to be given and file name at end: [-d <directory>] [-i] [<input>]. Current directory is used if no -d is given. If <input> is missing: help is printed
2. Directory always has to be given and directory name at end: [-f <file>] [-i] <directory>. If -f is not provided: Output to stdout without reading any index file

Chosen option: File always has to be given and filename at end. Reason: Consistency to markdown-toc. See https://github.com/jonschlinkert/markdown-toc#cli.

Please rewrite current CLI to this and update documentation accordingly.

Is bower.json really required? bower is deprecated: bower/bower#2298 and one should move away https://bower.io/blog/2017/how-to-drop-bower-support/

I think, adr-log is not registered at the bower registry, so bower.json can just be deleted?

An architectural decision record always has a title. See https://github.com/adr/madr/blob/master/docs/adr/template.md

The template is used at Eclipse Winery - see https://github.com/eclipse/winery/tree/master/docs/adr, which can be used for testing.

The MADR repository also contains an index file: https://github.com/adr/madr/blob/master/docs/adr/index.md. This index file describes the output. Please adapt adr-log to this output.

The npm badge shows v1.0.1 (https://www.npmjs.com/package/adr-log), but there is no tag "v1.0.1". Please create a tag and push it to github.