Contributing View Source

Thanks for considering contributing to Matcha!

Where to Contribute

We cultivate a set of issues that are good ways to contribute to Matcha for the first time.

Looking for other ways to contribute? Consider:

  • Improving the documentation

    Documentation is the most valuable contribution you can make directly to the repository! It is easy to overlook documentation when programming, and difficult to look back on something you understand and see where others may get confused. This makes it hard to keep documentation high-quality, and all assistance in fighting entropy is invaluable!

  • Tackling something that doesn't require extensive knowledge of the codebase

    These are less-involved issues that should be approachable without spending a bunch of time studying the entire project. They generally touch parts of the library that are similar across other Elixir and open-source projects.

  • Addressing regressions in upcoming releases to the language

    Matcha continuously looks ahead to upcoming language releases, running its test suite against them to anticipate compatibility issues. If a storm is brewing on the horizon, the bleeding-edge test suite normally catches it, with more than enough time for someone to jump in and deal with the regression.

  • Submitting a PR

    See a typo or a broken link? Is existing documentation unclear, or does following it lead to behaviour you consider surprising? Jump in and help us correct it!

  • Starting a discussion

    Have an idea for an improvement or an enhancement, but don't see a issue for it yet? Crack open a discussion and flesh it out with the maintainers!

  • Opening a new issue

    Is something else the matter, or do the ideas above not fit what you have in mind? Create an issue and continue the conversation!

Code

Want to contribute code? Here's what you need to know.

Reserved Branches & Tags

  • latest is the integration branch where work comes together.

    This means that you can get the "cutting edge" version of Matcha via:

    Mix.install matcha: [github: "christhekeele/matcha", ref: "latest"]
  • release is the staging branch where code intended for the next release is placed.

    This means that you can get the "release candidate" version of Matcha via:

    Mix.install matcha: [github: "christhekeele/matcha", ref: "release"]
  • stable is the floating pointer to the "highest" semantic version of Matcha released to hex.pm.

    This means that the "latest official" version of Matcha is available identically via:

    Mix.install matcha: [github: "christhekeele/matcha", ref: "stable"]

    and

    Mix.install matcha: ">= 0.0.0"
  • tags starting with v, ex vX.Y.Z-mayberc, represent versions published to hex.pm.

    If versions must be modified or yanked, currently these tags must be deleted or moved manually. This means that these two are equivalent:

    Mix.install matcha: [github: "christhekeele/matcha", ref: "vX.Y.Z-mayberc"]

    and

    Mix.install matcha: "vX.Y.Z-mayberc"

All other branch or tag names are fair game.

Project Structure

Matcha is a pretty standard Elixir library, and should be navigable to anyone familiar with such things. Here is the map, with points of interest where it may deviate from a typical project:

matcha

 CONTRIBUTING.md   # YOU ARE HERE

 README.md         # Project landingpad
 mix.exs           # Project manifest

 VERSION           # Library version
 lib/              # Library source code

 test/             # Test suite
    unit/         # Tests modules as laid out in lib/
    usecases/     # Tests derived from realworld ms usage

 docs/             # Extra material for docgen
    img/          # Images used in docgen
    guides/       # Interactive livebook guides

 CHANGELOG.md      # Describes changes in each release

 LICENSE.md        # License Matcha is available under

Guides

Guides are maintained in the docs/guides folder and built with livebook.

I recommend developing them against an actual local instance of livebook, via LIVEBOOK_TOKEN_ENABLED=false livebook server --root-path docs/guides. Avoid having the .livemd files also open in an editor as you work on a guide, to avoid getting into save-tug-of-war.

Tests

Checks

Matcha has three different checks that may run during various automatic builds. If you want to get ahead of build failures, you can run them all locally before pushing up code with the command mix checks. (This is the default task, so you can simply invoke it via mix.) This is equivalent to running:

  • mix test

    Runs the tests found in test/, checking for failures.

  • mix lint

    Checks for compiler warnings, formatting divergences, and style problems.

  • mix typecheck

    Runs dialyzer, checking for provable type issues.

Suites

Matcha has 5 test suites that run different checks automatically, depending on what's happening, for different versions of erlang/OTP, Elixir, and Matcha's dependencies.

Versions

The sets of versions we run checks against are named:

  • preferred

    • otp: The latest minor version of the highest major version erlang we want to support
    • elixir: The latest patch version of highest minor Elixir we want to support
    • deps: The locked-down version of our dependencies in our mix.lock
  • matrix

    • otp: The latest minor versions of every major erlang version we want to support
    • elixir: The latest patch versions of every minor Elixir version we want to support
    • deps: The locked-down version of our dependencies in our mix.lock
  • edge

    • otp: The latest major version erlang
    • elixir: The upcoming version of Elixir available on its default branch
    • deps: The un-locked version of dependencies in our mix.exs

Workflows

The automated test workflows we run are:

  • Test Suite

    • Runs all mix checks for the preferred versions of our dependencies.
    • Runs on every set of commits pushed up to GitHub, on source or forked repositories.
    • Provides continuous feedback on every potential change to the codebase.
  • Test Status

    • Runs the Test Suite, and updates related code quality services about its robustness.
    • Runs on every set of commits added to the latest and release branches.
    • Provides insight into test meta-data like code coverage, documentation quality, etc. displayed in the README.md.
  • Test Matrix

    • Runs all mix checks for every set of versions in our matrix of dependencies.
    • Runs on every set of commits added to the latest branch.
    • Provides full feedback on if each approved change will work on all supported versions.
  • Test Release

    • Runs the Test Matrix, and performs a dry-run of a planned release.
    • Runs on every set of commits added to pull requests to the release branch.
    • Provides a preview of what a release would look like if published from the release branch on all supported versions.
  • Test Edge

    • Runs all mix checks for the edge versions of our dependencies.
    • Runs on UTC midnight.
    • Provides continuous feedback on how prepared the codebase is for upstream changes in dependencies.