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:
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.
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!
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!
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
, exvX.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:
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 supportelixir
: The latest patch version of highest minor Elixir we want to supportdeps
: The locked-down version of our dependencies in ourmix.lock
matrix
otp
: The latest minor versions of every major erlang version we want to supportelixir
: The latest patch versions of every minor Elixir version we want to supportdeps
: The locked-down version of our dependencies in ourmix.lock
edge
otp
: The latest major version erlangelixir
: The upcoming version of Elixir available on its default branchdeps
: The un-locked version of dependencies in ourmix.exs
Workflows
The automated test workflows we run are:
- Runs all
mix checks
for thepreferred
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.
- Runs all
- Runs the Test Suite, and updates related code quality services about its robustness.
- Runs on every set of commits added to the
latest
andrelease
branches. - Provides insight into test meta-data like code coverage, documentation quality, etc. displayed in the README.md.
- Runs all
mix checks
for every set of versions in ourmatrix
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.
- Runs all
- 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.
- Runs all
mix checks
for theedge
versions of our dependencies. - Runs on UTC midnight.
- Provides continuous feedback on how prepared the codebase is for upstream changes in dependencies.
- Runs all