micronaut-projects / micronaut-projects/micronaut-docs

AsciiDocPropertyReferenceWriter is not reproducible

Open
#69 2 comments 0 reactions 0 assignees View on GitHub
status: awaiting feedback
Dominant language
CSS
Stars
11
Forks
17
PR merge metrics
No merged PRs in 30d

Description

Given the same inputs, the generated `config-properties.adoc` file might be different.

While working on refactoring the `micronaut-core` build, I wrote an utility to check that the generated jar files were the same byte-to-byte before and after the migration. I noticed that it wasn't the case because of 2 files:

- `config-properties.adoc`, generated by this project
- `spring-configuration-metadata.json`

Here's a file generated in a first round:

```asciidoc

++++
🔗
++++
.Configuration Properties for api:io.micronaut.scheduling.executor.UserExecutorConfiguration[]
|===
|Property |Type |Description

| `+micronaut.executors.*.n-threads+`
|java.lang.Integer
|

| `+micronaut.executors.*.type+`
|api:io.micronaut.scheduling.executor.ExecutorType[]
|

| `+micronaut.executors.*.parallelism+`
|java.lang.Integer
|

| `+micronaut.executors.*.core-pool-size+`
|java.lang.Integer
|

| `+micronaut.executors.*.thread-factory-class+`
|java.lang.Class
|

| `+micronaut.executors.*.name+`
|java.lang.String
|Sets the executor name.

| `+micronaut.executors.*.number-of-threads+`
|java.lang.Integer
|Sets the number of threads for {@link io.micronaut.scheduling.executor.ExecutorType#FIXED}. Default value (2 * Number of processors available to the Java virtual machine).

|===
<<<
++++
🔗
++++
.Configuration Properties for api:io.micronaut.runtime.ApplicationConfiguration.InstanceConfiguration[]
|===
|Property |Type |Description

| `+micronaut.application.instance+`
|api:io.micronaut.runtime.ApplicationConfiguration$InstanceConfiguration[]
|The instance configuration

| `+micronaut.application.instance.id+`
|java.lang.String
|The instance identifier

| `+micronaut.application.instance.group+`
|java.lang.String
|The instance auto scaling group

| `+micronaut.application.instance.zone+`
|java.lang.String
|The instance availability zone

| `+micronaut.application.instance.metadata+`
|java.util.Map
|The metadata to associate with the instance

|===
<<<
++++
🔗
++++
.Configuration Properties for api:io.micronaut.runtime.ApplicationConfiguration[]
|===
|Property |Type |Description

| `+micronaut.application.default-charset+`
|java.nio.charset.Charset
|Default value (UTF-8).

| `+micronaut.application.name+`
|java.lang.String
|Set the application name

|===
<<<
++++
🔗
++++
.Configuration Properties for api:io.micronaut.scheduling.io.watch.FileWatchConfiguration[]
|===
|Property |Type |Description

| `+micronaut.io.watch.enabled+`
|boolean
|Whether watch is enabled.

| `+micronaut.io.watch.restart+`
|boolean
|Set whether restart is enabled.

| `+micronaut.io.watch.paths+`
|java.util.List
|Sets the watch paths to use.

| `+micronaut.io.watch.check-interval+`
|java.time.Duration
|Sets the interval to wait between file watch polls.

|===
<<<
```

and the same file generated in another round:

```asciidoc

++++
🔗
++++
.Configuration Properties for api:io.micronaut.scheduling.executor.UserExecutorConfiguration[]
|===
|Property |Type |Description

| `+micronaut.executors.*.n-threads+`
|java.lang.Integer
|

| `+micronaut.executors.*.type+`
|api:io.micronaut.scheduling.executor.ExecutorType[]
|

| `+micronaut.executors.*.parallelism+`
|java.lang.Integer
|

| `+micronaut.executors.*.core-pool-size+`
|java.lang.Integer
|

| `+micronaut.executors.*.thread-factory-class+`
|java.lang.Class
|

| `+micronaut.executors.*.name+`
|java.lang.String
|Sets the executor name.

| `+micronaut.executors.*.number-of-threads+`
|java.lang.Integer
|Sets the number of threads for {@link io.micronaut.scheduling.executor.ExecutorType#FIXED}. Default value (2 * Number of processors available to the Java virtual machine).

|===
<<<
++++
🔗
++++
.Configuration Properties for api:io.micronaut.scheduling.io.watch.FileWatchConfiguration[]
|===
|Property |Type |Description

| `+micronaut.io.watch.enabled+`
|boolean
|Whether watch is enabled.

| `+micronaut.io.watch.restart+`
|boolean
|Set whether restart is enabled.

| `+micronaut.io.watch.paths+`
|java.util.List
|Sets the watch paths to use.

| `+micronaut.io.watch.check-interval+`
|java.time.Duration
|Sets the interval to wait between file watch polls.

|===
<<<
++++
🔗
++++
.Configuration Properties for api:io.micronaut.runtime.ApplicationConfiguration.InstanceConfiguration[]
|===
|Property |Type |Description

| `+micronaut.application.instance+`
|api:io.micronaut.runtime.ApplicationConfiguration$InstanceConfiguration[]
|The instance configuration

| `+micronaut.application.instance.id+`
|java.lang.String
|The instance identifier

| `+micronaut.application.instance.group+`
|java.lang.String
|The instance auto scaling group

| `+micronaut.application.instance.zone+`
|java.lang.String
|The instance availability zone

| `+micronaut.application.instance.metadata+`
|java.util.Map
|The metadata to associate with the instance

|===
<<<
++++
🔗
++++
.Configuration Properties for api:io.micronaut.runtime.ApplicationConfiguration[]
|===
|Property |Type |Description

| `+micronaut.application.default-charset+`
|java.nio.charset.Charset
|Default value (UTF-8).

| `+micronaut.application.name+`
|java.lang.String
|Set the application name

|===
<<<
```

Notice that while the contents is the same, the order of sections differ.

Contributor guide

Open the contributing guide

Research direction

Read AsciiDocPropertyReferenceWriter and reproduce generation of config-properties.adoc with identical inputs; compare the section ordering across runs. Done means repeated generation produces stable ordering and byte-identical output.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
documentation
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.