diff options
Diffstat (limited to 'developers-manual.rst')
| -rw-r--r-- | developers-manual.rst | 134 |
1 files changed, 67 insertions, 67 deletions
diff --git a/developers-manual.rst b/developers-manual.rst index 3b71d9ea..2910c9fb 100644 --- a/developers-manual.rst +++ b/developers-manual.rst @@ -51,7 +51,7 @@ Code Repositories Taler code is versioned with Git. For those users without write access, all the codebases are found at the following URL: -:: +.. code-block:: none git://git.taler.net/<repository> @@ -78,7 +78,7 @@ in the `Git book <https://git-scm.com/book/en/v2/Git-on-the-Server-Generating-Yo If you have been granted write access, you first of all must change the URL of the respective repository to: -:: +.. code-block:: none ssh://git@git.taler.net/<repository> @@ -94,7 +94,7 @@ such that others can verify your commits later. To sign all commits, you should run -:: +.. code-block:: console $ git config --global commit.gpgsign true @@ -102,7 +102,7 @@ You can also sign individual commits only by adding the ``-S`` option to the ``git commit`` command. If you accidentally already made commits but forgot to sign them, you can retroactively add signatures using: -:: +.. code-block:: console $ git rebase -S @@ -121,7 +121,7 @@ the master branch. If you commit and later find out that new commits were pushed, the following command will pull the new commits and rebase yours on top of them. -:: +.. code-block:: console # -S instructs Git to (re)sign your commits $ git pull --rebase -S @@ -218,7 +218,7 @@ Tagging components All Taler components must be tagged with git before they are deployed on the ``demo`` environment, using a tag of the following form: -:: +.. code-block:: none demo-YYYY-MM-DD-SS YYYY = year @@ -232,7 +232,7 @@ Environment Layout Environments have the following layout: -:: +.. code-block:: none $HOME/ deployment (deployment.git checkout) @@ -282,7 +282,7 @@ When deploying to ``demo``, the ``envcfg.py`` should be committed to ``deploymen Bootstrapping an Environment ---------------------------- -.. code-block:: sh +.. code-block:: console $ git clone https://git.taler.net/deployment.git ~/deployment $ cp ~/deployment/envcfg/$ENVCFGFILE ~/envcfg.py @@ -299,7 +299,7 @@ Bootstrapping an Environment Upgrading an Existing Environment --------------------------------- -.. code-block:: sh +.. code-block:: console $ rm -rf ~/sources ~/local $ git -C ~/deployment pull @@ -316,7 +316,7 @@ Switching Demo Colors As the ``demo`` user, to switch to color ``${COLOR}``, run the following script from ``deployment/bin``: -.. code-block:: sh +.. code-block:: console $ taler-deployment switch-demo @@ -359,7 +359,7 @@ All the Taler documentation is built by the user ``docbuilder`` that runs a Buildbot worker. The following commands set the ``docbuilder`` up, starting with a empty home directory. -.. code-block:: sh +.. code-block:: console # Log-in as the 'docbuilder' user. @@ -381,7 +381,7 @@ 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 commands set the ``taler-websites`` up, starting with a empty home directory. -.. code-block:: sh +.. code-block:: console # Log-in as the 'taler-websites' user. @@ -401,7 +401,7 @@ Code coverage Code coverage tests are run by the ``lcovworker`` user, and are also driven by Buildbot. -.. code-block:: sh +.. code-block:: console # Log-in as the 'lcovworker' user. @@ -423,7 +423,7 @@ 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. -.. code-block:: sh +.. code-block:: console # Log-in as the 'demo-checker' user @@ -444,7 +444,7 @@ Both 'test' and 'demo' setups get their tip reserve topped up by a Buildbot worker. The following steps get the reserve topper prepared. -.. code-block:: sh +.. code-block:: console # Log-in as <env>-topper, with <env> being either 'test' or 'demo' @@ -464,7 +464,7 @@ Both 'test' and 'demo' setups get their auditor reports compiled by a Buildbot worker. The following steps get the reports compiler prepared. -.. code-block:: sh +.. code-block:: console # Log-in as <env>-auditor, with <env> being either 'test' or 'demo' @@ -518,10 +518,10 @@ Tagging Tag releases with an **annotated** commit, like -.. code-block:: sh +.. code-block:: console - git tag -a v0.1.0 -m "Official release v0.1.0" - git push origin v0.1.0 + $ git tag -a v0.1.0 -m "Official release v0.1.0" + $ git push origin v0.1.0 Database for tests @@ -539,32 +539,32 @@ the change of the version. Update the Texinfo documentation using the files from docs.git: -.. code-block:: +.. code-block:: console # Get the latest documentation repository - cd $GIT/docs - git pull - make texinfo + $ cd $GIT/docs + $ git pull + $ make texinfo # The *.texi files are now in _build/texinfo # # This checks out the prebuilt branch in the prebuilt directory - git worktree add prebuilt prebuilt - cd prebuilt + $ git worktree add prebuilt prebuilt + $ cd prebuilt # Copy the pre-built documentation into the prebuilt directory - cp -r ../_build/texinfo . + $ cp -r ../_build/texinfo . # Push and commit to branch - git commit -a -S -m "updating texinfo" - git status + $ git commit -a -S -m "updating texinfo" + $ git status # Verify that all files that should be tracked are tracked, # new files will have to be added to the Makefile.am in # exchange.git as well! - git push + $ git push # Remember $REVISION of commit # # Go to exchange - cd $GIT/exchange/doc/prebuilt + $ cd $GIT/exchange/doc/prebuilt # Update submodule to point to latest commit - git checkout $REVISION + $ git checkout $REVISION Finally, the Automake ``Makefile.am`` files may have to be adjusted to include new ``*.texi`` files or images. @@ -573,14 +573,14 @@ include new ``*.texi`` files or images. For the exchange test cases to pass, ``make install`` must be run first. Without it, test cases will fail because plugins can't be located. -.. code-block:: sh +.. code-block:: console - ./bootstrap - ./configure # add required options for your system - make dist - tar -xf taler-$COMPONENT-$VERSION.tar.gz - cd taler-$COMPONENT-$VERSION - make install check + $ ./bootstrap + $ ./configure # add required options for your system + $ make dist + $ tar -xf taler-$COMPONENT-$VERSION.tar.gz + $ cd taler-$COMPONENT-$VERSION + $ make install check Wallet WebExtension ------------------- @@ -589,10 +589,10 @@ The version of the wallet is in *manifest.json*. The ``version_name`` should be adjusted, and *version* should be increased independently on every upload to the WebStore. -.. code-block:: sh +.. code-block:: console - ./configure - make dist + $ ./configure + $ make dist Upload to GNU mirrors --------------------- @@ -601,7 +601,7 @@ See https://www.gnu.org/prep/maintain/maintain.html#Automated-FTP-Uploads Directive file: -:: +.. code-block:: none version: 1.2 directory: taler @@ -644,13 +644,13 @@ About Privilege Levels This is the breakdown of privilege levels in Weblate: - * **Users**/**Viewers** = Can log in, view Translations (*applies to new users*) +* **Users**/**Viewers** = Can log in, view Translations (*applies to new users*) - * **Reviewers** = Can contribute Translations to existing *Components* +* **Reviewers** = Can contribute Translations to existing *Components* - * **Managers** = Can create new *Components* of existing *Projects* +* **Managers** = Can create new *Components* of existing *Projects* - * **Superusers** = Can create new *Projects* +* **Superusers** = Can create new *Projects* Upgrading Privileges -------------------- @@ -675,19 +675,19 @@ What follows is a sort of Wizard. You can find detailed docs at https://docs.we Under *https://weblate.taler.net/create/component/vcs/*: - * **Source code repository** - Generally ``git+ssh://git@git.taler.net/<reponame>```. Check with ``git remote -v``. +* **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 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 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. +* **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 +* **Merge style** - *Rebase*, in line with GNU Taler development procedures - * **Translation license** - *GNU General Public License v3.0 or Later* +* **Translation license** - *GNU General Public License v3.0 or Later* - * **Adding new translation** - Decide how to handle adding new translations +* **Adding new translation** - Decide how to handle adding new translations How to Create a Translation --------------------------- @@ -778,16 +778,16 @@ First, ensure that you have the required dependencies installed: Then you can get the app's source code using git: -.. code-block:: shell +.. code-block:: console # Start by cloning the Android git repository - git clone https://git.taler.net/taler-android.git + $ git clone https://git.taler.net/taler-android.git # Change into the directory of the cloned repository - cd taler-android + $ cd taler-android # Find out which Android SDK version you will need - grep -i compileSdkVersion merchant-terminal/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 @@ -801,22 +801,22 @@ In our example, the version is ``29`` which is available, so download the "SDK Platform" package of "Android 10.0.0 (API 29)" and unpack it: -.. code-block:: shell +.. code-block:: console # Change into the directory that contains your downloaded SDK - cd $HOME + $ cd $HOME # Unpack/extract the Android SDK - unzip android-sdk_eng.10.0.0_r14_linux-x86.zip + $ unzip android-sdk_eng.10.0.0_r14_linux-x86.zip # Tell the build system where to find the SDK - export ANDROID_SDK_ROOT="$HOME/android-sdk_eng.10.0.0_r14_linux-x86" + $ export ANDROID_SDK_ROOT="$HOME/android-sdk_eng.10.0.0_r14_linux-x86" # Change into the directory of the cloned repository - cd taler-android + $ cd taler-android # Build the merchant-terminal app - ./gradlew :merchant-terminal:assembleRelease + $ ./gradlew :merchant-terminal:assembleRelease If you get an error message complaining about build-tools @@ -935,11 +935,11 @@ in GNU Taler are: When shell scripts are used, they ``MUST`` begin with the following ``set`` command: -.. code-block:: shell +.. code-block:: console # Make the shell fail on undefined variables and # commands with non-zero exit status. - set -eu + $ set -eu Kotlin ------ @@ -1017,11 +1017,11 @@ Note: the main interpreter and the most part of CMDs and traits are hosted inside the exchange codebase, but nothing prevents the developer from implementing new CMDs and traits within other codebases. -:: +.. code-block:: c /* Without loss of generality, let's consider the * following logic to exist inside the run() method of CMD1 */ - .. + ... struct TALER_Amount *a; /** |