adoble / adr-j Goto Github PK

Using the default locale for date formatting is not good in an international team.

Related:
https://github.com/GingerTommy/adr-cli/blob/master/docs/adr/0002-use-iso-8601-date-format.md

Having the following code in a unit test:

Record record = new Record.Builder(docPath, dateFormatter)
				.id(67)
				.name("This is a new record ")
				.template("rsrc:template.md")
				.build();

		record.store();

fails if the unit test is run locally within the IDE:

Reason is that using rsrc:template.md causes the record builder to try and find template.md as a resource in a JAR file. But all files are stored in the normal file store.

In addition, there are missing unit tests in RecordTest.java for user specified templates.

When no editor specified in environment variables and adr init is used, an error message is produced that complains about the missing environment variable and the command aborts.

Better behavior is to give a warning, but still initialize the directory.

The creation of native (GraalVM) images does not work and stops the build. Strong suspicion that this is due to the presence of the enum DataFormatterType in org.doble.commands.CommandConfig class which is used to specify the allowed parameters.

Currently have commented out the GraalVM native builds in both build.gradle and .travis.yml (the .circleci specification has not been changed and causes a build error with CircleCI).

Some of the tests are (subjectively) more complicated than the code they test.

Use case:

template.md

<!--
SPDX-FileCopyrightText: © {{year}} {{author}} <{{author_email}}>
SPDX-License-Identifier: Apache-2.0
-->
# {{id}}. {{name}}

Status: {{status}}
Date: {{date}}

More information

REUSE - Add copyright and licensing information to each file

Have a command to directly edit the ADR based on its id, e.g.:

adr edit 42

will open the configured editor on the ADR number 42.

A consequence is Travis CI is showing build as passing, but it can have unit test errors.

ADR 3 states that:

Running adr without any arguments lists the available subcommands

Current behavior is that an error message is returned. Needs correcting.

when I try this I get:

adr new wiki migration
java.lang.NumberFormatException: For input string: "imag"
	at java.base/java.lang.NumberFormatException.forInputString(NumberFormatException.java:67)
	at java.base/java.lang.Integer.parseInt(Integer.java:668)
	at java.base/java.lang.Integer.<init>(Integer.java:1127)
	at org.doble.commands.CommandNew.toInt(CommandNew.java:264)
	at java.base/java.util.stream.ReferencePipeline$4$1.accept(ReferencePipeline.java:214)
	at java.base/java.util.Iterator.forEachRemaining(Iterator.java:133)
	at java.base/java.util.Spliterators$IteratorSpliterator.forEachRemaining(Spliterators.java:1845)
	at java.base/java.util.stream.AbstractPipeline.copyInto(AbstractPipeline.java:509)
	at java.base/java.util.stream.AbstractPipeline.wrapAndCopyInto(AbstractPipeline.java:499)
	at java.base/java.util.stream.ReduceOps$ReduceOp.evaluateSequential(ReduceOps.java:921)
	at java.base/java.util.stream.AbstractPipeline.evaluate(AbstractPipeline.java:234)
	at java.base/java.util.stream.IntPipeline.reduce(IntPipeline.java:520)
	at java.base/java.util.stream.IntPipeline.max(IntPipeline.java:483)
	at org.doble.commands.CommandNew.highestIndex(CommandNew.java:251)
	at org.doble.commands.CommandNew.call(CommandNew.java:133)
	at org.doble.commands.CommandNew.call(CommandNew.java:40)
	at picocli.CommandLine.executeUserObject(CommandLine.java:1953)
	at picocli.CommandLine.access$1300(CommandLine.java:145)
	at picocli.CommandLine$RunLast.executeUserObjectOfLastSubcommandWithSameParent(CommandLine.java:2352)
	at picocli.CommandLine$RunLast.handle(CommandLine.java:2346)
	at picocli.CommandLine$RunLast.handle(CommandLine.java:2311)
	at picocli.CommandLine$AbstractParseResultHandler.execute(CommandLine.java:2179)
	at picocli.CommandLine.execute(CommandLine.java:2078)
	at org.doble.adr.ADR.run(ADR.java:99)
	at org.doble.adr.ADR.main(ADR.java:72)

Iam trying with the ad-j tool to test adr related features and I see supercede functionality is partially working

This is the sequence of steps i followed

1. adr init -i madr_initial.md -t madr.md -> Initial adr created under doc/adr
2. Then I issued following command adr new Use Java -> I see new adr created
3. Marked the status as Accepted in the newly created ADR
4. Then I issued adr new -s 2 use Golang
5. new ADR is created and in the new ADR i can see it Supercedes old ADR
6. But in ADR 2 I don't see Superseded by references as mentioned in the documentation.

Am i missing something?

Although explicitly stated in the installation instructions NOT to do this, if the environment variable ADR_EDITOR contains blanks AND apostrophes are used then adr-j crashes.

ADRs whose title starts with more than one capital letter are not correctly formatted in the ADR file name. For instance the title:

CDR is stored in a relational database

produces as a file name (assuming this is the 8th ADR to be created):

0008-cDR-is-stored-in-a-relational-database

Suggestion:

adr init -t [template_file_name] [adr_folder]

The template_file_name specifies the structure and subsequent adr commands (such as adr new) use this structure.

