summaryrefslogtreecommitdiff
path: root/onboarding.rst
diff options
context:
space:
mode:
authorFlorian Dold <florian.dold@gmail.com>2019-10-13 13:15:21 +0530
committerFlorian Dold <florian.dold@gmail.com>2019-10-13 13:15:21 +0530
commit0822538a1cb6e1b19b04bed09b1cb5ca29b3d032 (patch)
tree3a7ca040870bc95b7d09869acfdc44c7a5c8c535 /onboarding.rst
parentebb171930ca227335a75abb8f634d6ea6c8bb0aa (diff)
downloaddocs-0822538a1cb6e1b19b04bed09b1cb5ca29b3d032.tar.gz
docs-0822538a1cb6e1b19b04bed09b1cb5ca29b3d032.tar.bz2
docs-0822538a1cb6e1b19b04bed09b1cb5ca29b3d032.zip
code style
Diffstat (limited to 'onboarding.rst')
-rw-r--r--onboarding.rst160
1 files changed, 96 insertions, 64 deletions
diff --git a/onboarding.rst b/onboarding.rst
index 77c8d51..7dcae97 100644
--- a/onboarding.rst
+++ b/onboarding.rst
@@ -3,8 +3,33 @@ Developer Onboarding Manual
.. contents:: Table of Contents
-Taler installation
-==================
+Fundamentals
+============
+
+Bug Tracking
+------------
+
+Bug tracking is done with Mantis (https://www.mantisbt.org/). The bug tracker
+is available at `<https://bugs.taler.net>`_. A registration on the Web site is
+needed in order to use the bug tracker, only read access is granted without a
+login.
+
+Code Repositories
+-----------------
+
+Taler code is versioned via Git. For those users without write access, all the
+codebases are found at the following URL:
+
+::
+
+ git://git.taler.net/<repository>
+
+A complete list of all the existing repositories is currently found at
+`<https://git.taler.net/>`_.
+
+
+Taler Deployment on gv.taler.net
+================================
This section describes the GNU Taler deployment on ``gv.taler.net``.
@@ -132,10 +157,12 @@ The following commands do that:
# continue development
$ git checkout master
-.. _Testing-components:
-Building the documentation
-==========================
+Environments and Builders on taler.net
+======================================
+
+Documentation Builder
+---------------------
All the Taler documentation is built by the user ``docbuilder`` that
runs a Buildbot worker. The following commands set the ``docbuilder`` up,
@@ -155,8 +182,9 @@ starting with a empty home directory.
$ buildbot-worker start worker/
-Building the Websites.
-======================
+Website Builder
+---------------
+
Taler Websites, ``www.taler.net`` and ``stage.taler.net``, are built by the
user ``taler-websites`` by the means of a Buildbot worker. The following
@@ -176,8 +204,9 @@ commands set the ``taler-websites`` up, starting with a empty home directory.
$ buildbot-worker start worker/
-Code coverage.
-==============
+Code coverage
+-------------
+
Code coverage tests are run by the ``lcovworker`` user, and are also driven
by Buildbot.
@@ -196,8 +225,9 @@ by Buildbot.
The results are then published at ``https://lcov.taler.net/``.
-Online services checker.
-========================
+Service Checker
+---------------
+
The user ``demo-checker`` runs periodic checks to see if all the
``*.demo.taler.net`` services are up and running. It is driven by
Buildbot, and can be bootstrapped as follows.
@@ -216,8 +246,9 @@ Buildbot, and can be bootstrapped as follows.
$ buildbot-worker start worker/
-Topping the tip reserve up
-==========================
+Tipping reserve top-up
+----------------------
+
Both 'test' and 'demo' setups get their tip reserve topped up
by a Buildbot worker. The following steps get the reserve topper
prepared.
@@ -236,7 +267,7 @@ prepared.
Producing auditor reports
-=========================
+-------------------------
Both 'test' and 'demo' setups get their auditor reports compiled
by a Buildbot worker. The following steps get the reports compiler
@@ -254,7 +285,6 @@ prepared.
$ buildbot-worker start worker/
-.. _Releases:
Releases
========
@@ -337,52 +367,6 @@ Directive file:
Upload the files in **binary mode** to the ftp servers.
-.. _Code:
-
-Code
-====
-
-Taler code is versioned via Git. For those users without write access,
-all the codebases are found at the following URL:
-
-::
-
- git://git.taler.net/<repository>
-
-A complete list of all the existing repositories is currently found at
-``https://git.taler.net/``. Note: ``<repository>`` must NOT have the
-``.git`` extension.
-
-
-.. _Python:
-
-Python
-======
-
-Supported Python Versions
--------------------------
-
-Python code should be written and build against version 3.7 of Python.
-
-Style
------
-
-We use `yapf <https://github.com/google/yapf>`_ to reformat the
-code to conform to our style instructions.
-A reusable yapf style file can be found in ``taler-build-scripts``,
-which is intended to be used as a git submodule.
-
-.. _Bugtracking:
-
-Bugtracking
-===========
-
-Bug tracking is done with Mantis (https://www.mantisbt.org/). All the
-bugs are displayed and managed at ``https://bugs.gnunet.org/``, under
-the "Taler" project. A registration on the Web site is needed in order
-to use the bug tracker, only read access is granted without a login.
-
-.. _Continuous-integration:
Continuous integration
======================
@@ -411,8 +395,13 @@ nightly (once a day) by a Buildbot worker. The coverage results are
then published at ``https://lcov.taler.net/``.
-Coding Style
-============
+Coding Conventions
+==================
+
+GNU Taler is developed primarily in C, Python and TypeScript.
+
+Components written in C
+-----------------------
These are the general coding style rules for Taler.
@@ -420,7 +409,7 @@ These are the general coding style rules for Taler.
by the GNUnet style: https://gnunet.org/style
Naming conventions
-------------------
+^^^^^^^^^^^^^^^^^^
* include files (very similar to GNUnet):
@@ -489,7 +478,50 @@ Naming conventions
* must be called "perf_module-under-test_case-description.c"
+Shell Scripts
+-------------
+
+Shell scripts should be avoided if at all possible. The only permissible uses of shell scripts
+in GNU Taler are:
+
+* Trivial invocation of other commands.
+* Scripts for compatibility (e.g. ``./configure``) that must run on
+ as many systems as possible.
+
+When shell scripts are used, they ``MUST`` begin with the following ``set`` command:
+
+.. code-block:: shell
+
+ # Make the shell fail on undefined variables and
+ # commands with non-zero exit status.
+ set -eu
+
+Python
+------
+
+Supported Python Versions
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Python code should be written and build against version 3.7 of Python.
+
+Style
+^^^^^
+
+We use `yapf <https://github.com/google/yapf>`_ to reformat the
+code to conform to our style instructions.
+A reusable yapf style file can be found in ``taler-build-scripts``,
+which is intended to be used as a git submodule.
+
+Python for Scripting
+^^^^^^^^^^^^^^^^^^^^
+
+When using Python for writing small utilities, the following libraries
+are useful:
+* ``click`` for argument parsing (should be prefered over argparse)
+* ``pathlib`` for path manipulation (part of the standard library)
+* ``subprocess`` for "shelling out" to other programs. Prefer ``subprocess.run``
+ over the older APIs.
Testing library
===============