apache / apache/gravitino

[Improvement] Define a standard for Markdown document formatting

Open
#12,617 0 comments 0 reactions 0 assignees View on GitHub
documentation improvement
Dominant language
Java
Stars
3.2k
Forks
935
Avg merge
1d 17h
Merged PRs (30d)
339

Description

## Summary

Design-document reviews keep spending time on Markdown formatting, especially unaligned tables, because `design-docs/` has no written format standard and no shared lint environment.

## Desired outcome

Adopt markdownlint defaults as the standard, record only a few overrides, and enforce them with rumdl: local Gradle blocking, CI warn-only until a follow-up formats existing docs and turns CI blocking.

## Scope and boundaries

- **In scope**: `design-docs/**/*.md` in Apache Gravitino.
- **Non-goal**: product `docs/`, RFCs, or Enterprise docs in this first pass.
- **Non-goal**: a custom Gravitino Markdown aesthetic. Accept markdownlint defaults and override only where design docs already conflict.
- **Unchanged**: design-doc section structure; Apache license HTML comment as the first block.

## Acceptance criteria

- A Markdown document in `design-docs/` states the standard (defaults plus overrides).
- `.rumdl.toml` implements that document from markdownlint defaults.
- `./gradlew markdownlint` fails on violations (local blocking).
- CI on `design-docs/**` reports the same findings as warnings and does not fail the job.
- A later PR formats existing design docs, attaches the task to `check`, and makes CI blocking.

## How should we improve?

Ship the standard and warn-first CI now. Do not rewrite every existing table in the first PR.

- **Syntax**: GitHub Flavored Markdown
- **Default**: markdownlint `default: true`
- **Tables**: aligned pipes (Santilli / MD060)
- **Overrides**: MD013 120 and skip tables/code; MD040 off for ASCII diagrams; MD055 leading-and-trailing pipes
- **Runner**: rumdl, pinned and downloaded by Gradle so local and CI use the same binary
- **Local**: `./gradlew markdownlint` blocking; `./gradlew markdownlintFormat` to fix
- **CI**: same Gradle task with `-Pmarkdownlint.failOn=never`

Nevin
Sent from my 🤖 (Cursor)

Contributor guide

Open the contributing guide

Research direction

Start with the existing design-docs/**/*.md scope and locate the Gradle and CI configuration used for markdown checks. Add the standard document and .rumdl.toml, wire the blocking markdownlint and markdownlintFormat tasks, and configure CI for warn-only findings. Done means the stated acceptance criteria pass without rewriting existing design documents.

Written by the indexing model from the issue text.

Assessment

Tech stack
markdown
Domain
build-system, ci-cd, documentation
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
68/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.