Skip to content

Latest commit

 

History

History
92 lines (65 loc) · 3.47 KB

CONTRIBUTING.md

File metadata and controls

92 lines (65 loc) · 3.47 KB
Raw

Contributing to async-stripe

  1. Fork it!
  2. Create your feature branch: git checkout -b my-new-feature
  3. Test it: cargo test --features runtime-blocking
  4. Lint it: cargo +nightly clippy --all --all-targets -- -D warnings
  5. Commit your changes: git commit -am 'Add some feature'
  6. Push to the branch: git push origin my-new-feature
  7. Submit a pull request :D

We use rustfmt to keep our codebase consistently formatted. Please ensure that you have correctly formatted your code (most editors will do this automatically when saving) or it may not pass the CI tests.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as in the README, without any additional terms or conditions.

Coding standards

These are requirements we have that we have not yet lifted to the level of automatic enforcement.

Import grouping

In each file the imports should be grouped into at most 4 groups in the following order:

  1. stdlib
  2. non-repository local crates
  3. repository local other crates
  4. this crate

Separate each group with a blank line, and rustfmt will sort into a canonical order. Any file that is not grouped like this can be rearranged whenever the file is touched - we're not precious about having it done in a separate commit, though that is helpful.

Clippy lints

We ask that contributors keep the clippy status clean. Minimally, run cargo clippy before submitting code. Clippy is also run in GitHub Actions.

rustfmt

It is expected that code is uniformly formatted. Before submitting code, make sure to run cargo fmt to make sure it conforms to the standard.

Code Generation

This library is (mostly) authored via code generation by parsing the OpenAPI specification for Stripe. To automatically update the generated code, copy it into the generated folder, and format, use the cargo make target openapi-install. This will also fetch the spec matching the OpenAPI release used for the generated code on master.

cargo make openapi-install

To instead update the generated code using the latest OpenAPI specification release, use

cargo make openapi-install-latest

Testing

To run the tests, you will need to run a stripe-mock server and select a runtime. CI runs tests against all runtimes, but it is encouraged you test your changes locally against a few runtimes first.

docker run --rm -d -it -p 12111-12112:12111-12112 stripe/stripe-mock:latest
cargo test --features runtime-blocking

Communication

It is encouraged to open an issue before you create a PR as a place for pre-implementation discussion. If you're unsure about your contribution or simply want to ask a question about anything just open an issue and we'll chat.

Architecture

This project makes wide use of code generation, with API types generated directly from the stripe openapi spec. This is what the openapi tool does. All generated code ends up in the handily named generated folder which is exposed based on features specified.

In some cases, it is helpful to have additional logic associated with a datatype to, for example, capture a create Charge object. This additional impl goes in the charge_ext.rs file in the resources folder, to provide a clean seperation between generated and hand maintained files. If you notice that logic is missing, please add it to (or create) the appropriate ext file.