diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..fa8a4ce --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,91 @@ + + +# Contributing + +These are the contribution guidelines for "Notes on OpenPGP". + +Development takes place at https://codeberg.org/openpgp/notes. + +Discussion around this project takes place in [`#notes-on-openpgp:matrix.org`] on [Matrix]. + +## Providing changes + +This project uses [sphinx] and [MyST-parser] to allow building various output formats, such as [HTML] and [EPUB], for the included book projects. + +Contributors can provide changes by pull request towards the project. + +### Building and testing + +The included book projects can be built and tested using a `Makefile`. + +The below examples show how to use it with a book named `book`. + +To cleanly build the [HTML] output: + +```shell +$ make -C book clean build +``` + +To cleanly build the [EPUB] output: + +```shell +$ make -C book clean epub +``` + +To spell check all files using [codespell]: + +```shell +$ make -C book codespell +``` + +To check the external links in all [HTML] files using [lychee]: + +```shell +$ make -C book html-linkcheck +``` + +### Writing text + +The syntax follows what is available in [MyST-parser]. + +--- +**NOTE**: It is advisable to always relate to the [MyST-parser] documentation, as [MyST] itself offers more/ different features! + +--- + +#### Cross-referencing + +There are a few guidelines when it comes to cross-referencing, which work around oddities with [sphinx] and [MyST-parser]: + +* When referencing chapters by file, use `[](/my-chapter)`, instead of relying on [explicit targets] for a top-level heading. +* To reference a figure by its title, use `[](#my-figure)` for a figure with the `:name:` attribute `my-figure` (and e.g. the title `My Figure`). +* To reference a figure by number (e.g. `Fig. 1`), use ```{numref}`my-figure` ``` for a figure with the `:name:` attribute `my-figure`. + +#### Figures + +[Figure] environments must have a `:name:` attribute, prefixed with `fig-`, so that they can be referenced elsewhere. +The `:alt:` attribute should explain what is displayed in the picture, as this is an [accessibility] feature. To keep matters brief, components and symbols that are described in other figures already, can be referenced by name instead of explaining them in detail. + +## License + +All text contributions fall under the terms of the [CC-BY-SA-4.0]. + +Configuration file contributions fall under the terms of the [CC0-1.0]. + +[`#notes-on-openpgp:matrix.org`]: https://matrix.to/#/%23notes-on-openpgp%3Amatrix.org +[Matrix]: https://matrix.org +[sphinx]: https://www.sphinx-doc.org/en/master/ +[MyST-parser]: https://myst-parser.readthedocs.io/en/latest/ +[HTML]: https://en.wikipedia.org/wiki/HTML +[EPUB]: https://en.wikipedia.org/wiki/EPUB +[MyST]: https://mystmd.org/guide/quickstart-myst-markdown +[codespell]: https://github.com/codespell-project/codespell +[lychee]: https://lychee.cli.rs +[explicit targets]: https://myst-parser.readthedocs.io/en/latest/syntax/cross-referencing.html#creating-explicit-targets +[Figure]: https://myst-parser.readthedocs.io/en/latest/syntax/images_and_figures.html#figures-images-with-captions +[accessibility]: https://en.wikipedia.org/wiki/Computer_accessibility +[CC-BY-SA-4.0]: ./LICENSES/CC-BY-SA-4.0.txt +[CC0-1.0]: ./LICENSES/CC0-1.0.txt