Could also add adr check [template file name] to check if the template is correctly formed and allows the basic fields such as title, date etc.

It should be mentioned somewhere and the options should be explained.

Currently, it is only implicitly it is described by adr config.

As well as the terse options such as -l have as alternative long option names such as --link

Hi!

I have converted the example madr templates to Asciidoc.
example_templates.zip
When using this, {{{link.file}}} seems to empty in generation.
Problem seems to be the hard reference to markdown md in the glob variables in ADRFilter.java.

Example:
adr init -i \madr_initial.adoc -t \madr.adoc
adr new -link=1:"Amends":"Amended by" define template directory

Output:

• Amends link:[ADR 1]

Environement: Windows 11, JRE 8

Best regards
Torsten

The current README page serves as a quick "getting started" to ADR-J. However, as the number of commands increases I would propose a more complete set of documentation (in addition to the README file) . Apparently this can be generated from the code annotations using tools provided by the PICOCLI project. This need to be investigated.

I would propose to rename doc to docs (at least in this repository) to enable rendering of the docs using gh-pages (see https://help.github.com/en/articles/configuring-a-publishing-source-for-github-pages) and to be consistent to other GitHub repositories.

I know that adr-tools rejected that proposal: npryce/adr-tools#39 - maybe, you can spend a thought regarding that, too.

Have the possibility that ADRs can be generated using Asciidoc instead of markdown

It would be nice if one could install adr-j via homebrew.

Similar to the existing brew install adr-tools.

To avoid conflicts, the environment variables EDITOR and VISUAL should be prefixed with ADR_, i.e.

ADR_EDITOR
and
ADR_VISUAL

Running the following in the Git Bash shell in windows terminal:

$ adr --help
←[31m←[1mUnknown option: '--help'←[21m←[39m←[0m
Usage: ←[1madr←[21m←[0m [COMMAND]
Creation and management of architectural decision records (ADRs)
Commands:
  ←[1minit←[21m←[0m     Initialise the directory of architecture decision records:
            * creates a subdirectory of the current working directory
            * creates the first ADR in that subdirectory, recording the
             decision to record architectural decisions with ADRs.
  ←[1mnew←[21m←[0m      Creates a new, numbered ADR.  The <title_text> arguments are
             concatenated to form the title of the new ADR. The ADR is opened
             for editing in the editor specified by the VISUAL or EDITOR
             environment variable (VISUAL is preferred; EDITOR is used if
             VISUAL is not set).  After editing, the file name of the ADR is
             output to stdout, so the command can be used in scripts.
  ←[1mlist←[21m←[0m     Lists the filenames of the currently created architecture decision
             records.
  ←[1mversion←[21m←[0m  Prints the version of adr-j.
  ←[1medit←[21m←[0m     Starts the editor on the specified ADR
  ←[1mconfig←[21m←[0m   List of the currently set properties.
  ←[1mlink←[21m←[0m     Links ADRs with one another.
  ←[1mhelp←[21m←[0m     Displays help information about the specified command
Exit Codes:
   0   Successful program execution.
  64   Invalid input: an unknown option or invalid parameter was specified.
  70   Execution exception: an exception occurred while executing the business
         logic.
Environment Variables:
  ADR_VISUAL   The editor to use to edit ADRs. Ignored, if ADR_EDITOR set
  ADR_AUTHOR   The author of the ADR
  ADR_EDITOR   The editor to use to edit ADRs

It would be useful to have an author field substitution.

The author could be determined by using the JVM property "user.name" or a new environment variable ADR_AUTHOR.

ADR 2 references an implementation in Java 8. Update with decision to use last LTS version of Java.

As JCenter is sunsetting (see https://jfrog.com/blog/into-the-sunset-bintray-jcenter-gocenter-and-chartcenter), need to remove references to it in build.gradle

if you had a jbang-catalog defined we could do:

jbang app install adr@adoble and have it available as adr on any platform supporting java.

I didn't find adr jar published anywhere but by using jitpack you can mimck it:

jbang app install --name adr --repos jitpack -m org.doble.adr.ADR com.github.adoble:adr-j:LATEST

now you can runadr

I'll open PR with example catalog if you are interested. best would be if you created adoble/jbang-catalog repo then the name would just be adr@adoble rather than adr@adoble/adr-j

Running the following:

adr new This has been superseded

Gives the following error message:

Unknown option: 'superseded'
Possible solutions: supersedes

@tkleiber has noticed that:

• ADR 4 only refers to markdown and not to other mark up formats such as ASCIIDOC
• The main README does not make it clear that other mark up formats such as ASCIIDOC can used.

Hi!

reverse_link_description seems to imply to me, that in the previous ADR is created a reverse link too.
This is not the case, so what should the parameter do?

Example:
adr new -l=2:a:b test

New ADR contains:
* A [ADR 2](0002-define-template-directory.md)

Previous ADR 2 contains no link.

Environement: Windows 11, JRE 8

Best regards
Torsten

If some of the previous issues are implemented we are starting to have a number of options. Having all these handled during init is maybe too much and a developer may want to change them after initialization.

Propose a config command, e.g.:

adr config editor /usr/bin/vim
adr config dir docs/records
adr config template ~/templates/madr
adr config format asciidoc