Proposal: Splitting the AReaL Repo for Better Governance

[mingcheng]

Your Idea

Hi everyone! I'm mingcheng, a Maintainer of the CNCF graduated project dragonfly. I'd like to kick off a discussion about splitting up the AReaL repository.

Background

As you've probably noticed, AReaL now lives under its own areal-project GitHub Organization. As the project keeps growing, keeping all the code and surrounding materials in a single mono-repo has started to cause some friction for both development and day-to-day management. To make governance more fine-grained and to lower the bar for new contributors, I'd like to propose splitting the current repo into a few smaller ones.

Proposed Split

I suggest breaking things up along functional lines and target audience, into the following repos:

1. AReaL
   Stays as the core code repo, focused purely on iterating on the core logic.

2. community
   For community governance, events, contributor management, and other non-code work. Could include:

   • Contributing Guide
   • Meeting notes
   • Community event announcements
   • Contributor list and shout-outs
   • Discussions and proposals (via Issues or Discussions)

3. website
   The official website codebase — frontend pages, blog, etc. This lets frontend-focused contributors jump in directly without having to wade through the complexity of the core code.

4. docs (or document)
   A dedicated docs repo for the user guide, API reference, developer docs, and so on. Makes it much easier for docs contributors to send quick fixes.

Why This Helps(In Short Ways)

• Fine-grained permissions: Inside the org, we can set up different teams per repo. For example, we can give docs-focused contributors Maintainer rights on docs without handing out write access to the core code.
• Faster CI/CD: Each repo has its own build and test pipeline. Tweaking the website or docs won't trigger the heavy core test suite anymore, so PRs get validated a lot faster.
• Decoupled release cadence: The core library (maybe a major release every six months) and the website/docs (which may change daily) can each have their own versioning and release rhythm.
• Lower contribution barrier: A newcomer facing a small, single-purpose repo has a much easier time getting their head around the code and sending a PR than someone dropped into a giant, tangled mono-repo.

Suggested Execution Plan

To preserve commit history and keep the transition smooth, I suggest these steps:

1. Freeze window: Pick a weekend or other time as a code-freeze window and stop merging any PRs, and clean duplicated branches.
2. CI/CD setup: Configure and verify the GitHub Actions pipelines in each new repo.
3. Issue migration: Use GitHub's built-in Transfer Issue feature to move the existing issue backlog into the matching sub-repo.
4. Cleanup and signposting: Remove the moved directories from the original areal repo, and add a navigation section in its README linking out to the new repos.

I'd love to hear your thoughts below — especially on whether the split granularity feels about right. Thanks!

Use Case

No response

Alternatives

No response

Contribution

• I'd like to work on this if it's accepted

[garrett4wade]

Sounds great! What about raising this up in the next biweekly community meeting 2026/05/30?

[mingcheng]

Alright, I'll bring up this proposal at the upcoming community meeting.