Skip to content

Latest commit

 

History

History
179 lines (129 loc) · 5.24 KB

CONTRIBUTING.md

File metadata and controls

179 lines (129 loc) · 5.24 KB
Raw

Contributing to b2-client

This is mostly a set of guidelines, not fixed rules. They are also changeable -- if you have questions or think something can be improved please submit an issue/PR or start a discussion.

Table of Contents

Quick Reference

How Can I Contribute?

  • Create tickets for discovered bugs and ideas for improvement, reference material to answering questions other people have.
  • Improve tests -- in particular, we need to be able to test the live API against multiple HTTP clients.
  • Help implement the B2 API.

PR Checklist

Before submitting a PR or patchset, be sure to check that you haven't broken various feature combinations:

  • Can you build documentation?
    • cargo doc --no-deps
  • Can you run tests with no features?
    • cargo test
  • Can you run tests with each HTTP client backend?
    • cargo test --features=with_hyper
    • cargo test --features=with_isahc
    • cargo test --features=with_surf
  • Are there any clippy warnings?

All new tests related to sending and receiving data from the B2 service need to be based on real communication with the service, rather than generated solely from their documentation; creating those tests will potentially result in monetary charges. If you submit tests that have not been based on a real session with B2, please let me know in the PR so that I can do so.

Style Guidelines

Commit and PR Style

The first line of a commit message should summarize the purpose of the commit. It should be a full sentence but end without a period. The subject must be no more than 72 characters, preferably no more than 50.

Write the subject in imperative style (like you're telling someone what to do); use "Add xyz" instead of "Added xyz", "Fix" instead of "Fixed", etc.

Example commit subjects:

Add tests for authorize_account function
Add uniq iterator
Fix clippy warnings

If relevant, later paragraphs should provide context and explain anything that may not be apparent. For example, if you made a design decision that may not be obvious, why did you choose that over an alternative?

Answer the question "why?"; we can see "what" from the code itself. Use "Fix typo in schedule documentation" rather than "Change schedull to schedule".

Text should be wrapped at 72 characters.

If a commit references, is related to, or fixes an issue in the tracker, list it at the end.

A full commit message might look something like this:

Add a widget to the box

The box was looking empty with nothing inside it.

We could also have used a gadget, but widgets are shiny, and I like
shiny things.

This does mean we will no longer be able to fit some things inside the
box:

* contrivances will be too big
* devices might break nearby widgets
* gimmicks would no longer be relevant

Resolves: #4

It's best to keep commits small when possible, doing only one thing.

Code Style

  • Use four spaces for indentation.
  • Use a hard 80 column line width.
  • Write code with understandability and future maintainability in mind.
  • Write tests whenever practical; exercise error conditions and edge cases as well as the happy path.
  • Document all public declarations. Also document non-trivial private declarations.
  • Follow the typical Rust naming conventions.
  • If an import is used in one or very few places in a module, prefer a local import to a global one (import inside the function rather than the top of the file).
  • In general, try to conform to the style of the code in which you're working.

Braces

Place opening braces on the same line as the function declaration/if expression/etc. unless doing so would break the 80 column rule.

Function Definitions

If a function's return value would cross 80 columns, place the -> on the next line at column 1. where clauses should be indented four spaces, and the opening brace should be placed on the next line on column 1.

If the parameter list will extend past 80 characters, place each parameter on its own line, indented once. Place the closing parenthesis on the line past the final paremeter, unindented, and with the -> on the same line.

Examples:

fn my_function(a: u32) -> u32 {
    // ...
}

fn my_function_with_a_long_name(apple: u32, banana: &str, carrot: f32)
-> FoodFromIngredients {
    // ...
}

fn another_function<T>(food: &T) -> u32
    where T: SomeTrait,
{
    // ...
}

fn my_other_function_with_a_long_name<T>(apple: T, banana: &str, carrot: f32)
-> FoodFromIngredients
    where T: SomeTrait,
{
    // ...
}

fn another_function_that_goes_across_the_page<T>(
    apple: T,
    banana: &str,
    carrot: f32
) -> FoodFromIngredients {
    // ...
}