Skip to content
This repository has been archived by the owner on Jun 17, 2021. It is now read-only.

Latest commit

 

History

History
60 lines (49 loc) · 2.66 KB

CONTRIBUTING.md

File metadata and controls

60 lines (49 loc) · 2.66 KB

Contributing

The following highlight some guidelines for contributing to Crichton and submitting pull requests.

Background

At the heart of Crichton is the ALPS specification. It is important that functionality that impacts Crichton's resource descriptors conforms to and preserves the existing ALPS-related implementations so that profiles can be properly generated and referenced.

Guidelines

Crichton aspires follow ideas set out by Bob Martin in Clean Code. As such, the following are some guidelines to think about as you code:

Every file should be easy to read.

  • Use pronouncable, meaningful names that reveal intentions.
  • Code should read like a top-down narrative starting with required modules to make things easy to find.
  • Use three or less method arguments.
  • Stay DRY and keep methods, classes and modules sizes small.

Only add comments that actually add clarification.

  • If you are explaining bad code, fix the code.
  • Aspire to self-documenting variable and method names.

Only do one thing.

  • Methods should call other methods vs. writing larger methods that violate SRP.
  • Every method should be followed by any methods it calls (as the next level of abstraction).

Specs should be F.I.R.S.T.

  • Fast - run quickly.
  • Independent - not rely on previous tests.
  • Repeatable - work in any environment.
  • Self-validating - examples are written to document what passes.
  • Timely - Follow TDD/BDD principles.

Pull Requests

  • Make your feature addition or bug fix that conforms to the style guide.

  • Add pertinent YARD documentation and check that it is correctly formatted by running $ bundle exec rake doc:yard locally.

  • Add specs for it. This is important so future versions don't break it unintentionally.

  • Send a pull request.

  • For a proposed version bump, update the CHANGELOG.

  • Run specs and confirm coverage for your code additions (Note: some specs exist in the demo service which will be set up in the below instructions) :

    $ bundle exec appraisal install
$ bundle exec appraisal rake demo_service:setup
$ bundle exec appraisal rspec

Demo Service

  • The Crichton demo service is located in spec/integration/crichton-demo-service/

  • Crichton demo service requires SQLite which must be installed locally

  • To set up the demo service run:

    $ cd spec/integration/crichton-demo-service/
$ bundle install
$ bundle exec rake setup