commit f25559a428e3c77bc0ba8430b87bc6c5fe505584
parent eab35d514e2d1307f992d288e8ab817874207e42
Author: Martin Schanzenbach <schanzen@gnunet.org>
Date: Thu, 19 Dec 2024 09:22:48 +0100
more cleanup and reordering
Diffstat:
2 files changed, 155 insertions(+), 158 deletions(-)
diff --git a/developers/contributing.rst b/developers/contributing.rst
@@ -20,6 +20,34 @@ the GNU Free Documentation License. When contributing to the GNUnet
project, GNU standards and the `GNU philosophy <https://www.gnu.org/philosophy/philosophy.html>`__ should be
adhered to.
+Minor contributions
+===================
+
+Smaller contributions should be provided as patches and not in
+developer branches that require git access (see below).
+You may post patches on https://bugs.gnunet.org in a new or existing
+(relevant) issue or on the mailing list gnunet-developers@gnu.org.
+
+Major contributions
+===================
+
+You can find the GNUnet project repositories at https://git.gnunet.org.
+The following applies to all repositories, but access policies are only
+enforced for the main gnunet repository.
+To gain write access to the repository, you will have to sign the
+Copyright Assignment (see below).
+Note that all commits **MUST** be signed with your GPG key.
+The server will verify that any pushed commit is signed. It does not matter
+which key is used (we do not keep a list of GPG public keys).
+
+For any changes that are not minor, you **SHOULD** create an issue at
+https://bugs.gnunet.org and work in a branch that you may
+push to the project's server.
+This will allow us to track the motivation and execution of a change
+and list it in the release notes.
+
+See :ref:`dev-style-workflow` for details on the style and workflow.
+
Copyright Assignment
====================
@@ -46,17 +74,8 @@ authors file or section, please do let us know.
.. _Contributing-to-the-Reference-Manual:
-Contributing to the Reference Manual
-====================================
-
-.. todo:: Move section to contrib.rst?
-
-.. todo:: Update contrib section to reflect move to reStructuredText
-
-- When writing documentation, please use `gender-neutral
- wording <https://en.wikipedia.org/wiki/Singular_they>`__ when
- referring to people, such as singular "they", "their", "them", and so
- forth.
+Reference Manual
+================
- Keep line length below 74 characters, except for URLs. URLs break in
the PDF output when they contain linebreaks.
@@ -66,35 +85,3 @@ Contributing to the Reference Manual
- Write texts in the third person perspective.
.. _Contributing-testcases:
-
-Contributing testcases
-======================
-
-In the core of GNUnet, we restrict new testcases to a small subset of
-languages, in order of preference:
-
-1. C
-
-2. Portable Shell Scripts
-
-3. Python (3.7 or later)
-
-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
-or later.
-
-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:
-
-* `Shellcheck <https://github.com/koalaman/shellcheck>`__, for static
- analysis of shell scripts.
-* http://www.etalabs.net/sh_tricks.html,
-* ``bash``-``dash`` (``/bin/sh`` on Debian) interoperability
- * `checkbashisms <https://salsa.debian.org/debian/devscripts/blob/master/scripts/checkbashisms.pl>`__,
- * https://wiki.ubuntu.com/DashAsBinSh, and
- * https://mywiki.wooledge.org/Bashism
-
-
diff --git a/developers/style.rst b/developers/style.rst
@@ -1,3 +1,4 @@
+.. _dev-style-workflow:
*******************
Style and Workflow
@@ -6,102 +7,6 @@ Style and Workflow
This document contains normative rules for writing GNUnet
code and naming conventions used throughout the project.
-
-Naming conventions
-==================
-
-Header files
-------------
-.. Not sure if "include" and "header" files are synonymous.
-
-
-For header files, the following suffixes should be used:
-
-============= ======================================
-Suffix Usage
-============= ======================================
-``_lib`` Libraries without associated processes
-``_service`` Libraries using service processes
-``_plugin`` Plugin definition
-``_protocol`` structs used in network protocol
-============= ======================================
-
-There exist a few exceptions to these rules within the codebase:
-
-* ``gnunet_config.h`` is automatically generated.
-* ``gnunet_common.h``, which defines fundamental routines.
-* ``platform.h``, a collection of portability functions and macros.
-* ``gettext.h``, the internationalization configuration for gettext in GNUnet.
-
-
-Binaries
---------
-
-For binary files, the following convention should be used:
-
-=============================== =========================================
-Name format Usage
-=============================== =========================================
-``gnunet-service-xxx`` Service processes (with listen sockets)
-``gnunet-daemon-xxx`` Daemon processes (without listen sockets)
-``gnunet-helper-xxx[-yyy]`` SUID helper for module xxx
-``gnunet-yyy`` End-user command line tools
-``libgnunet_plugin_xxx_yyy.so`` Plugin for API xxx
-``libgnunetxxx.so`` Library for API xxx
-=============================== =========================================
-
-Logging
--------
-
-The convention is to define a macro on a per-file basis to manage logging:
-
-.. code-block:: c
-
- #define LOG(kind,...)
- [logging_macro] (kind, "[component_name]", __VA_ARGS__)
-
-The table below indicates the substitutions which should be made
-for ``[component_name]`` and ``[logging_macro]``.
-
-======================== ========================================= ===================
-Software category ``[component_name]`` ``[logging_macro]``
-======================== ========================================= ===================
-Services and daemons Directory name in ``GNUNET_log_setup`` ``GNUNET_log``
-Command line tools Full name in ``GNUNET_log_setup`` ``GNUNET_log``
-Service access libraries ``[directory_name]`` ``GNUNET_log_from``
-Pure libraries Library name (without ``lib`` or ``.so``) ``GNUNET_log_from``
-Plugins ``[directory_name]-[plugin_name]`` ``GNUNET_log_from``
-======================== ========================================= ===================
-
-.. todo:: Clear up terminology within the style guide (_lib, _service mapped to appropriate software categories)
-
-.. todo:: Interpret and write configuration style
-
-Symbols
--------
-
-Exported symbols must be prefixed with ``GNUNET_[module_name]_`` and be
-defined in ``[module_name].c``. There are exceptions to this rule such as
-symbols defined in ``gnunet_common.h``.
-
-Private symbols, including ``struct``\ s and macros, must not be prefixed.
-In addition, they must not be exported in a way that linkers could use them
-or other libraries might see them via headers. This means that they must
-**never** be declared in ``src/include``, and only declared or defined in
-C source files or headers under ``src/[module_name]``.
-
-
-Tests
------
-
-Test cases and performance tests should follow the naming conventions
-``test_[module-under-test]_[test_description].c`` and
-``perf_[module-under-test]_[test_description].c``, respectively.
-
-In either case, if there is only a single test, ``[test_description]``
-may be omitted.
-
-
Coding style
============
@@ -346,6 +251,129 @@ does remain on the same line. Example:
short j);
+Naming conventions
+==================
+
+Header files
+------------
+.. Not sure if "include" and "header" files are synonymous.
+
+
+For header files, the following suffixes should be used:
+
+============= ======================================
+Suffix Usage
+============= ======================================
+``_lib`` Libraries without associated processes
+``_service`` Libraries using service processes
+``_plugin`` Plugin definition
+``_protocol`` structs used in network protocol
+============= ======================================
+
+There exist a few exceptions to these rules within the codebase:
+
+* ``gnunet_config.h`` is automatically generated.
+* ``gnunet_common.h``, which defines fundamental routines.
+* ``platform.h``, a collection of portability functions and macros.
+* ``gettext.h``, the internationalization configuration for gettext in GNUnet.
+
+
+Binaries
+--------
+
+For binary files, the following convention should be used:
+
+=============================== =========================================
+Name format Usage
+=============================== =========================================
+``gnunet-service-xxx`` Service processes (with listen sockets)
+``gnunet-daemon-xxx`` Daemon processes (without listen sockets)
+``gnunet-helper-xxx[-yyy]`` SUID helper for module xxx
+``gnunet-yyy`` End-user command line tools
+``libgnunet_plugin_xxx_yyy.so`` Plugin for API xxx
+``libgnunetxxx.so`` Library for API xxx
+=============================== =========================================
+
+Logging
+-------
+
+The convention is to define a macro on a per-file basis to manage logging:
+
+.. code-block:: c
+
+ #define LOG(kind,...)
+ [logging_macro] (kind, "[component_name]", __VA_ARGS__)
+
+The table below indicates the substitutions which should be made
+for ``[component_name]`` and ``[logging_macro]``.
+
+======================== ========================================= ===================
+Software category ``[component_name]`` ``[logging_macro]``
+======================== ========================================= ===================
+Services and daemons Directory name in ``GNUNET_log_setup`` ``GNUNET_log``
+Command line tools Full name in ``GNUNET_log_setup`` ``GNUNET_log``
+Service access libraries ``[directory_name]`` ``GNUNET_log_from``
+Pure libraries Library name (without ``lib`` or ``.so``) ``GNUNET_log_from``
+Plugins ``[directory_name]-[plugin_name]`` ``GNUNET_log_from``
+======================== ========================================= ===================
+
+.. todo:: Clear up terminology within the style guide (_lib, _service mapped to appropriate software categories)
+
+.. todo:: Interpret and write configuration style
+
+Symbols
+-------
+
+Exported symbols must be prefixed with ``GNUNET_[module_name]_`` and be
+defined in ``[module_name].c``. There are exceptions to this rule such as
+symbols defined in ``gnunet_common.h``.
+
+Private symbols, including ``struct``\ s and macros, must not be prefixed.
+In addition, they must not be exported in a way that linkers could use them
+or other libraries might see them via headers. This means that they must
+**never** be declared in ``src/include``, and only declared or defined in
+C source files or headers under ``src/[module_name]``.
+
+
+Tests
+-----
+
+In the core of GNUnet, we restrict new testcases to a small subset of
+languages, in order of preference:
+
+1. C
+
+2. Portable Shell Scripts
+
+3. Python (3.7 or later)
+
+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
+or later.
+
+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:
+
+* `Shellcheck <https://github.com/koalaman/shellcheck>`__, for static
+ analysis of shell scripts.
+* http://www.etalabs.net/sh_tricks.html,
+* ``bash``-``dash`` (``/bin/sh`` on Debian) interoperability
+ * `checkbashisms <https://salsa.debian.org/debian/devscripts/blob/master/scripts/checkbashisms.pl>`__,
+ * https://wiki.ubuntu.com/DashAsBinSh, and
+ * https://mywiki.wooledge.org/Bashism
+
+Test cases and performance tests should follow the naming conventions
+``test_[module-under-test]_[test_description].c`` and
+``perf_[module-under-test]_[test_description].c``, respectively.
+
+In either case, if there is only a single test, ``[test_description]``
+may be omitted.
+
+
+
Continuous integration
======================
@@ -374,28 +402,10 @@ developers with accounts for the GNUnet project on coverity.com are able
to see the analysis results.
-Minor contributions
-===================
-
-Smaller contributions should be provided as patches and not in
-developer branches that require git access (see below).
-You may post patches on https://bugs.gnunet.org in a new or existing
-(relevant) issue or on the mailing list gnunet-developers@gnu.org.
-
Developer access and commit messages
====================================
-You can find the GNUnet project repositories at https://git.gnunet.org.
-The following applies to all repositories, but access policies are only
-enforced for the main gnunet repository.
-Note that all commits **MUST** be signed with your GPG key.
-The server will verify that any pushed commit is signed. It does not matter
-which key is used (we do not keep a list of GPG public keys).
-
-For any changes that are not minor, you should create an issue at
-https://bugs.gnunet.org and work in a branch that you may
-push to the project's server.
-For this, you can create a *developer branch*.
+Major changes **SHOULD** be developed in a developer branch.
A developer branch is a branch which matches a developer-specific
prefix. As a developer with git access, you should have a git username.
If you do not know it, please ask an admin. A developer branch has the
