Contributing Rules & Style Guide

Rough draft. Borrows from other style guides such as Github and Elm.

Pull Requests Style

Pull requests must compile without warnings and be elm-formatted.

Do not include issue numbers in the PR title
Include screenshots and animated GIFs in your pull request whenever possible.
Run elm-format on your code before submitting, ideally have it run every save.
Include a {-| Comment block detailing the function -} above every new top function.
If it compiles but with warnings, get rid of them first, please.
If it doesn't compile, we don't want it.

Git Commit Messages Style

Use the present tense ("Add feature" not "Added feature")
Use the imperative mood ("Move cursor to..." not "Moves cursor to...")
Limit the first line to 72 characters or less
Reference issues and pull requests liberally after the first line
Consider starting the commit message with an applicable emoji:
- 🎨 :art: when improving the format/structure of the code
- 🐎 :racehorse: when improving performance
- 📝 :memo: when improving documentation
- 🐧 :penguin: when fixing something on Gnu/Linux
- 🍎 :apple: when fixing something on macOS
- 🏁 :checkered_flag: when fixing something on Windows
- 🐛 :bug: when fixing a bug
- 🔥 :fire: when removing code or files
- ✅ :white_check_mark: when adding tests
- 🔒 :lock: when dealing with security
- ⬆️ :arrow_up: when upgrading dependencies
- ⬇️ :arrow_down: when downgrading dependencies
- 👕 :shirt: when removing linter warnings

Naming conventions

Imports

Import everything such that it would provide the shortest qualifiers, unless it completely conflicts with another module.
- For example: import Html.Styled.Attributes exposing (..) and import Html.Styled.Attributes exposing (..)
  - This causes the ambiguity with the checked function, so the compiler will force you to qualify it as
    - Css.checked or
    - Html.Styled.Attributes.checked.
  - This is perfectly fine. In these cases, just pick the correct prefix and add it.
  - Most other functions do not conflict, so it is worth it.
- Counterexample: import Json.Decode exposing (..) and import Json.Encode exposing (..)
  - These modules have lots of functions of the same name.
  - Using most functions, such as string, would cause ambiguity errors
    - The compiler would force us to write either Json.Encode.string or Json.Decode.string
    - That's a lot of long qualifiers
  - Solution: import Json.Decode as Decode exposing (..) and import Json.Encode as Encode exposing (..)
    - Bam. Now we only ever need to type as much as Decode.string or Encode.string