Contributing to Chime

Copy Markdown View Source

Thank you for helping. This page says what to open (an issue, a pull request, or a security report), what a pull request needs, and what the maintainers keep for themselves. How to run the tests is in the README, under Development.

Questions, bugs and ideas

  • A bug. Open an issue with the bug report form. The smallest setup that shows it (the notifier, the resolver, the options given to Chime, and the mount if it matters) is the most useful thing you can give.
  • An idea or a change of behaviour. Open an issue with the feature request form, and say the problem before the solution.
  • A security problem. Do not open an issue. See SECURITY.md.

Search the open and closed issues first: the idea may already be planned, or turned down for a reason given there. BACKLOG.md has the known gaps.

When a pull request needs an issue first

Open an issue, and agree on the change there, before a pull request that:

  • adds a feature, an option, a mount, a channel, or a callback of Chime.Notifier, Chime.Resolver or Chime.Channel;
  • changes what a notification, a delivery, the feed, the preferences, the JSON API or the components do, or the public API;
  • changes the tables (a new version of Chime.Migrations), or the JSON of the API or of its stream;
  • adds a dependency;
  • touches many files, or needs a design decision.

A pull request does not need an issue when it is small and its reason is plain from the diff: a typo, a broken link, a wrong sentence in a guide, or a bug fix with a test that fails without it. When in doubt, open the issue: a short discussion costs less than a pull request that is not merged.

A pull request with an issue says so: Fixes #123 or Closes #123.

A pull request

  • One change. A fix, the guide for an unrelated case and a README edit are three pull requests. Each is reviewed, reverted and released on its own.

  • Why, not only what. The description says the problem the change solves, for whom, and what happened before it: an error, a crash, a notification to the wrong person. Say why a number was chosen when the change adds one.

  • Tests. A bug fix has a test that fails on main and passes with the fix. A feature has tests of what it does, and of its errors, on SQLite and PostgreSQL when it touches the database.

  • Docs. A change a user can see updates the guide it belongs to and the unreleased section at the top of CHANGELOG.md.

  • The checks pass. CI runs them; run them first:

    mix format --check-formatted
mix compile --warnings-as-errors
mix credo --strict
mix docs
mix test
mix dialyzer

    mix test runs on SQLite, and on PostgreSQL too when it is reachable; CI has PostgreSQL. mix precommit runs most of the checks at once. CI also runs the tests with the oldest Elixir, Phoenix and LiveView that Chime supports (CHIME_OLDEST=1, see .github/workflows/ci.yml).

The JavaScript of priv/static/chime.js and chime-react.js is built from assets/src; a change to it commits the bundles that npm run build gives, as CI checks:

cd assets
npm ci
npm run typecheck
npm test
npm run build

mix dev runs a small app at http://localhost:4100, with notifications, the bell, the admin at /admin/notifications and its previews, to see a change in a browser.

The pull request template has these as a checklist.

What the maintainers keep

  • Releases. The version in mix.exs, the release headings of the changelog and the tags are changed by the maintainers, at a release.

Style

Match the code around your change: its naming, its comments and the way its guides are written. mix format and mix credo --strict settle the rest.

License

By contributing, you agree that your contribution is released under the MIT License of the project (see LICENSE).