feat: refine contribute pages (#25)

.vitepress/config.mts

@@ -103,8 +103,8 @@ export default defineConfig({
     },
     nav: [
       { text: "Getting Started", link: "/docs/guide/introduction" },
-      { text: "Contribute", link: "/docs/contribute/intro" },
       { text: "Learn", link: "/docs/learn/ecosystem" },
+      { text: "Contribute", link: "/docs/contribute/introduction" },
       { text: "Blog", link: "/blog/2022-02-10-js-tooling-research" },
       {
         text: "Playground",
@@ -146,28 +146,6 @@ export default defineConfig({
           ],
         },
       ],
-      "/docs/contribute/": [
-        { text: "Intro", link: "/docs/contribute/intro" },
-        { text: "Rules", link: "/docs/contribute/rules" },
-        {
-          items: [
-            { text: "Parser", link: "/docs/contribute/parser" },
-            { text: "Linter", link: "/docs/contribute/linter" },
-            { text: "Prettier", link: "/docs/contribute/prettier" },
-            { text: "Resolver", link: "/docs/contribute/resolver" },
-            {
-              text: "Transformer",
-              link: "/docs/contribute/transformer",
-            },
-            { text: "Formatter", link: "/docs/contribute/formatter" },
-            { text: "Codegen", link: "/docs/contribute/codegen" },
-            { text: "Minifier", link: "/docs/contribute/minifier" },
-            { text: "VSCode", link: "/docs/contribute/vscode" },
-          ],
-        },
-        { text: "Performance", link: "/docs/contribute/performance" },
-        { text: "Showcase", link: "/docs/contribute/showcase" },
-      ],
       "/docs/learn/": [
         {
           text: "Architecture",
@@ -213,6 +191,34 @@ export default defineConfig({
         { text: "Ecosystem", link: "/docs/learn/ecosystem" },
         { text: "References", link: "/docs/learn/references" },
       ],
+      "/docs/contribute/": [
+        {
+          text: "Contributing Guide",
+          items: [
+            { text: "Introduction", link: "/docs/contribute/introduction" },
+            { text: "Development", link: "/docs/contribute/development" },
+          ],
+        },
+        {
+          text: "Domain",
+          items: [
+            { text: "Parser", link: "/docs/contribute/parser" },
+            { text: "Linter", link: "/docs/contribute/linter" },
+            { text: "Prettier", link: "/docs/contribute/prettier" },
+            { text: "Resolver", link: "/docs/contribute/resolver" },
+            {
+              text: "Transformer",
+              link: "/docs/contribute/transformer",
+            },
+            { text: "Formatter", link: "/docs/contribute/formatter" },
+            { text: "Codegen", link: "/docs/contribute/codegen" },
+            { text: "Minifier", link: "/docs/contribute/minifier" },
+            { text: "VSCode", link: "/docs/contribute/vscode" },
+          ],
+        },
+        { text: "Performance", link: "/docs/contribute/performance" },
+        { text: "Showcase", link: "/docs/contribute/showcase" },
+      ],
       "/blog/": blogSidebar,
     },
   },

src/docs/contribute/development.md

@@ -0,0 +1,67 @@
+---
+title: Development
+outline: deep
+---
+
+# Development
+
+This page explains how to set up enrionment for OXC development.
+
+## Clone Repository
+
+```bash
+git clone --recurse-submodules --shallow-submodules git@github.com:oxc-project/oxc.git
+```
+
+The `--recurse-submodules` and `--shallow-submodules` flags are needed to initialize git submodules that are needed to run conformance tests.
+
+## Set Up Project
+
+### Install Rust
+
+If you have not yet installed Rust, follow [the official instruction](https://www.rust-lang.org/tools/install) and install Rust.
+
+After installing Rust, run the following command at the project root:
+
+```bash
+rustup show
+```
+
+`rustup show` reads the `./rust-toolchain.toml` file and installs the correct Rust toolchain and components for this project.
+
+### Install Project Tools
+
+#### `cargo-binstall`
+
+Some Cargo tools are required to develop OXC, and it is recommended to use [cargo binstall](https://github.com/cargo-bins/cargo-binstall), which provides a low-complexity mechanism to install rust binaries and is fater way than building them from source by running `cargo install`.
+
+```bash
+cargo install cargo-binstall
+```
+
+You can also download [the pre-compiled binary](https://github.com/cargo-bins/cargo-binstall#installation) and save it in `~/.cargo/bin`.
+
+#### `just`
+
+OXC utilizes [`just`](https://github.com/casey/just), which is a handy way to save and run project-specific commands:
+
+```bash
+cargo binstall just -y
+```
+
+#### Dependencies
+
+Run the following command in `justfile` at the project root to install dependencies:
+
+```bash
+just init
+```
+
+You can see the list of available commands by running `just`.
+
+You can run `just ready` (or, `just r` in short) to make sure the whole project builds and runs correctly.
+
+---
+
+Now you are ready to develop OXC!
+You can check out [good first issues](https://github.com/oxc-project/oxc/contribute) or ask us on [Discord](https://discord.gg/9uXCAwqQZW).

src/docs/contribute/introduction.md

@@ -0,0 +1,41 @@
+---
+title: Introduction
+outline: deep
+---
+
+# Introduction
+
+Thank you for getting interested in contributing to OXC project!
+Before starting, please make sure to read the following rules and policy.
+
+## General Rules
+
+- We welcome and appreciate any form of contributions.
+- Please create an issue or discussion if you want to make an architectural change.
+
+## PR Rules
+
+- We [prefer smaller PRs](https://graphite.dev/blog/how-large-prs-slow-down-development) for faster development.
+- Try stacked PRs with [graphite](https://graphite.dev) if you are given access permission to the repository.
+
+## Action Policy
+
+Taken from [Astral's values](https://astral-sh.notion.site/Astral-s-Values-0ed6a642bcc84e91af6836b2373572f5):
+
+> 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.
+
+## Development Policy
+
+- All performance issues (runtime and compilation speed) are considered as bugs in this project.
+- Embrace data-oriented design.
+- APIs should be simple and well-documented.
+- Third-party dependencies should be minimal.
+- Avoid the `regex` crate when possible. Regexes are slow, most of them can be rewritten in a performant way by using Rust iterator and string methods.
+- Avoid macros, traits or any Rust techniques that would penalize compilation speed.
+
+## Maintenance Policy
+
+- Monitor code coverage for unused code. Aim for 99% code coverage.
+- CI time should be actively monitored and reduced to speed up merging of PRs. The current CI time on GitHub actions is around 3 minutes.