apache / apache/auron

Consolidate documentation from auron-sites into auron to prevent divergence

Open
#2,157 2 comments 0 reactions 0 assignees View on GitHub
development-process documentation enhancement help wanted
Dominant language
Rust
Stars
1.8k
Forks
241
Avg merge
2d 14h
Merged PRs (30d)
22

Description

**Is your feature request related to a problem? Please describe.**

Documentation currently lives in two places: the main apache/auron repo (README, CONTRIBUTING) and apache/auron-sites (auron.apache.org)
- Content like getting-started, configuration, and benchmarks is duplicated across both repos
- Changes in one repo don't propagate to the other, leading to silent divergence
- Contributors submitting PRs to apache/auron have no way to ensure their documentation changes are
reflected on the website, and a lot of features don't directly make it to the documentation until a contributor manually updates

**Describe the solution you'd like**

Make `apache/auron` the single source of truth for all documentation content by adding a `docs/` directory in the main repo. This way:
- Every PR that changes behavior can include corresponding doc updates, tracked and reviewed together
- Documentation changes become part of the standard PR review cycle
- Minimize the divergence between the code repo and the website

If `apache/auron-sites` still needs to be managed separately (for site theme, layout, VuePress config,
deployment), it can use an extscm (or git submodule/subtree) to clone/pull the `docs/` content from
`apache/auron` at build time. The VuePress build in `auron-sites` would then render docs sourced from
`apache/auron`.

**Describe alternatives you've considered**

- **Keep the current two-repo setup** with a CI check that flags drift; but this adds complexity and
doesn't solve the fundamental problem of contributors needing to update two repos.
- **Move everything into `apache/auron`** is simpler, but may
not be desired if the site theme/layout/deployment needs to evolve independently.
- **Use a GitHub Action in `apache/auron` to auto-sync docs to `auron-sites`** on merge which reduces manual
drift but still keeps two repos as sources and adds CI complexity.

**Additional context**

N/A

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.