Contribution guide

Thank you for your interest in contributing to chalk! There are many ways to contribute, and we appreciate all of them.

If you'd like to contribute, consider joining the Traits Working Group. We hang out on the rust-lang zulip in the #wg-traits stream.

As a reminder, all contributors are expected to follow our Code of Conduct.

Bug Reports

While bugs are unfortunate, they're a reality in software. We can't fix what we don't know about, so please report liberally. If you're not sure if something is a bug or not, feel free to file a bug anyway.

If you have the chance, before reporting a bug, please search existing issues, as it's possible that someone else has already reported your error. This doesn't always work, and sometimes it's hard to know what to search for, so consider this extra credit. We won't mind if you accidentally file a duplicate report.

Sometimes, a backtrace is helpful, and so including that is nice. To get a backtrace, set the RUST_BACKTRACE environment variable to a value other than 0. The easiest way to do this is to invoke chalk like this:

$ RUST_BACKTRACE=1 chalk ...

Running and Debugging

There is a repl mainly for debugging purposes which can be run by cargo run. Some basic examples are in libstd.chalk:

$ cargo run
?- load libstd.chalk
?- Vec<Box<i32>>: Clone
Unique; substitution [], lifetime constraints []

More logging can be enabled by setting the CHALK_DEBUG environment variable. Set CHALK_DEBUG=3 or CHALK_DEBUG=info to see info!(...) output, and CHALK_DEBUG=4 or CHALK_DEBUG=debug to see debug!(...) output as well. In addition, logs may be filtered in a number of ways. The syntax for filtering logs is:

 target[span{field=value}]=level

(Note: all parts of the filter are optional )

In more detail, the filter may consist of:

  • A target (location of origin)
    • For example setting CHALK_DEBUG='chalk_solve::infer::unify' will filter logs to show only output originating from chalk_solve::infer::unify.
  • A span (name provided to the logging macros, for instance unify_var_ty in debug_span!("unify_var_ty"))
    • For example setting CHALK_DEBUG='[unify_ty_ty]' will show only logs where the span contains unify_ty_ty.
  • A list of fields (variables recorded in the logs), for instance ty in debug!("unify_var_ty", ?ty) with values optionally specified
    • For example setting CHALK_DEBUG='[{ty}]' will show only logs which contain a variable ty
    • Setting CHALK_DEBUG='[{ty=Bar}]' will show only logs which contain a variable ty with the value Bar
  • A maximum log level (one of info, debug, trace) which shows logs at or below the given level

More documentation on the syntax and options can be found here.

Pull Requests

Pull requests are the primary mechanism we use to change Rust. GitHub itself has some great documentation on using the Pull Request feature. We use the "fork and pull" model described here, where contributors push changes to their personal fork and create pull requests to bring those changes into the source repository.

Please make pull requests against the master branch.

Writing Documentation

Documentation improvements are very welcome. Documentation pull requests function in the same way as other pull requests.

You can find documentation style guidelines in RFC 1574.