Contributing

Getting started (section in README)

Contributions are welcome!

The easiest way for you to contribute right now is to use fern in your application, and see where it's lacking. The current library should have a solid base, but not many log adapters or niche features.

If you have a use case fern does not cover, filing an issue will be immensely useful to me, to anyone wanting to contribute to the project, and (hopefully) to you once the feature is implemented!

If you‘ve just filed an issue, or you want to approach one of our existing ones, mentoring is available! Tag me with @daboross on an issue, or send me an email at daboross @ daboross.net, and I’ll be available to help.

As a note, all contributions are expected to follow the Rust Code of Conduct.

fern project structure

Fern attempts to be an idiomatic rust library and to maintain a sane structure. All source code is located in src/, and tests are in tests/.

The source is split into four modules:

• lib.rs contains top-level traits, module documentation, and helper functions
• builders.rs contains all the configuration code
• errors.rs contains error handling for finishing configuration
• and log_impl.rs contains the implementation for log::Log which is created to run for the actual logging.

Hopefully these modules are fairly separated, and it‘s clear when you’ll need to work on multiple sections. Adding a new log implementation, for instance, will need to touch builders.rs for configuration, and log_impl.rs for the implementation - both pieces of code will connect via builders::Dispatch::into_dispatch, but besides that, things should be fairly separate.

Pull requests

Pull requests are the way to change code using git. If you aren't familiar with them in general, GitHub has some excellent documentation.

There aren't many hard guidelines in this repository on how specifically to format your request. Main points:

• Please include a descriptive title for your pull request, and elaborate on what's changed in the description.
• Feel free to open a PR before the feature is completely ready, and commit directly to the PR branch.
  • This is also great for review of PRs before merging
  • All commits will be squashed together on merge, so don't worry about force pushing yourself.
• Please include at least a short description in each commit, and more of one in the “main” feature commit. Doesn‘t have to be much, but someone reading the history should easily tell what’s different now from before.
• If you have rustfmt-nightly installed, using it is recommended. I can also format the code after merging the code, but formatting it consistently will make reviewing nicer.

Testing

Building fern is as easy as is expected, cargo build.

As of fern 0.5, testing can also easily be done with cargo test.

To run and test the example programs, use:

cargo run --example cmd-program # test less logging
cargo run --example cmd-program -- --verbose # test more logging
cargo run --example colored --features=colored # test colored log levels

Feel free to add tests and examples demonstrating new features as you see fit. Pull requests which solely add new/interesting example programs are also welcome.

Mentoring

With all that said, contributing to a library, especially if new to rust, can be daunting.

Feel free to email me at daboross @ daboross.net with any questions!