gnunet/doc/handbook/chapters/contributing.texi

@node GNUnet Contributors Handbook
@chapter GNUnet Contributors Handbook

@menu
* Contributing to GNUnet::
* Licenses of contributions::
* Copyright Assignment::
* Contributing to the Reference Manual::
* Contributing testcases::
@end menu

@node Contributing to GNUnet
@section Contributing to GNUnet

@cindex licenses
@cindex licenses of contributions
@node Licenses of contributions
@section Licenses of contributions

GNUnet is a @uref{https://www.gnu.org/, GNU} package.
All code contributions must thus be put under the
@uref{https://www.gnu.org/licenses/agpl.html, GNU Affero Public License (AGPL)}.
All documentation should be put under FSF approved licenses
(see @uref{https://www.gnu.org/copyleft/fdl.html, fdl}).

By submitting documentation, translations, and other content to GNUnet
you automatically grant the right to publish code under the
GNU Public License and documentation under either or both the
GNU Public License or the GNU Free Documentation License.
When contributing to the GNUnet project, GNU standards and the
@uref{https://www.gnu.org/philosophy/philosophy.html, GNU philosophy}
should be adhered to.

@cindex copyright assignment
@node Copyright Assignment
@section Copyright Assignment
We require a formal copyright assignment for GNUnet contributors
to GNUnet e.V.; nevertheless, we do allow pseudonymous contributions.
By signing the copyright agreement and submitting your code (or
documentation) to us, you agree to share the rights to your code
with GNUnet e.V.; GNUnet e.V. receives non-exclusive ownership
rights, and in particular is allowed to dual-license the code. You
retain non-exclusive rights to your contributions, so you can also
share your contributions freely with other projects.

GNUnet e.V. will publish all accepted contributions under the AGPLv3
or any later version. The association may decide to publish
contributions under additional licenses (dual-licensing).

We do not intentionally remove your name from your contributions;
however, due to extensive editing it is not always trivial to
attribute contributors properly. If you find that you significantly
contributed to a file (or the project as a whole) and are not listed
in the respective authors file or section, please do let us know.

@node Contributing to the Reference Manual
@section Contributing to the Reference Manual

@itemize @bullet

@item When writing documentation, please use
@uref{https://en.wikipedia.org/wiki/Singular_they, gender-neutral wording}
when referring to people, such as singular “they”, “their”, “them”, and so
forth.

@item Keep line length below 74 characters, except for URLs.
URLs break in the PDF output when they contain linebreaks.

@item Do not use tab characters (see chapter 2.1 texinfo manual)

@item Write texts in the third person perspective.

@c FIXME: This is questionable, it feels like bike shed painging to do
@c this for several k lines. It only helps to jump between sentences in
@c editors afaik.
@c @item Use 2 spaces between sentences, so instead of:

@c @example
@c We do this and the other thing. This is done by foo.
@c @end example

@c Write:

@c @example
@c We do this and the other thing.  This is done by foo.
@c @end example

@end itemize

@node Contributing testcases
@section Contributing testcases

In the core of gnunet, we restrict new testcases to a small subset
of languages, in order of preference:
@enumerate
@item C
@item Portable Shell Scripts
@item Python (3.7 or later)
@end enumerate

We welcome efforts to remove our existing python-2.7 scripts to
replace them either with portable shell scripts or,
at your choice, python-3.7+.

If you contribute new python based testcases, we advise you to
not repeat our past misfortunes and write the tests in a standard
test framework like for example pytest.

For writing portable shell scripts, these tools are useful:
@uref{https://github.com/koalaman/shellcheck, Shellcheck},
@uref{https://salsa.debian.org/debian/devscripts/blob/master/scripts/checkbashisms.pl, checkbashisms},
@uref{http://www.etalabs.net/sh_tricks.html},
@uref{https://wiki.ubuntu.com/DashAsBinSh},
and @uref{https://mywiki.wooledge.org/Bashism}

@c You could also run "bin/check_shell_script" (which we still have
@c to write).