1
# Contributing
2
3
Contributors are very welcome! **No contribution is too small and all contributions are valued.**
4
5
Some suggestions to get started:
6
7
- You can look at the [good first issue][good-first-issue] label on the issue tracker.
8
- Help with packaging on various distributions needed!
9
- To use print debugging to the [Helix log file][log-file], you must:
10
* Print using `log::info!`, `warn!`, or `error!`. (`log::info!("helix!")`)
11
* Pass the appropriate verbosity level option for the desired log level. (`hx -v <file>` for info, more `v`s for higher verbosity)
12
* Want to display the logs in a separate file instead of using the `:log-open` command in your compiled Helix editor? Start your debug version with `cargo run -- --log foo.log` and in a new terminal use `tail -f foo.log`
13
- Instead of running a release version of Helix, while developing you may want to run in debug mode with `cargo run` which is way faster to compile
14
- Looking for even faster compile times? Give [mold](https://github.com/rui314/mold) a try
15
- If your preferred language is missing, integrating a tree-sitter grammar for
16
it and defining syntax highlight queries for it is straightforward and
17
doesn't require much knowledge of the internals.
18
- If you don't use the Nix development shell and are getting your rust-analyzer binary from rustup, you may need to run `rustup component add rust-analyzer`.
19
This is because `rust-toolchain.toml` selects our MSRV for the development toolchain but doesn't download the matching rust-analyzer automatically.
20
21
We provide an [architecture.md][architecture.md] that should give you
22
a good overview of the internals.
23
24
# Auto generated documentation
25
26
Some parts of [the book][docs] are autogenerated from the code itself,
27
like the list of `:commands` and supported languages. To generate these
28
files, run
29
30
```shell
31
cargo xtask docgen
32
```
33
34
inside the project. We use [xtask][xtask] as an ad-hoc task runner.
35
36
To preview the book itself, install [mdbook][mdbook]. Then, run
37
38
```shell
39
mdbook serve book
40
```
41
42
and visit [http://localhost:3000](http://localhost:3000).
43
44
# Testing
45
46
## Unit tests/Documentation tests
47
48
Run `cargo test --workspace` to run unit tests and documentation tests in all packages.
49
50
## Integration tests
51
52
Integration tests for helix-term can be run with `cargo integration-test`. Code
53
contributors are strongly encouraged to write integration tests for their code.
54
Existing tests can be used as examples. Helpers can be found in
55
[helpers.rs][helpers.rs]. The log level can be set with the `HELIX_LOG_LEVEL`
56
environment variable, e.g. `HELIX_LOG_LEVEL=debug cargo integration-test`.
57
58
Contributors using MacOS might encounter `Too many open files (os error 24)`
59
failures while running integration tests. This can be resolved by increasing
60
the default value (e.g. to `10240` from `256`) by running `ulimit -n 10240`.
61
62
## Minimum Stable Rust Version (MSRV) Policy
63
64
Helix keeps an intentionally low MSRV for the sake of easy building and packaging
65
downstream. We follow [Firefox's MSRV policy]. Once Firefox's MSRV increases we
66
may bump ours as well, but be sure to check that popular distributions like Ubuntu
67
package the new MSRV version. When increasing the MSRV, update these three places:
68
69
* the `workspace.package.rust-version` key in `Cargo.toml` in the repository root
70
* the `env.MSRV` key at the top of `.github/workflows/build.yml`
71
* the `toolchain.channel` key in `rust-toolchain.toml`
72
73
[Firefox's MSRV policy]: https://firefox-source-docs.mozilla.org/writing-rust-code/update-policy.html
74
[good-first-issue]: https://github.com/helix-editor/helix/labels/E-easy
75
[log-file]: https://github.com/helix-editor/helix/wiki/FAQ#access-the-log-file
76
[architecture.md]: ./architecture.md
77
[docs]: https://docs.helix-editor.com/
78
[xtask]: https://github.com/matklad/cargo-xtask
79
[mdbook]: https://rust-lang.github.io/mdBook/guide/installation.html
80
[helpers.rs]: ../helix-term/tests/test/helpers.rs
81
