Contributing

September 24, 2026 · View on GitHub

When you open a Pull Request to the project, you agree to license your code under the GNU AFFERO GENERAL PUBLIC LICENSE and to transfer the copyright on the submitted code to Kévin Dunglas.

Be sure to have the right to do that (if you are a professional, ask your company)!

If you include code from another project, please mention it in the Pull Request description and credit the original author.

Commit Messages

The commit message must follow the Conventional Commits specification. The following types are allowed:

  • fix: bugfix
  • feat: new feature
  • docs: change in the documentation
  • spec: spec change
  • test: test-related change
  • perf: performance optimization
  • ci: CI-related change

Examples:

fix: Fix something

feat: Introduce X

feat!: Introduce Y, BC break

docs: Add docs for X

spec: Z disambiguation

Hub

Clone the project and make your changes:

git clone https://github.com/dunglas/mercure
cd mercure

To run the test suite:

go test -v -timeout 30s github.com/dunglas/mercure

To test the Caddy module:

cd caddy/mercure
MERCURE_EXTRA_DIRECTIVES='playground' go run -tags deprecated_transport,nobadger,nomysql,nopgx main.go run --config ../../Caddyfile

Go to https://localhost and enjoy!

When you send a PR, make sure that:

  • You add valid test cases.
  • Tests are green.
  • You make a PR on the related documentation.
  • You make the PR on the same branch you based your changes on. If you see commits that you did not make in your PR, you're doing it wrong.

Debugger UI Dependencies

The debugger UI loads nothing from third-party origins. Its npm dependencies are declared in ui/package.json and bundled into public/vendor/, which is committed because the hub embeds it. Run the scripts from ui/:

  • npm ci && npm run vendor regenerates public/vendor/ from package-lock.json.
  • npm run upgrade bumps every dependency to its latest version published at least a week ago, then regenerates public/vendor/. A weekly workflow runs it and opens a pull request when something changed.
  • npm run check fails when public/vendor/ doesn't match the lockfile or a dependency is outdated. release.sh runs it.

CI fails when public/vendor/ doesn't match the lockfile.

Configuring Visual Studio Code

A configuration for Visual Studio Code is provided in the .vscode/ directory of the repository. It is automatically loaded by Visual Studio Code.

Finding Deadlocks

To debug potential deadlocks:

  1. Install go-deadlock: ./tests/use-go-deadlock.sh
  2. Run the tests in race mode: go test -race ./... -v
  3. To stress-test the app, run the load test (see docs/load-testing.md)
  4. Be sure to remove go-deadlock before committing

Spec

The spec is written in Markdown, compatible with Mmark. It is then converted in the "xml2rfc" Version 3 Vocabulary.

To contribute to the protocol itself:

  • Make your changes
  • Download Mmark
  • Download xml2rfc using pip: pip install xml2rfc
  • Generate the XML file: mmark spec/mercure.md > spec/mercure.xml
  • Validate the generated XML file and generate the text file: xml2rfc --text --v3 spec/mercure.xml
  • Remove non-ASCII characters from the generated mercure.txt file (example: Kévin)
  • If appropriate, be sure to update the reference implementation accordingly