Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore: update CONTRIBUTING.md #472

Merged
merged 5 commits into from
Oct 3, 2023
Merged

chore: update CONTRIBUTING.md #472

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
337550e
chore: update CONTRIBUTING.md
nissy-dev Oct 2, 2023
5639ec8
Update CONTRIBUTING.md
nissy-dev Oct 3, 2023
0c0e32d
Update CONTRIBUTING.md
nissy-dev Oct 3, 2023
efc9a54
Update CONTRIBUTING.md
nissy-dev Oct 3, 2023
57563f8
docs: update by review
nissy-dev Oct 3, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
109 changes: 52 additions & 57 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -65,7 +65,21 @@ just install-tools

And you're good to go hack with Biome and Rust! 🚀

## Testing
## Crates development

### Analyzers and lint rules

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](https://docs.rs/biome_analyze/latest/biome_analyze/)

### Parser

To know the technical details of how our parser works and how to write test, please check our [internal page](https://docs.rs/biome_parser/latest/biome_parser/)

### Formatter

To know the technical details of how our formatter works and how to write test, please check our [internal page](https://docs.rs/biome_js_formatter/latest/biome_js_formatter/)

### Testing

To run the tests, just run

Expand Down Expand Up @@ -95,7 +109,7 @@ When a snapshot test fails, you can run:
- `cargo insta reject` to reject all the changes;
- `cargo insta review` to review snapshots singularly;

## Checks
### Checks

When you finished your work, and you are ready to **commit and open a PR**,
run the following command:
Expand All @@ -107,7 +121,35 @@ 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.

## Language Server and VS Code Extension Development
#### Generated files

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.

##### `cargo codegen grammar`

This command will update the syntax of the parsers.

The source is generated from the [`ungram` files](https://github.com/biomejs/biome/blob/main/xtask/codegen/js.ungram).

##### `cargo codegen test`

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.


##### `cargo codegen analyzer`

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.

### crate dependencies

[Workspace dependencies](https://doc.rust-lang.org/cargo/reference/workspaces.html#the-dependencies-table) 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](https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#specifying-path-dependencies) to avoid requiring the published version of these crates.

## VS Code extension development

The Biome language server is the binary crate `biome` which can be built using the command:

Expand Down Expand Up @@ -171,7 +213,7 @@ If files specific to your local development environment should be ignored, pleas

You can find more information on this process [here](https://help.github.com/en/github/using-git/ignoring-files#configuring-ignored-files-for-all-repositories-on-your-computer).

## Intellij plugin
## Intellij plugin development

To start development from source, navigate to the `editors/intellij` directory.

Expand Down Expand Up @@ -218,7 +260,7 @@ For testing and developing, you need to build these packages, following the step
The tests are run against the compiled files, which means that you need to run the
`build` command after you implemented features/bug fixes.

## Website
## Website development

The [Biome website](https://biomejs.dev/) is built with [Astro](https://astro.build).
To start a development server you can run the following commands:
Expand All @@ -229,41 +271,6 @@ pnpm install
pnpm start
```

### Generated files
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

move to crate development section


If you work on some parser and you create new nodes or modify existing ones, will need to run a command to update some files that are auto-generated.

#### `cargo codegen grammar`

This command will update the syntax of the parsers.

The source is generated from the [`ungram` files](https://github.com/biomejs/biome/blob/main/xtask/codegen/js.ungram).

#### `cargo codegen test`

This command will create new tests for your parser. We currently have a neat infrastructure
where tests for parser are generated com inline comments found inside
the source code. Please read [the proper chapter for more information](#write-tests-for-a-parser)

It's strongly advised to **run this command before committing new changes**.

#### `cargo codegen analyzer`

This command will detect linter rules declared in the `analyzers` and `assists` directories in `biome_analyze`, regenerate the index modules `analyzers.rs` and `assists.rs` to import these files, and update the registry builder function in `registry.rs` to include all these rules.
It will also regenerate the configuration of the rules.

#### `cargo coverage`

This command will check and report parser conformance against different test suites.
We currently target the [Official ECMAScript Conformance Test Suite](https://github.com/tc39/test262) and
the [Typescript Test Suite](https://github.com/microsoft/TypeScript/tree/main/tests)

The test suites are included as git submodules and can be pulled using:

```bash
git submodule update --init --recursive
```

## Commit messages

Internally, the Biome team adheres as closely as possible to the [conventional commit specification](https://www.conventionalcommits.org/en/v1.0.0-beta.2/).
Expand All @@ -288,14 +295,14 @@ docs: fix link to website page
test(lint): add more cases to handle invalid rules
```

### Creating pull requests
## Creating pull requests

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](#Commit-messages) about conventional commit format.

Please use the template provided.

#### Changelog
### Changelog

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](./CHANGELOG.md). Although **not required**, we appreciate the effort.

Expand Down Expand Up @@ -351,7 +358,7 @@ Because the website displays the changelog, you should update the website using
just codegen-website
```

##### Writing a changelog line
#### Writing a changelog line

- 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]()".
Expand All @@ -362,36 +369,24 @@ just codegen-website

If in doubt, take a look to existing changelog lines.

#### Documentation
### Documentation

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.

#### Magic comments
### Magic comments

- `!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;

### Analyzers and lint rules

To know the technical details of how our analyzer works, how to create a rule and how to write tests, please check our [contribution page](https://github.com/biomejs/biome/blob/main/crates/biome_analyze/CONTRIBUTING.md)

### Formatter

To know the technical details of how our formatter works and how to write test, please check our [contribution page](https://github.com/biomejs/biome/blob/main/crates/biome_js_formatter/CONTRIBUTING.md)
Comment on lines -376 to -382
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

move to crates development section


### Versioning

We follow the specs suggested by [the official documentation](https://code.visualstudio.com/api/working-with-extensions/publishing-extension#prerelease-extensions):

Odd minor versions are dedicated to pre-releases, e.g. `*.5.*` .
Even minor versions are dedicated to official releases, e.g. `*.6.*`.

### Playground
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is outdated.


- [run the playground locally](/website/playground/README.md)

## Releasing

When releasing a new version of a Biome, follow these steps:
Expand Down