We can use help in a bunch of areas and any help is greatly appreciated!
- 🚀 Contributing
If you have any questions, proposals, or feedbacks, open a GitHub discussion. Make sure your comment adds value: don't post a comment just to get attention.
Our Discord server is open for help and more ad-hoc discussion. All activity on the Discord is still moderated and will be strictly enforced under the project's Code of Conduct.
Remember that we are doing this project on our own time. We are humans: we like support, and we expect kindness :)
Our GitHub issues serve as a place for submitting bugs. Make sure that the bugs is not reported yet and is not fixed in the main branch. You can test on the main branch, thanks to the playground.
Alternatively, you can use our official CodeSandbox template.
Building this project requires a stable
Rust toolchain, which can be installed using rustup.
Clone the repository and navigate to the tools
directory:
git clone https://github.com/biomejs/biome
cd biome
You can use cargo to run Biome CLI in development mode:
# This is like running "biome --help"
cargo biome-cli-dev --help
We use Just to run scripts and tasks, to make our life easier.
You can install just
using cargo:
cargo install just
But we highly recommend to install it using an OS package manager, so you won't need to prefix every command with cargo
.
Once installed, run the following command install the required tools:
just install-tools
This command will install:
cargo-binstall
, to install binary extensions forcargo
.cargo-insta
, acargo
extension to manage snapshot testing inside the repository.taplo-cli
, a small tool for formatting TOML files.wasm-pack
andwasm-tools
for managing the WASM build of Biome.
And you're good to go hack with Biome and Rust! 🚀
You can either use cargo
or just
to run tests. For simplicity and running tests real quick, use cargo
.
With cargo
, you can run tests with using the test
command:
# run tests
cargo test
# or use the shortcut
cargo t
If you run cargo t
from the root, it will run all tests of the whole repository. If you're inside a crate folder, cargo
will run tests of that crate:
cd crates/biome_cli
# it will run only the tests of the `biome_cli` crate
cargo t
You can run a single test with cargo by passing the test name after the test
command:
cd crates/biome_js_formatter
cargo t quick_test
This will run the quick_test
test inside he biome_js_formatter
crate. You should see an output similar to this:
running 1 test
test quick_test::quick_test ... ok
test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 224 filtered out; finished in 0.02s
You can also use just
for running tests. With just
, the scripts will use the same test runner we use in the CI.
just test
If you want to test the tests for a single crate:
just test-crate biome_cli
Rust has a concept of doctest. A doc test is a doc comment that runs some code. Usually, it looks something like this:
/// I am a doc test
/// ```
/// assert_eq!(true, true) // this is a doc test, and the assertion must pass
/// ```
fn some_fn() {
}
The code inside the code blocks is run during the testing phase.
To run only the doctest, you can run the command:
just test-doc
In some crates, we use snapshot testing. The majority of snapshot testing is done using insta
. insta
is already installed by the command just install-tools
.
When a snapshot test fails, you can run:
cargo insta accept
to accept all the changes and update all the snapshots;cargo insta reject
to reject all the changes;cargo insta review
to review snapshots singularly.
Sometimes you want to debug something when running tests. Like console.log
, in JavaScript, in Rust you can use the macro dbg!()
to print something during debugging something. Then, pass the option --show-output
to cargo
:
fn some_function() -> &'static str {
let some_variable = "some_variable";
dbg!(&some_variable);
some_variable
}
#[test]
fn test_some_function() {
let result = some_function();
assert_eq!(result, "some_variable")
}
cargo t test_some_function --show-output
Creating a development binary is very useful in case you need to triage a reproduction, and you require more information like logging, trace logs, etc.
Additionally, you can use this binary when you need to debug issues related to LSP clients.
From the root of the repository, run the following command:
cargo build --bin biome
cargo
will create a binary called biome
in the target/debug/
directory.
If you're debugging a CLI reproduction, copy the biome
binary inside the root of the reproduction, and change any script that uses the npm package to use the binary instead:
{
"scripts": {
- "lint": "biome lint",
+ "lint": "./biome lint"
}
}
If you're debugging an LSP reproduction, make sure that the client allows to use custom binary, like VSCode and Zed. Provide an absolute URL to the binary that was emitted.
{
"biome.lspBin": "/Users/john/www/biome/target/debug/biome"
}
Usually, the easiest way to create a production build is to use the --release
flag, however Biome requires an environment variable called BIOME_VERSION
to generate different code at compile time.
When you provide a BIOME_VERSION
that is different from 0.0.0
, the build will turn off all the nursery rules that are recommended. The value of BIOME_VERSION
doesn't matter, as long as it's different from 0.0.0
. This means that you'll have to provide a command similar to this:
BIOME_VERSION=0.0.1 cargo build --bin biome --release
When you finished your work, and you are ready to commit and open a PR, there are few other things you would need to run and check:
just f
(alias forjust format
), formats Rust and TOML files.just l
(alias forjust lint
), run the linter for the whole project.- Code generation. The code generation of the repository is spread in the different parts of the code base. Sometimes is needed and sometime it isn't:
- run
just gen-lint
when you're working on the linter; - run
just gen-bindings
in case you worked around the workspace.
- run
Note
You can run just ready
as well, although it's a command that runs the codegen of the whole repository, which will take some time
If you happen to create a new crate inside the workspace, use the command just new-crate
, e.g.:
just new-crate biome_new_crate
Where biome_new_crate
is going to be the name of the new crate. This script takes care of adding the correct template for the Cargo.toml
file, and it adds the crate
to the knope.toml
file, which we use for changelog generation.
To know the technical details of how our analyzer works, how to create a rule and how to write tests, please check our internal page
To know the technical details of how our parser works and how to write test, please check our internal page
To know the technical details of how our formatter works and how to write test, please check our internal page
Workspace dependencies are used, and many dependencies are defined in Cargo.toml in the root.
Internal crates are loaded with workspace = true
for each crate. About dev-dependencies
, we use path dependencies to avoid requiring the published version of these crates.
The npm module packages/@biomejs/biome
contains Biome's Node.js API that supports different backends:
wasm-nodejs
(WebAssembly)backend-jsonrpc
(Connection to the daemon)
For testing and developing, you need to build these packages, following the steps:
- install pnpm via corepack by running
corepack enable
; - install wasm-pack globally;
- run
pnpm --filter "@biomejs/backend-jsonrpc" build
; - run the
pnpm --filter "@biomejs/js-api" build:wasm-dev
andpnpm --filter "@biomejs/js-api" build
commands; - run
pnpm i --filter "@biomejs/js-api" --frozen-lockfile
to link the WebAssembly bindings and the JSON-RPC bindings
The tests are run against the compiled files, which means that you need to run the
build
script after you implemented features/bug fixes.
For more information on how to help with translation, please see the translation contribution guidelines for our docs.
Internally, the Biome team adheres as closely as possible to the conventional commit specification. The following this convention encourages commit best-practices and facilitates commit-powered features like change log generation.
The following commit prefixes are supported:
build:
, a change that affects the build system or external dependencieschore:
, project housekeepingci:
, a change that affects CIdocs:
, a documentation updatefeat:
, a new featurefix:
, a bugfixperf:
, project performancerefactor:
, refactor of the code without change in functionalityrelease:
, release of a new versionrevert:
, revert a previous changetest:
, a test update
Below are examples of well-formatted commits:
feat(compiler): implement parsing for new type of files
fix: fix nasty unhandled error
docs: fix link to website page
test(lint): add more cases to handle invalid rules
We are using action-semantic-pull-request to lint the titles of pull requests. If the 'Lint Pull Request Titles' workflow fails, please correct the title.
When creating a new pull request, it's preferable to use a conventional commit-formatted title, as this title will be used as the default commit message on the squashed commit after merging. See the dedicated section about conventional commit format.
Please use the template provided.
If the PR you're about to open is a bugfix/feature visible to Biome users, you CAN add a new bullet point to CHANGELOG.md. Although not required, we appreciate the effort.
At the top of the file you will see a Unreleased
section.
The headings divide the sections by "scope"; you should be able to identify the scope that belongs to your change. If the change belongs to multiple scopes, you can copy the same sentence under those scopes.
Here's a sample of the headings:
## Unreleased
### Analyzer
### CLI
### Configuration
### Editors
### Formatter
### JavaScript APIs
### Linter
### Parser
When you edit a blank section:
- If your PR adds a breaking change, create a new heading called
#### BREAKING CHANGES
and add bullet point that explains the breaking changes; provide a migration path if possible. Read how we version Biome to determine if your change is breaking. A breaking change results in a major release. - If your PR adds a new feature, enhances an existing feature, or fixes a bug, create a new heading called
#### New features
,#### Enhancements
, or#### Bug fixes
. Ultimately, add a bullet point that explains the change.
Make sure that the created subsections are ordered in the following order:
#### BREAKING CHANGES
#### New features
#### Enhancements
#### Bug fixes
- Use the present tense, e.g. "Add new feature", "Fix edge case".
- If you fix a bug, please add the link to the issue, e.g. "Fix edge case #4444".
- You can add a mention
@user
for every contributor of the change. - Whenever applicable, add a code block to show your new changes. For example, for a new rule you might want to show an invalid case, for the formatter you might want to show how the new formatting changes, and so on.
If in doubt, take a look to existing changelog lines.
If your PR requires some update on the website (new features, breaking changes, etc.), you should create a new PR once the previous PR is successfully merged. When adding new features, the documentation should be part of a new PR, which will be merged right before the release.
We follow the specs suggested by the official documentation:
Odd minor versions are dedicated to pre-releases, e.g. *.5.*
.
Even minor versions are dedicated to official releases, e.g. *.6.*
.
When releasing a new version of a Biome, follow these steps:
-
Add a changelog entry for every Pull Request that lacks one. You can filter merged PRs that don't update the changelog. Read our guidelines for editing the changelog.
-
Based on the changelog, determine which version number to use. See our versioning guide for more details.
-
Rename
Unreleased
to<version> (iso-date)
in the changelog. -
Update
version
in Biome'spackage.json
if applicable. -
Update to the same
version
in all crates if you publish crates. (Cargo.toml
andcrates/**/Cargo.toml
) -
Linter rules have a
version
metadata directly defined in their implementation. This field is set tonext
for newly created rules. This field must be updated to the new version. -
Once the PR is merged, the CI will trigger the
Release: *
workflows. Once these workflows finish compiling the final artefact, they need to be approved manually. -
Open a new PR in the website repository to update the website with the new version number:
BIOME_VERSION=<version> pnpm run codegen:all
. This will also copy the configuration schema in the right place.
We have several resources explaining about Biome. They will help you understand the project and codebase.
- Rust Dublin October 2023 - Biome - YouTube
- Rome, a Modern Toolchain! by Emanuele Stoppa - GitNation
- How to create a lint rule in Biome
Members are listed in alphabetical order. Members are free to use the full name, GitHub handle, or any other nickname they wish to be addressed. Members are free to disclose their pronouns.
- Carson McManus @dyc3
- Denis Bezrukov @denbezrukov
- Hiroki Ihoriya @unvalley
- Jon Egeland @faultyserver
- Nicolas Hedger @nhedger
- Ze-Zheng Wu @Sec-ant
- Dani Guardiola @DaniGuardiola
- Justinas Delinda @minht11
- Madeline Gurriarán @SuperchupuDev
- Vasu Singh @vasucp1207
- Vo Hoang Long @vohoanglong0107
- Yagiz Nizipli @anonrig
- Yoshiaki Togami @togami2864
- Yusuke Abe @chansuke
- Zheyu Zhang @ah-yu
- zoomdong @fireairforce
- Daiki Nishikawa @nissy-dev (Core contributor)
- Takayuki Maeda @TaKO8Ki (Maintainer)
- Victor Teles @victor-teles (Maintainer)