diff options
Diffstat (limited to 'developers-manual.rst')
| -rw-r--r-- | developers-manual.rst | 190 |
1 files changed, 154 insertions, 36 deletions
diff --git a/developers-manual.rst b/developers-manual.rst index 7d1f6ab8..2f1fbfd8 100644 --- a/developers-manual.rst +++ b/developers-manual.rst @@ -286,10 +286,6 @@ Bootstrapping an Environment $ taler-deployment-start $ taler-deployment-arm -I # check everything works - Caution: there is currently a known bug in the part that sets up the bank - account password of the exchange might either not exist or be broken. - Thus, that must currently still be done manually! (#6099). - Upgrading an Existing Environment --------------------------------- @@ -319,6 +315,34 @@ run the following script from ``deployment/bin``: Environments and Builders on taler.net ====================================== +Buildbot implementation +----------------------- + +GNU Taler uses a buildbot implementation (front end at https://buildbot.taler.net) to manage continuous integration. Buildbot documentation is at https://docs.buildbot.net/. + +Here are some highlights: + +- The WORKER is the config that that lives on a shell account on a localhost (taler.net), where this host has buildbot-worker installed. The WORKER executes the commands that perform all end-functions of buildbot. + +- The WORKER running buildbot-worker receives these commands by authenticating and communicating with the buildbot server using parameters that were specified when the worker was created in that shell account with the ``buildbot-worker`` command. + +- The buildbot server's master.cfg file contains FACTORY declarations which specify the commands that the WORKER will run on localhost. + +- The FACTORY is tied to the WORKER in master.cfg by a BUILDER. + +- The master.cfg also allows for SCHEDULER that defines how and when the BUILDER is executed. + +- Our master.cfg file is checked into git, and then periodically updated on a particular account on taler.net (ask Christian for access if needed). Do not edit this file directly/locally on taler.net, but check changes into Git. + + +Best Practices: + +- When creating a new WORKER in the ``master.cfg`` file, leave a comment specifying the server and user account that this WORKER is called from. (At this time, taler.net is the only server used by this implementation, but it's still good practice.) + +- Create a worker from a shell account with this command: ``buildbot-worker create-worker <workername> localhost <username> <password>`` + +Then make sure there is a WORKER defined in master.cfg like: ``worker.Worker("<username>", "<password>")`` + Documentation Builder --------------------- @@ -594,28 +618,121 @@ for that. There is also the possibility to trigger builds manually, but this is only reserved to "admin" users. + +Internationalization +==================== + +Internationalization (a.k.a "Translation") is handled with Weblate (https://weblate.org) via our instance at ``https://weblate.taler.net/``. + +At this time, this system is still very new for Taler.net and this documentation may be incorrect and is certainly incomplete. + +Who can Register +---------------- + +At this time, anyone can register an account at ``https://weblate.taler.net/`` to create translations. Registered users default to the **Users** and **Viewers** privilege level. + +About Privilege Levels +---------------------- + +This is the breakdown of privilege levels in Weblate: + + * **Users**/**Viewers** = Can log in, view Translations (*applies to new users*) + + * **Reviewers** = Can contribute Translations to existing *Components* + + * **Managers** = Can create new *Components* of existing *Projects* + + * **Superusers** = Can create new *Projects* + +Upgrading Privileges +-------------------- + +To upgrade from **Users**/**Viewers**, a superuser must manually augment your privileges. At this time, superusers are Christian, Florian, and Buck. + +How to Create a Project +----------------------- + +The *GNU Taler* project is probably the correct project for most Components and Translations falling under this guide. Please contact a superuser if you need another Project created. + +How to Create a Component +------------------------- + +Reference: https://docs.weblate.org/en/weblate-4.0.3/admin/projects.html#component-configuration + +In Weblate, a *Component* is a subset of a *Project* and each Component contains N translations. A Component is generally associated with a Git repo. + +To create a Component, log into https://weblate.taler.net/ with your *Manager* or higher credentials and choose **+ Add** from the upper-right corner. + +What follows is a sort of Wizard. You can find detailed docs at https://docs.weblate.org/. Here are some important notes about connecting your Component to the Taler Git repository: + +Under *https://weblate.taler.net/create/component/vcs/*: + + * **Source code repository** - Generally ``git+ssh://git@git.taler.net/<reponame>```. Check with ``git remote -v``. + + * **Repository branch** - Choose the correct branch to draw from and commit to. + + * **Repository push URL** - This is generally ``git+ssh://git@git.taler.net/<reponame>``` Check with ``git remote -v``. + + * **Repository browser** - This is the www URL of the Git repo's file browser. Example ``https://git.taler.net/<repositoryname>.git/tree/{{filename}}?h={{branch}}#n{{line}}`` where ``<repositoryname>`` gets replaced but ``{{filename}}`` and other items in braces are actual variables in the string. + + * **Merge style** - *Rebase*, in line with GNU Taler development procedures + + * **Translation license** - *GNU General Public License v3.0 or Later* + + * **Adding new translation** - Decide how to handle adding new translations + +How to Create a Translation +--------------------------- + +1 - Log into ``https://weblate.taler.net`` + +2 - Navigate to *Projects* > *Browse all projects* + +3 - Choose the *Project* you wish to contribute to. + +4 - Choose the *Component* you wish to contribute to. + +5 - Find the language you want to translate into. Click "Translate" on that line. + +6 - Find a phrase and translate it. + +You may also wish to refer to ``https://docs.weblate.org/``. + +Translation Standards and Practices +----------------------------------- + +By default, our Weblate instance is set to accept translations in English, French, German, Italian, Russian, Spanish, and Portuguese. If you want to contribute a translation in a different language, navigate to the *Component* you want to translate for, and click "Start new translation" to begin. If you require a privilege upgrade, please contact a superuser with your request. + +When asked, set the license to GPLv3 or later. + +Set commit/push to manual only. + +GPG Signing of Translations +--------------------------- + +weblate.taler.net signs GPG commits with the GPG key CD33CE35801462FA5EB0B695F2664BF474BFE502, and the corresponding public key can be found at https://weblate.taler.net/keys/. + +This means that contributions made through weblate will not be signed with the individual contributor's key when they are checked into the Git repository, but with the weblate key. + + Android Apps ============ Android App Nightly Builds -------------------------- -There are currently three Android apps: +There are currently three Android apps in +`the official Git repository <https://git.taler.net/taler-android.git>`__: * Wallet - [`Git Repo <https://git.taler.net/wallet-android.git>`__] - [`Git Mirror <https://gitlab.com/gnu-taler/wallet-android>`__] - [`CI <https://git.taler.net/wallet-android.git/tree/.gitlab-ci.yml>`__] + [`CI <https://git.taler.net/taler-android.git/tree/wallet/.gitlab-ci.yml>`__] * Merchant PoS Terminal - [`Git Repo <https://git.taler.net/merchant-terminal-android.git/>`__] - [`Git Mirror <https://gitlab.com/gnu-taler/merchant-terminal-android>`__] - [`CI <https://git.taler.net/merchant-terminal-android.git/tree/.gitlab-ci.yml>`__] + [`CI <https://git.taler.net/taler-android.git/tree/merchant-terminal/.gitlab-ci.yml>`__] * Cashier - [`Git Repo <https://git.taler.net/cashier-terminal-android.git/>`__] - [`Git Mirror <https://gitlab.com/gnu-taler/cashier-terminal-android>`__] - [`CI <https://git.taler.net/cashier-terminal-android.git/tree/.gitlab-ci.yml>`__] + [`CI <https://git.taler.net/taler-android.git/tree/cashier/.gitlab-ci.yml>`__] -Their git repositories are mirrored at Gitlab to utilize their CI +Their git repositories are `mirrored at Gitlab <https://gitlab.com/gnu-taler/taler-android>`__ +to utilize their CI and `F-Droid <https://f-droid.org>`_'s Gitlab integration to `publish automatic nightly builds <https://f-droid.org/docs/Publishing_Nightly_Builds/>`_ for each change on the ``master`` branch. @@ -642,7 +759,8 @@ Building apps from source Note that this guide is different from other guides for building Android apps, because it does not require you to run non-free software. -It uses the Merchant PoS Terminal as an example, but works as well for the other apps. +It uses the Merchant PoS Terminal as an example, but works as well for the other apps +if you replace ``merchant-terminal`` with ``wallet`` or ``cashier``. First, ensure that you have the required dependencies installed: @@ -654,20 +772,20 @@ Then you can get the app's source code using git: .. code-block:: shell - # Start by cloning the git repository - git clone https://git.taler.net/merchant-terminal-android.git + # Start by cloning the Android git repository + git clone https://git.taler.net/taler-android.git - # Change into the directory of the cloned app - cd merchant-terminal-android + # Change into the directory of the cloned repository + cd taler-android # Find out which Android SDK version you will need - grep -i compileSdkVersion app/build.gradle + grep -i compileSdkVersion merchant-terminal/build.gradle The last command will return something like ``compileSdkVersion 29``. So visit the `Android Rebuilds <http://android-rebuilds.beuc.net/>`_ project and look for that version of the Android SDK there. If the SDK version is not yet available as a free rebuild, -you can try to lower the ``compileSdkVersion`` in the app's ``app/build.gradle`` file. +you can try to lower the ``compileSdkVersion`` in the app's ``merchant-terminal/build.gradle`` file. Note that this might break things or require you to also lower other versions such as ``targetSdkVersion``. @@ -686,21 +804,22 @@ and unpack it: # Tell the build system where to find the SDK export ANDROID_SDK_ROOT="$HOME/android-sdk_eng.10.0.0_r14_linux-x86" - # Change into the directory of the cloned app - cd merchant-terminal-android + # Change into the directory of the cloned repository + cd taler-android - # Build the app - ./gradlew assembleRelease + # Build the merchant-terminal app + ./gradlew :merchant-terminal:assembleRelease If you get an error message complaining about build-tools > Failed to install the following Android SDK packages as some licences have not been accepted. build-tools;29.0.3 Android SDK Build-Tools 29.0.3 -you can try changing the ``buildToolsVersion`` in the app's ``app/build.gradle`` file +you can try changing the ``buildToolsVersion`` in the app's ``merchant-terminal/build.gradle`` file to the latest "Android SDK build tools" version supported by the Android Rebuilds project. -After the build finished successfully, you find your APK in ``app/build/outputs/apk/release/``. +After the build finished successfully, +you will find your APK in ``merchant-terminal/build/outputs/apk/release/``. .. _Code-coverage: @@ -724,7 +843,7 @@ Components written in C These are the general coding style rules for Taler. * Baseline rules are to follow GNU guidelines, modified or extended - by the GNUnet style: https://gnunet.org/style + by the GNUnet style: https://docs.gnunet.org/handbook/gnunet.html#Coding-style Naming conventions ^^^^^^^^^^^^^^^^^^ @@ -892,7 +1011,7 @@ from implementing new CMDs and traits within other codebases. :: - /* Withouth loss of generality, let's consider the + /* Without loss of generality, let's consider the * following logic to exist inside the run() method of CMD1 */ .. @@ -959,7 +1078,7 @@ Anonymous E-Cash the customer. Also some people are scared of anonymity (which as a term is also way too absolute, as anonymity is hardly ever perfect). - **Use instead**: "Privacy-preserving", "Privacy-friedly" + **Use instead**: "Privacy-preserving", "Privacy-friendly" Payment Replay The process of proving to the merchant that the customer is entitled @@ -1221,11 +1340,6 @@ use when talking to end users or even system administrators. a list of :term:`contract terms` that has been completed and signed by the merchant backend. - reserve - Funds set aside for future use; either the balance of a customer at the - exchange ready for withdrawal, or the funds kept in the exchange;s bank - account to cover obligations from coins in circulation. - refresh refreshing operation by which a :term:`dirty coin` is converted into one or more @@ -1252,6 +1366,10 @@ use when talking to end users or even system administrators. :term:`coins` from the reserve, thereby draining the reserve. If a reserve is not drained, the exchange eventually :term:`closes` it. + Other definition: Funds set aside for future use; either the balance of a customer at the + exchange ready for withdrawal, or the funds kept in the exchange;s bank + account to cover obligations from coins in circulation. + reveal revealing step in the :term:`refresh` protocol where some of the transfer private |