Settings View Source Contributing

Thanks for considering contributing to Matcha!

quickstart

Quickstart

Assuming you have the GitHub cli and the asdf version manager installed:

# Acquire a copy of the code
gh repo fork git@github.com:christhekeele/matcha.git --remote
cd matcha

# Install dependencies
asdf install
mix deps.get

# Start work
git checkout -b <some-branch-name>
# ...do changes, commits, pushes, etc
mix checks
# ...address reported test failures, type issues, linting problems

# Submit PR
gh pr create

If you are not using gh or asdf, you should fork Matcha from the source and set up your Erlang and Elixir installations on your machine to match those described in .tool-versions yourself.

what-to-contribute

What 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:

• 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!

• Helping answer questions in the communituy

  Helping other people use Matcha successfully is a great way to give back!

• 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.

• 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

Code

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

project-structure

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
├── CHANGELOG.md      # Describes changes in each release
├── LICENSE.md        # License Matcha is available under
│
├── mix.exs           # Project manifest
│
├── VERSION           # Library version
├── lib/              # Library source code
│
├── test/             # Test suite
│   ├── benchmark/    #   Benchmark suite
│   ├── doctest/      #   Tests of moduledocs as laid out in lib/
│   ├── unit/         #   Tests modules as laid out in lib/
│   └── usecases/     #   Tests derived from realworld ms usage
│
├── docs/             # Extra material for docgen
│   ├── guides/       #   Interactive livebook guides
│   └── img/          #   Images used in docgen
│
├── benchmarks/       # Benchmark reports generated by `mix test.benchmarks`
├── coverage/         # Coverage reports generated by `mix test.coverage`
└── doc/              # Documentation generated by `mix docs`

branches-tags

Branches & Tags

• latest is the default 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"], force: true

• 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"], force: true

• stable is a floating tag pointing 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"], force: true

  and

  Mix.install matcha: ">= 0.0.0", force: true

• tags starting with v, ex vX.Y.Z-mayberc, represent semantic versions published to hex.pm.

  If versions must be modified or yanked, currently these tags should be deleted or moved manually.

  This means that these two are equivalent:

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

  and

  Mix.install matcha: "vX.Y.Z-mayberc", force: true

All other branch or tag names are fair game.

docs

Docs

code-documentation

Code Documentation

Matcha uses ex_doc to generate documentation from source code automatically on every release.

If you're developing documentation, you can preview it locally by running:

mix docs
open doc/index.html

The warnings emitted by ex_doc are useful and worth keeping an eye on!

You can also get and overview of the current documentation coverage status by running:

mix docs.coverage

guides

Guides

Matcha also includes a set of interactive guides powered by LiveBook.

They are maintained in the docs/guides folder. They are best developed against a 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!

checks

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 equivalent to running:

• mix test

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

• mix typecheck

  Runs dialyzer, checking for provable type issues.

• mix lint

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

ci-suites

CI 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 on every set of commits pushed up to GitHub, on source or forked repositories.

  • Runs all mix checks for the preferred versions of our dependencies.

  • Provides continuous feedback on every potential change to the codebase.

• Test Status

  • Runs on every set of commits and every PR into the latest and release branches.

  • Runs the Test Suite, and updates related code quality services about its robustness.

  • Provides insight into test meta-data like code coverage, documentation quality, etc. displayed in the README.md.

• Test Matrix

  • Runs on every set of commits and every PR into the latest and release branches.

  • Runs all mix checks for every set of versions in our matrix of dependencies.

  • Provides full feedback on if each approved change will work on all supported versions.

• Test Release

  • Runs on every set of commits added to pull requests to the release branch.

  • Performs a dry-run of a planned release.

  • Provides a preview of what a release would look like if published from the release branch.

• Test Edge

  • Runs automatically UTC midnight.

  • Runs all mix checks for the edge versions of our dependencies.

  • Provides continuous feedback on how prepared the codebase is for upstream changes in dependencies.