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 you 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.
The commit message must follow the Conventional Commits specification. The following types are allowed:
fix
: bug fixfeat
: new featuredocs
: change in the documentationspec
: spec changetest
: test-related changeperf
: performance optimizationci
: CI-related change
Examples:
fix: Fix something
feat: Introduce X
feat!: Introduce Y, BC break
docs: Add docs for X
spec: Z disambiguation
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
$ go run main.go run -config ../../Caddyfile.dev
Go to https://localhost
and enjoy!
To test the legacy server:
$ cd cmd/mercure
$ go run main.go
Go to http://localhost:3000
and enjoy!
When you send a PR, just 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.
To debug potential deadlocks:
- Install
go-deadlock
:./tests/use-go-deadlock.sh
- Run the tests in race mode:
go test -race ./... -v
- To stress test the app, run the load test (see
docs/load-testing.md
) - Be sure to remove
go-deadlock
before committing
The spec is written in Markdown, compatible with Mmark. It is then converted in the the "xml2rfc" Version 3 Vocabulary.
To contribute to the protocol itself:
- Make your changes
- Download Mmark
- Download
xml2rfc
using pip:pip install xml2rfc
- Format the Markdown file:
mmark -markdown -w spec/mercure.md
- 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