Markdown Tables Formatting Convention

[ata-nas]

To Discuss

• what shall be our accepted convention to format the md tables

Reason

• we always change the whole formatting back and forth (done automatically by our IDEs usually) and that creates a needless effort.
• we should come up with a convention as to how we are going to format the tables and stick with it

Discussion

There are two ways to format the md tables:

---

Example 1:

| Environment Variable                  | Description                                                           |       Default Value |
| :------------------------------------ | :-------------------------------------------------------------------- | ------------------: |
| PERSISTENCE_STORAGE_LIVE_ROOT_PATH    | The root path for the live storage.                                   |                     |
| PERSISTENCE_STORAGE_ARCHIVE_ROOT_PATH | The root path for the archive storage.                                |                     |
| PERSISTENCE_STORAGE_TYPE              | Type of the persistence storage                                       | BLOCK_AS_LOCAL_FILE |
| PERSISTENCE_STORAGE_COMPRESSION       | Compression algorithm used during persistence (could be none as well) |                ZSTD |
| PERSISTENCE_STORAGE_COMPRESSION_LEVEL | Compression level to be used by the compression algorithm             |                   3 |
| CONSUMER_TIMEOUT_THRESHOLD_MILLIS     | Time to wait for subscribers before disconnecting in milliseconds     |                1500 |
| SERVICE_DELAY_MILLIS                  | Service shutdown delay in milliseconds                                |                 500 |
| MEDIATOR_RING_BUFFER_SIZE             | Size of the ring buffer used by the mediator (must be a power of 2)   |            67108864 |
| MEDIATOR_TYPE                         | Type of mediator to use                                               |                     |
| NOTIFIER_RING_BUFFER_SIZE             | Size of the ring buffer used by the notifier (must be a power of 2)   |                2048 |
| PRODUCER_TYPE                         | Type of producer to use                                               |                     |
| SERVER_PORT                           | The port the server will listen on                                    |                8080 |
| SERVER_MAX_MESSAGE_SIZE_BYTES         | The maximum size of a message frame in bytes                          |             1048576 |
| PROMETHEUS_ENDPOINT_ENABLED           | Whether the Prometheus metrics endpoint is enabled                    |                true |
| PROMETHEUS_ENDPOINT_PORT_NUMBER       | The port number for the Prometheus metrics endpoint                   |                9090 |

Pros:

• more human readable in raw format

Cons:

• we rely on IDE formatting (most likely) to support this formatting when we change the table
• without automatic formatting it is very hard to manually maintain
• redundant whitespaces and dashes

---

Example 2:

| Environment Variable | Description | Default Value |
|:---|:---|---:|
| PERSISTENCE_STORAGE_LIVE_ROOT_PATH | The root path for the live storage. | |
| PERSISTENCE_STORAGE_ARCHIVE_ROOT_PATH | The root path for the archive storage. | |
| PERSISTENCE_STORAGE_TYPE | Type of the persistence storage | BLOCK_AS_LOCAL_FILE |
| PERSISTENCE_STORAGE_COMPRESSION | Compression algorithm used during persistence (could be none as well) | ZSTD |
| PERSISTENCE_STORAGE_COMPRESSION_LEVEL | Compression level to be used by the compression algorithm | 3 |
| CONSUMER_TIMEOUT_THRESHOLD_MILLIS | Time to wait for subscribers before disconnecting in milliseconds | 1500 |
| SERVICE_DELAY_MILLIS | Service shutdown delay in milliseconds | 500 |
| MEDIATOR_RING_BUFFER_SIZE | Size of the ring buffer used by the mediator (must be a power of 2) | 67108864 |
| NOTIFIER_RING_BUFFER_SIZE | Size of the ring buffer used by the notifier (must be a power of 2) | 2048 |
| SERVER_PORT | The port the server will listen on | 8080 |
| SERVER_MAX_MESSAGE_SIZE_BYTES | The maximum size of a message frame in bytes | 1048576 |

