Skip to main content

​
Contribution Workflow

Loong treats docs, tests, verification, and architecture boundaries as part of a complete contribution.

​
Contribution Tracks

Loong publicly distinguishes two contribution tracks.

​
Validation Bar

The public minimum validation bar is:
The main local convenience gate is:
If a contribution changes architecture-sensitive areas, contributors should also expect to run the repo’s architecture and dependency checks instead of assuming CI will discover every boundary regression later.

​
Docs Change Loop

For reader-facing docs work under site/, use the docs-specific validation loop in addition to the normal repository bar that still applies to the branch.
That loop belongs to the public contribution workflow because Mintlify docs are deployed from this repository, not from a separate docs repo. The versions are pinned so contributors do not hit two avoidable false failures: a transient registry mismatch on Mintlify, or an unsupported local Node 25+ shell leaking into the docs validation path. The extra PATH step is intentional because Mintlify’s wrapper spawns node from the shell path instead of reusing the outer npm exec runtime automatically. GitHub Actions mirrors this same loop in the docs-site job, so docs pull requests should be reproducible locally before review. The CI export step is time-bounded because Mintlify can occasionally leave the process alive after the static export artifact has already been written.

​
Standard Workflow

  1. Branch from dev.
  2. Keep commits focused on one task or one coherent slice of work.
  3. Run the relevant validation checks before opening a PR.
  4. Open the PR against dev.
  5. Address review feedback without letting the branch sprawl into unrelated work.

​
When To Start With An Issue First

Open an issue or discussion before deep implementation when:
  • the change affects kernel or policy behavior
  • the change weakens or reshapes a public contract
  • the change is large enough that scope alignment matters more than coding speed
  • you are not sure whether the work belongs in Track A or Track B

​
What Maintainers Expect

  • public architecture boundaries should be preserved rather than bypassed
  • reader-facing docs should be updated when the public contract changes
  • generated or agent-assisted code still needs human ownership and review
  • smaller, reviewable diffs are preferred over opaque drops that no reviewer can defend

​
Issue Intake

​
Documentation Language Scope

  • The repository keeps Simplified Chinese support only for README.zh-CN.md.
  • The Mintlify site under site/ is the main English reader-facing docs surface.
  • Repository markdown under docs/ remains public as supporting reference and source-facing material.
  • If broader docs i18n is introduced later, it should happen at the docs-site layer instead of by expanding repository-wide markdown translation.

​
Deep References