diff options
Diffstat (limited to 'onboarding.rst')
-rw-r--r-- | onboarding.rst | 160 |
1 files changed, 96 insertions, 64 deletions
diff --git a/onboarding.rst b/onboarding.rst index 77c8d516..7dcae97c 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 =============== |