Pros:

• very easy to support
• no redundant dashes and whitespaces
• no need for automatic formatting tool (which some may not have)

Cons:

• less human readable when raw

---

Final Disposition

The Heiro organization has chosen to apply global format to markdown, and this project will follow that format.

[ata-nas]

@jsync-swirlds @AlfredoG87 @mattp-swirldslabs @georgi-l95

Let's vote on this and come up with a convention that we must follow, we have a lot of conflicts about this formatting.

I suggest:
Those in favor of Example 2 above (this includes me), upvote.

[mattp-swirldslabs]

Is there already a company precedent?

[AlfredoG87]

yes, I have found many examples across services and mirror node where they use example 1.
https://raw.githubusercontent.com/hashgraph/hedera-services/refs/heads/develop/docs/hedera-java-style-guide.md
https://raw.githubusercontent.com/hashgraph/hedera-services/refs/heads/develop/hedera-node/docs/system-accounts-operations.md
https://raw.githubusercontent.com/hashgraph/hedera-mirror-node/refs/heads/main/docs/configuration.md
https://raw.githubusercontent.com/hashgraph/hedera-mirror-node/refs/heads/main/docs/troubleshooting.md

that said, I've also found examples similar to example 2.

https://raw.githubusercontent.com/hashgraph/hedera-services/refs/heads/develop/hedera-node/docs/autorenew-feature.md
https://raw.githubusercontent.com/hashgraph/hedera-services/refs/heads/develop/hedera-node/docs/privileged-transactions.md

• Mirror node is more strict and there all tables are formatted like example1, we also do it like that on relay.

[jsync-swirlds]

It's very inconsistent in some of the other projects.
There isn't truly a precedent, more just people accepting IDE default behavior without thinking.

[jasperpotts]

I vote for Example 1 😀 little more work if IDE does not help you but so much more readable and easy to verify you have right thing in right column

[AlfredoG87]

IntelliJ does the format automatically for you, so is actually easier. (however I guess you can configure the IDE either way, but example 1 is the default)

[jasperpotts]

I would have done it manually if IDE did not do it for me. I am fussy about formatting. I brain is very visual so having things in being ordered and structured makes a huge difference in readability for me.

[jsync-swirlds]

I find the second example much easier to read, particularly if the table ends up large (I've seen tables that scroll forever even on really large screens).

If I want to check the visual, I just look at the rendered view (which IDEs also do for you).

[ata-nas]

So, the result currently seems to be:
(no pun intended!)

Example 2 as convention

For	Against	Undecided
@ata-nas
@jsync-swirlds
	@jasperpotts
	@AlfredoG87
	@mattp-swirldslabs
		@georgi-l95

@mattp-swirldslabs @georgi-l95 feel free to add yourselves since I cannot deduce from the discussion :)

[jjohannes]

With #216, automatic Markdown formatting (using Flexmark) is now in place when running qualityGate (or spotlessApply directly). Next time a Markdown file is changed, it will automatically reformat the tables to something like Example 1 above.

This is the same formatting convention shared by all other Java-based repositories that use the setup.

It would be desirable to have the same formatting done everywhere to keep maintenance low. If there are strong opinions against the current setup, you can discuss that and maybe we can also make adjustments that apply to all repos.

This is the current configuration, which is based on what was configured in hedera-services:
https://github.com/hiero-ledger/hiero-gradle-conventions/blob/main/src/main/kotlin/org.hiero.gradle.check.spotless-markdown.gradle.kts

[jsync-swirlds]

These are markdown files, not YAML.
Is the YAML format convention applying to Markdown?

[AlfredoG87]

Thank you @jjohannes, I believe this should close the discussions if we are now using a company wide convention 👍

[jjohannes]

Thanks for clarifying @jsync-swirlds . I meant to write Markdown. Corrected now.