We can use help in a bunch of areas and any help is greatly appreciated!
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
Compile all packages and dependencies:
cargo build
Biome can be used via the biome
bin:
cargo run --bin biome -- --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
And you're good to go hack with Biome and Rust! 🚀
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
To run the tests, just run
just test
If you want to test the tests for a single crate:
just test-crate biome_cli
To run only the doctests, you would need to pass an argument to 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;
When you finished your work, and you are ready to commit and open a PR, run the following command:
just ready
This command will run the same commands of the CI: format, lint, tests and code generation. Eventually everything should be "green" 🟢 and commit all the code that was generated.
If you work on some parser and create new nodes or modify existing ones, you must run a command to update some auto-generated files.
This command will update the syntax of the parsers.
The source is generated from the ungram
files.
This command will create new tests for JS or JSON parser. These tests are generated from inline comments found inside the source code.
On the other hand, we are moving away from this approach and have a straightforward process in other parser implementation like CSS.
This command will detect linter rules declared in the analyzers
, assists
and syntax
directories in the analyzer crates, e.g. biome_js_analyze
, biome_json_analyze
, etc., and regenerate the registry.rs
file and its dependents to include all the rules.
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 Biome language server is the binary crate biome
which can be built using the command:
cargo build --bin biome
If benchmarking the language server, be sure to build with the --release
flag.
The VS Code extension can be installed from the Marketplace and can be used with a development build of the language server by setting the "biome.lspBin"
VS Code setting to the path of the binary:
{
"biome.lspBin": "/path/to/biome/target/debug/biome"
}
Please note that Windows disallows modifying an executable while it's running, meaning you won't be able to recompile the Biome binary once the extension was activated in your editor.
The server is spawned as a background daemon, and continues to run even after the editor is closed.
To stop the running daemon instance use the biome stop
command, with the editor closed as the extension
will try to restart it otherwise.
To build the VS Code extension from source, navigate to the editors/vscode
directory and run:
npm install
npm run build
This will create a biome_lsp.vsix
which you can install into VS Code by running:
npm run install-extension
The "biome.lspBin"
VS Code setting will still need to be set as described above.
When the extension is running, it will connect to a daemon server - or it will bootstrap one.
When you apply changes to the binary, you need to do two things:
- compile the binary
- kill the daemon process, so you can spawn a new server session with the new changes
When the daemon is running, it's possible to inspect its logs in the folder biome-logs
, placed
in the temporary folder of the operative system.
The Biome VS Code extension can be debugged by running the Debug Extension
launch configuration
in VS Code. This will compile the extension, watch for modifications and start a separate VS Code
instance with only the Biome extension installed.
If files specific to your local development environment should be ignored, please add these files to a global git ignore file rather than to a git ignore file within Biome.
You can find more information on this process here.
To start development from source, navigate to the editors/intellij
directory.
Build and run the plugin requires:
- Java development kit 17+
- IntelliJ IDEA Ultimate edition
./gradlew runIde
./gradlew buildPlugin
Before start testing the plugin you will need to start IDE by invoking the ./gradlew runIdeForUiTests &
and wait IDE startup
You can now run the test task:
./gradlew test
The npm module npm/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 wasm-pack globally;
- run the
build
command inside the packagebackend-jsonrpc
; - run the
build
andbuild:wasm-node-dev
commands inside the packagejs-api
(foldernpm/js-api
); - run
pnpm i
inside the packagejs-api
(foldernpm/js-api
), this will 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
command after you implemented features/bug fixes.
The Biome website is built with Astro. To start a development server you can run the following commands:
cd website
pnpm install
pnpm start
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:
feat:
, a new featurefix:
, a bugfixdocs:
, a documentation updatetest:
, a test updatechore:
, project housekeepingperf:
, project performancerefactor:
, refactor of the code without change in functionality
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
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
### VSCode
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
Because the website displays the changelog, you should update the website using the following command:
just gen-web
- 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.
!bench_parser
benchmarks the parser's runtime performance and writes a comment with the results;!bench_formatter
benchmarks the formatter runtime performance and writes a comment with the results;!bench_analyzer
benchmarks the analyzer runtime performance and writes a comment with the results;
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. Then update the website usingBIOME_VERSION=<version> cargo codegen-website
. -
Update
version
in Biome'spackage.json
if applicable. -
Update
version
in Biome's LSP package.json if applicable. Note that the LSP follows a distinct versioning scheme. -
Update
version
in each published crates if applicable. (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. Then executejust codegen-linter
. -
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.
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.