From d23a73c72c50cf15bb7ab3bfb45f255fd7c18be3 Mon Sep 17 00:00:00 2001 From: Nozomu Ikuta <16436160+NozomuIkuta@users.noreply.github.com> Date: Sun, 26 Nov 2023 21:16:10 +0900 Subject: [PATCH] feat: refine contribute pages --- .vitepress/config.mts | 52 ++++++++++++---------- src/docs/contribute/development.md | 67 +++++++++++++++++++++++++++++ src/docs/contribute/intro.md | 59 ------------------------- src/docs/contribute/introduction.md | 41 ++++++++++++++++++ src/docs/contribute/rules.md | 38 ---------------- 5 files changed, 137 insertions(+), 120 deletions(-) create mode 100644 src/docs/contribute/development.md delete mode 100644 src/docs/contribute/intro.md create mode 100644 src/docs/contribute/introduction.md delete mode 100644 src/docs/contribute/rules.md diff --git a/.vitepress/config.mts b/.vitepress/config.mts index 8b0d2d1f6a..d3a03b1b6c 100644 --- a/.vitepress/config.mts +++ b/.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, }, }, diff --git a/src/docs/contribute/development.md b/src/docs/contribute/development.md new file mode 100644 index 0000000000..975e51f455 --- /dev/null +++ b/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). diff --git a/src/docs/contribute/intro.md b/src/docs/contribute/intro.md deleted file mode 100644 index bf82bfe7d3..0000000000 --- a/src/docs/contribute/intro.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: Contribute -outline: deep ---- - -# Where to start - -Check out some of the [good first issues](https://github.com/oxc-project/oxc/contribute) or ask us on [Discord](https://discord.gg/9uXCAwqQZW). - -## Clone Repo - -```bash -git clone --recurse-submodules --shallow-submodules git@github.com:oxc-project/oxc.git -cd oxc -``` - -The `--recurse-submodules --shallow-submodules` flag will also initialize git submodules that are needed to run conformance tests. - -## New to Rust - -### Install Rust - -```bash -curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -rustup show -``` - -`rustup show` reads the `./rust-toolchain.toml` file and installs the correct Rust toolchain and components for this project. - -### Cargo Tools - -Some additional Cargo tools are required for developing this project, they can be installed via [`cargo binstall`](https://github.com/cargo-bins/cargo-binstall). - -```bash -cargo install cargo-binstall -``` - -`cargo binstall` provides a low-complexity mechanism for installing rust binaries as an alternative to building from source via the slower `cargo install`. - -You can also download the [pre-compiled binary](https://github.com/cargo-bins/cargo-binstall#installation) and save it in `~/.cargo/bin`. - -## Required tools - -```bash -cargo binstall just -y -``` - -[`just`](https://github.com/casey/just) is a handy way to save and run project-specific commands. -To initialize all the required tools, run - -```bash -just init -``` - -## Commands - -Run `just` for the list of available commands. - -Run `just r` (alias for `just ready`) to make sure the whole project builds and runs correctly. diff --git a/src/docs/contribute/introduction.md b/src/docs/contribute/introduction.md new file mode 100644 index 0000000000..2b22fae6d1 --- /dev/null +++ b/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. diff --git a/src/docs/contribute/rules.md b/src/docs/contribute/rules.md deleted file mode 100644 index 17922530d0..0000000000 --- a/src/docs/contribute/rules.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: Rules -outline: deep ---- - -# Rules - -- We welcome and appreciate any form of contributions. -- Please create an issue or discussion if you are making an architectural change. - -## PR related - -- [Prefer smaller PRs](https://graphite.dev/blog/how-large-prs-slow-down-development), they will get merged quickly. -- Try stacked PRs with [graphite](https://graphite.dev) if repo write permission is given to you. - -## Architecture - -- 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 - -- 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. - ---- - -### Bias towards action - -(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.