Consolidate documentation from auron-sites into auron to prevent divergence
- 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
Assessment
This issue has not been assessed yet.