Merge pull request 'Add contributing guidelines' (#138) from dvzrv/contributing into draft

Reviewed-on: https://codeberg.org/openpgp/notes/pulls/138

CONTRIBUTING.md

@@ -0,0 +1,91 @@
+<!--
+SPDX-FileCopyrightText: 2023 The "Notes on OpenPGP" project
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# 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