Skip to content

Latest commit

 

History

History
97 lines (70 loc) · 4.65 KB

CONTRIBUTING.md

File metadata and controls

97 lines (70 loc) · 4.65 KB
Raw

This document is a work-in-progress.

Table of Contents

Bug Reports

When creating a bug report, start by checking for similar bugs, even if they are closed. Closed issues may contain the solution to your problem.

If the same issue was reported and closed due to lack of information, add your information to the existing issue and it will get reopened for further review.

If no similar issues exist, create a new one with the following information:

  • hoard version (commit if built from git).
  • Steps to reproduce the issue.
  • A minimal configuration file that causes the issue to be reproduceable.
  • If the issue is not a crash or obvious error, a short description of what the expected behavior is.

This information will make it much easier for me to be able to help resolve your issue.

Feature Requests

When submitting a feature request, first check the issue tracker for similar requests.

  • If one exists and is open, add a thumbs up, heart, or other reaction to the first post to show your support.
  • If one exists and is closed, check the reason for closing:
    • If marked wontfix, the feature request has been rejected. Please do not create a new request. If you feel there is a strong reason to reconsider and the thread is not locked, add your thoughts to the existing issue.
    • If not marked wontfix, the feature may have been implemented already! If that is the case, there will be a pull request linked somewhere in the issue's conversation.

If no similar request exists, you can submit a new one, with the following:

  • The feature being requested.
  • The benefit this feature will bring to users.
  • Why this feature should be implemented in hoard and not externally.

If these are not included in the initial request, they will probably be asked for before the request will be considered.

Code

This section describes guidelines for how to write code that will be accepted.

Style

Any code that is submitted via Pull Request needs to pass clippy checks and be formatted using cargo fmt. There are CI checks in place that will fail if this is not the case.

Logging

Any new code should be logged appropriately:

  • ERROR: Fatal errors must be logged where they are created. If the error is built recursively or in a loop, this only applies to the final recursion/iteration.
  • WARN: Non-fatal errors and potentially unexpected behavior (e.g. an operation being skipped) must be logged the same as fatal ones, but with this log level.
  • INFO: Messages to inform the user of the high-level progress of the application get logged here. "High-level" currently means no more frequent than once per Hoard.
  • DEBUG: More detailed messages to inform the user of some of the lower-level workings of the program. This generally means anything more specific than INFO but less specific than TRACE. A good rule of thumb is that multiple instances of a single DEBUG message should not take up more than one full-screen console window.
  • TRACE: Very detailed messages that announce every non-trivial operation in the program.

These are some general rules used for writing log statements.

  1. Logged messages must start with lowercase letters and remain lowercase unless there is a specific reason to have capital letters.
  2. If a hoard library function may call another hoard library function and/or contains a loop, create a new span before that point with the necesssary context.
  3. A span's context should only contain anything used in the immediate context. Items passed through to other library functions should be part of that more specific context, instead.
  4. Let hoard library functions log themselves being called; create spans before calling for context, if necessary. That is, if there is a function call to do_a_thing(), the log message "Doing a thing" should come from inside do_a_thing().
  5. If there must be an event logged with the creation of a span, log the event first so that the context logged with it remains minimal.

Ignoring Lines for Code Coverage

Ignored lines should be limited to the following:

  • Logging statements
  • "This should never happen" panics/asserts in testing code.
  • Code containing unimplemented!() (i.e. should never be called)
  • Lines containing only opening/closing braces that are marked as missing coverage
  • Manual error propagation
    • That is, something like inspecting a lower error to return a specific higher one, or otherwise returning the original error.

Lines can be manually ignored by adding a comment with grcov: ignore on that line.