docs: polish contribution guide

.github/CONTRIBUTING.md

@@ -1,3 +1,3 @@
-- For contribution guide, please refer to the deployed version at: https://rolldown.rs/dev-guide/
+- For contribution guide, please refer to the deployed version at: https://rolldown.rs/contrib-guide/
 
-- The source is also in this repo: https://github.com/rolldown-rs/rolldown/blob/main/web/docs/dev-guide/
+- The source is also in this repo: https://github.com/rolldown-rs/rolldown/blob/main/web/docs/contrib-guide/

web/docs/.vitepress/config.ts

@@ -5,32 +5,51 @@ export default defineConfig({
   title: 'Rolldown',
   description:
     'Fast JavaScript/TypeScript bundler in Rust with Rollup-compatible API',
+
+  lastUpdated: true,
+  cleanUrls: true,
+
+  /* prettier-ignore */
+  head: [
+    ['link', { rel: 'icon', type: 'image/svg+xml', href: '/lightning-down.svg' }],
+    ['meta', { name: 'theme-color', content: '#ff7e17' }],
+    ['meta', { property: 'og:type', content: 'website' }],
+    ['meta', { property: 'og:locale', content: 'en' }],
+    ['meta', { property: 'og:title', content: 'Rolldown | Rust bundler for JavaScript' }],
+    ['meta', { property: 'og:site_name', content: 'Rolldown' }],
+    ['meta', { property: 'og:url', content: 'https://rolldown.rs/' }],
+  ],
+
   themeConfig: {
+    logo: { src: '/lightning-down.svg', width: 24, height: 24 },
+
     // https://vitepress.dev/reference/default-theme-config
     nav: [
       { text: 'Home', link: '/' },
-      { text: 'Guide', link: '/guide/getting-started.md' },
-      { text: 'Dev Guide', link: '/dev-guide/getting-started.md' },
+      { text: 'About', link: '/about.md' },
+      { text: 'Contribute', link: '/contrib-guide/' },
     ],
 
     sidebar: {
-      '/guide/': {
-        base: '/guide/',
-        items: [{ text: 'Getting Started', link: '/getting-started.md' }],
-      },
-      '/dev-guide/': {
-        base: '/dev-guide/',
-        items: [
-          { text: 'Getting Started', link: '/getting-started.md' },
-          { text: 'Setup', link: '/setup.md' },
-          { text: 'Testing', link: '/testing.md' },
-          { text: 'Release', link: '/release.md' },
-        ],
-      },
+      '/contrib-guide/': [
+        { text: 'Overview', link: '/contrib-guide/' },
+        { text: 'Setup', link: '/contrib-guide/setup.md' },
+        { text: 'Build', link: '/contrib-guide/build.md' },
+        { text: 'Test', link: '/contrib-guide/test.md' },
+        { text: 'Benchmark', link: '/contrib-guide/benchmark.md' },
+        { text: 'Release', link: '/contrib-guide/release.md' },
+      ],
     },
 
     socialLinks: [
-      { icon: 'github', link: 'https://github.com/vuejs/vitepress' },
+      { icon: 'x', link: 'https://twitter.com/rolldown_rs' },
+      { icon: 'discord', link: 'https://discord.gg/vsZxvsfgC5' },
+      { icon: 'github', link: 'https://github.com/rolldown-rs/rolldown' },
     ],
+
+    footer: {
+      message: 'Released under the MIT License.',
+      copyright: 'Copyright © 2023-present Rolldown Team & Contributors',
+    },
   },
 })

web/docs/.vitepress/theme/custom.css

@@ -0,0 +1,5 @@
+:root {
+  --vp-c-brand-1: #ff7e17;
+  --vp-c-brand-2: #ff8700;
+  --vp-c-brand-3: #e37800;
+}

web/docs/.vitepress/theme/index.js

@@ -0,0 +1,4 @@
+import DefaultTheme from 'vitepress/theme'
+import './custom.css'
+
+export default DefaultTheme

web/docs/about.md

