Contributing to Hakushi

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 build the bundle, run the development server and 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 canvas that shows it (the <.canvas>, its :node slots, a few nodes and edges of its graph, and its on_change) 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, and BACKLOG.md: the idea may already be planned, or turned down for a reason given there.

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 attribute, a kind of change or a callback;
  • changes what the canvas, a change, the rules or a room does, or its public API (Hakushi.Graph, Hakushi.Change, the components, the hook);
  • changes the events between the hook and the LiveView;
  • adds a dependency, in mix.exs or in assets/;
  • 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 guides 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 change that was lost. 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. A change to the matcher keeps test/fixtures/match.json true in Elixir and in TypeScript.

  • Docs. A change a user can see updates the guide it belongs to and the [Unreleased] section 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 --exclude build
mix dialyzer

    mix precommit runs most of them at once. CI also runs the tests with the oldest Phoenix and LiveView that Hakushi supports (JUMON_OLDEST=1, after mix deps.update phoenix phoenix_live_view), on Elixir 1.18. A change to assets/ also runs, in assets/:

    npm run typecheck
npm test            # or mix test.js

    and a change the browser sees mix test.e2e, in Chromium, Firefox and WebKit.

The pull request template has these as a checklist.

What the maintainers keep

  • Releases. The version in mix.exs and package.json, the release headings of the changelog and the tags are changed by the maintainers, at a release.
  • The built bundle. The files in priv/static are not in the repository; a pull request does not add them.

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 of the Elixir; npm run typecheck the TypeScript.

License

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