Introduction

PR Rules

• We prefer smaller PRs.
• Try stacked PRs with graphite if you have write access, which will be given to you when you contribute a lot.
• Please create an issue or discussion if the PR contains architectural changes.

Development Policy

• Embrace data-oriented design.
• Keep APIs simple and well-documented.
• Always provide a reference to the source if the implementation is from another project.

Performance

• All performance issues are considered as bugs in this project, this includes all runtime and compilation performance issues.
  • Follow guidance from the Rust performance book.
  • Minimize the use of the regex crate. Use Rust iterators and string methods for better performance.
• Compile time must be minimized to reduce impact on development workflow and downstream tools.
  • Minimize third-party dependencies to reduce compilation speed and project complexity.
  • Avoid heavy macros, generics, or any Rust techniques that slow down compilation.
  • Our CI runs complete in 3 minutes, any regressions need to be fixed.

Maintenance Policy

• Monitor code coverage for unused code. Aim for 99% code coverage.
• Actively monitor and work on reducing the CI time to speed up merging of PRs. The current CI time on GitHub actions is around 3 minutes.
• Documentation first - documentation should serve as the source of truth. Keep the documentation updated and share the link instead of repeatedly answering the same questions. See GitLab's handbook-first approach.
• Consistent import orders: "furthest away" to "closest".
  • std
  • External crates
  • Oxc crates
  • Local crate (crate)
  • super
  • mod

Conventional Commits

We follow conventional commits:

The commit contains the following structural elements, to communicate intent to the consumers:

• fix: a commit of the type fix patches a bug in your codebase.
• feat: a commit of the type feat introduces a new feature to the codebase.
• BREAKING CHANGE: a appends a ! after the type/scope, introduces a breaking API change, e.g. feat(parser)!: new feature.
• the scopes are crate names.
• the types are feat:, fix:, chore:, ci:, docs:, style:, refactor:, perf: and test:.

Action Policy

Taken from Astral's values:

We bias towards action, even in the face of uncertainty. We favor pragmatic doing over prolonged debating; we favor asking for forgiveness over permission. We value decisiveness — especially when a decision isn’t clear cut, and especially when a decision is reversible.

A bias towards action is not the same as recklessness. Rather, it’s a bias towards making responsible decisions and acting on them with urgency, even if we’re left with lingering ambiguity or known unknowns.