@@ -0,0 +1,71 @@
+# About Rolldown
+
+:::warning 🚧 Work in Progress
+Rolldown is currently in active development and not usable for production yet.
+
+Last updated: **March 8th, 2024**
+:::
+
+## The future bundler for Vite
+
+It will provide Vite with:
+- Significantly faster production builds
+- Stronger dev / prod consistency
+- More robust SSR dependency handling
+- More control over chunk splitting
+
+Our goal is for Vite users (directly or indirectly through a framework) to be able to transition to a Vite version that uses Rolldown internally with minimal friction.
+
+At the same time, Rolldown will be usable as a standalone bundler
+
+## Rollup Compatibility & Difference
+
+- API & Plugin interface compatibility
+- Internal logic difference
+- Scope difference
+
+## Roadmap
+
+### Stage 1: Basic Bundling (done)
+- Mixed CommonJS / ESM support
+
+### Stage 2: Advanced Bundling (we are here)
+- Treeshaking (done)
+- Chunk hashing (wip)
+- Source map (wip)
+- Plugin compatibility (wip)
+- Advanced Chunk splitting (planned)
+- Module federation (planned)
+
+### Stage 3: Built-in Transforms (work going on in parallel in oxc)
+- TypeScript & JSX transforms
+- Minification
+- Syntax lowering
+
+### Stage 4: Integration w/ Vite
+- Plugin container w/ rustified Vite internal plugins
+- Full bundle mode w/ HMR
+
+### Nice to Haves
+
+- Opinionated, zero config TypeScript library bundling
+- DTS generation + bundling (isolatedDeclarations: true)
+
+### Out of Scope
+
+- CSS processing. Use Lightning CSS.
+- Framework specific support (done via plugins)
+
+## Acknowledgements
+
+The Rolldown project is standing upon the shoulders of these giants:
+
+- [rollup](https://github.com/rollup/rollup), created by [Rich-Harris](https://github.com/Rich-Harris) and maintained by [lukastaegert](https://github.com/lukastaegert).
+- [esbuild](https://github.com/evanw/esbuild), created by [evanw](https://github.com/evanw).
+- [parcel_sourcemap](https://github.com/parcel-bundler/source-map).
+
+## Join us!
+
+- [GitHub](https://github.com/rolldown-rs/rolldown)
+- [Contribution Guide](/contrib-guide/)
+- [Discord chat](https://discord.gg/vsZxvsfgC5)

web/docs/contrib-guide/benchmark.md

@@ -0,0 +1,33 @@
+# Benchmarking
+
+## Setup
+
+Before running the benchmarks, setup the necessary fixtures with:
+
+```shell
+# in project root
+just setup-bench
+```
+
+## Benchmarking in Rust
+
+```shell
+# in project root
+just bench
+```
+
+## Benchmarking in Node.js
+
+Make sure to build the Node.js bindings in release mode:
+
+```shell
+# in project root
+yarn build --release
+```
+
+Then, in `packages/bench`:
+
+```shell
+# in packages/bench
+yarn bench
+```

web/docs/contrib-guide/build.md

@@ -0,0 +1,10 @@
+# Building Bindings
+
+For the NAPI-RS based Node packages to work, and for their tests and benchmarks to run, they must be built first. This is done by running `yarn build` in the root directory. This will spin up a process that builds the Node/WASM binding crates (with Cargo), and then builds the rolldown npm package. The `yarn build` script is also smart enough to only re-build if it detects changes since the last time it was ran.
+
+`yarn build` accepts two flags:
+
+- `--no-wasm`
+- `--release` (**important if running benchmarks**)
+
+In addition, the `yarn watch` script can be used to watch the file system for changes, and re-build the bindings and npm package when changes are detected (using the same process as `yarn build`). This is useful for development when you're constantly making changes and re-running tests.

web/docs/contrib-guide/index.md

@@ -0,0 +1,31 @@
+# Contribution Guide
+
+Contributions are always welcome, no matter how large or small! Here we summarize some general guidelines on how you can get involved in the Rolldown project.
+
+## Open development
+
+All development happens directly on [GitHub](https://github.com/rolldown-rs/rolldown). Both core team members and external contributors (via forks) send pull requests which go through the same review process.
+
+Outside of GitHub, we also use a [Discord server](https://discord.gg/vsZxvsfgC5) for real-time discussions.
+
+## Reporting a bug
+
+Please report bugs to GitHub only after you have previously searched for the issue and found no results. Be sure to be as descriptive as possible and to include all applicable labels.
+
+The best way to get your bug fixed is to provide a reduced test case. Please provide a public repository with a runnable example, or a usable code snippet. In the future, we will also provide a REPL that runs in the browser for easier reproductions.
+
+## Requesting new functionality
+
+Before requesting new functionality, view [open issues](https://github.com/rolldown/rolldown/issues) as your request may already exist. If it does not exist, submit an issue with the title prefixed with `[request]`. Be sure to be as descriptive as possible and to include all applicable labels.
+
+## Submitting a pull request
+
+We accept pull requests for all bugs, fixes, improvements, and new features. Before submitting a pull request, be sure your build passes locally using the development workflow above.
+
+For setting up the project's development environment, see [Project Setup](./setup.md).
+
+### Branch organization
+
+Submit all pull requests directly to the `main` branch. We only use separate branches for upcoming releases / breaking changes, otherwise, everything points to main.
+
+Code that lands in main must be compatible with the latest stable release. It may contain additional features, but no breaking changes. We should be able to release a new minor version from the tip of main at any time.

web/docs/contrib-guide/release.md

@@ -0,0 +1,11 @@
+# Release Workflow
+
+:::tip Maintainers only
+This section is for maintainers with push and release privileges only.
+:::
+
+1. Run `yarn verison` locally, which will create new version for packages and generate the changelog. Push the changes to a release branch.
+
+2. Run the [release workflow](https://github.com/rolldown-rs/rolldown/actions/workflows/release.yml) on GitHub via the web interface. Choose your branch under the "Run workflow" dropdown. The action will build, test, and publish the relevant packages.
+
+   The source of the release workflow can be found [here](https://github.com/rolldown-rs/rolldown/blob/main/.github/workflows/release.yml).

web/docs/contrib-guide/setup.md

@@ -0,0 +1,65 @@
+# Project Setup
+
+## Prerequisites
+
+- Rust >= 1.75
+- Node.js >= v18
+- Yarn >= 4
+- Git
+
+## Setup
+
+On your first checkout of the repository, you'll need to install required tools and dependencies.
+
+:::tip
+If you are using [proto](https://moonrepo.dev/proto), you can run `proto use` in the repository root to install Rust, Node.js, and Yarn. For other tools, or if not using proto, continue reading.
+:::
+
+### Rust
+
+Rolldown is built on Rust and requires `rustup` and `cargo` to exist in your environment. You can
+[install Rust from the official website](https://www.rust-lang.org/tools/install).
+
+We also require `just` and `cargo-binstall`. You can install these with:
+
+```shell
+cargo install cargo-binstall
+cargo binstall just
+```
+
+Once installed, run the following to install secondary tools.
+
+```shell
+just init-rust
+```
+
+### Node.js
+
+Rolldown is an npm package built with [NAPI-RS](https://napi.rs/) and is published to the npm registry, and as such requires Node.js and Yarn (for dependency management).
+
+We recommend installing Node.js with a version manager, like [nvm](https://github.com/nvm-sh/nvm) or [fnm](https://github.com/Schniz/fnm). Make sure to install and use Node.js verison 18+, which is the minimum requirement for this project. You can skip this step if you are already using a Node.js version manager of your choice and on a Node.js version that meets the requirement.
+
+We recommend enabling Yarn via [corepack](https://nodejs.org/api/corepack.html), so the correct version of Yarn can be automatically used when working in this project:
+
+```shell
+corepack enable
+```
+
+Once both Node.js and Yarn are configured, run the following to install dependencies.
+
+```shell
+just init-node
+```
+
+## High Level Workflow
+
+The following commands are available and should be used in your standard development workflow.
+
+- `just init` - Install required tools and dependencies.
+- `just check` - Runs the typechecker.
+- `just lint` - Lints code.
+- `just fmt` - Formats code.
+- `just test` - Runs tests. Also see [Testing](./testing.md).
+- `just ready` - Run everything!
+
+> Every command will run both Rust and Node.js scripts. To only target one, append `-rust` or `-node` to the just command. For example, `just lint-rust` or `just fmt-node`.

web/docs/contrib-guide/test.md

@@ -0,0 +1,53 @@
+# Testing
+
+We have two groups of test suites: one for Rust, and one for Node.js.
+
+## Summary
+
+- `just test-rust` for running all Rust tests.
+- `just test-node` for running all Node.js tests.
+
+## Rust Tests
+
+Rust tests cases are stored in
+
+- `/crates/rolldown/tests/esbuild`
+- `/crates/rolldown/tests/fixures`
+
+### How test cases are defined
+
+A test case is a folder that contains `test.config.json`.
+
+`test.config.json` contains the configuration for the test suite. See https://github.com/rolldown-rs/rolldown/blob/main/crates/rolldown_testing/src/test_config/mod.rs for more information.
+
+- `main.js` is the default entry of the test case, if `input.input` is not specified in `test.config.json`.
+
+Rolldown will bundle the input into `/dist`, and using the same `node` instance to execute every entry file in `/dist` orderly. If `_test.mjs` is found in test case folder, it will be executed after all entry points are executed.
+
+## Node.js Tests
+
+:::tip
+Make sure to [build Node.js bindings](./build.md) before running these tests.
+:::
+
+### Node.js API tests
+
+Tests located in `packages/node/test` are used to test Rolldown's Node.js API (i.e. the API of the `@rolldown/node` package published on NPM).
+
+It is our goal to align Rolldown's Node.js API with that of Rollup's as much as possible, and the tests are used to verify API alignment and track the progress. Currently, there are many Rollup options that are not yet supported. If you implemented support for additional options from rollup, please add corresponding test cases for them.
+
+In `/packages/node`:
+
+- `yarn test` will run rollup tests.
+- `yarn test:update` will run and update the tests status.
+
+### Rollup behavior alignment tests
+
+We also aim for behavior alignment with Rollup by running Rollup's own tests against Rolldown. The tests are located in `packages/rollup-tests`.
+
+Tests cases are stored in `/rollup`, which is a git submodule of `rolldown`. It should have been set up properly after running `just init` when setting up the project, but you should also run `just update` to update the submodule before running the Rollup tests.
+
+In `/packages/rollup-tests`:
+
+- `yarn test` will run rollup tests.
+- `yarn test:update` will run and update the tests status.