commit 2648ef6f9cacd20ad532e8f351054354685b2705
parent 717b416fcdff45edb5f2022d1b7ecbd05eca4cb5
Author: Florian Dold <florian@dold.me>
Date: Mon, 18 Aug 2025 14:39:25 +0200
fix formatting, add text about tagging and package versioning
Diffstat:
1 file changed, 73 insertions(+), 48 deletions(-)
diff --git a/taler-developer-manual.rst b/taler-developer-manual.rst
@@ -38,76 +38,76 @@ GNU Taler consists of a large (and growing) number of components
in various Git repositories. The following list gives a first
overview:
- * exchange: core payment processing logic with a REST API, plus various
- helper processes for interaction with banks and cryptographic
- computations. Also includes the logic for the auditor and an
- in-memory "bank" API implementation for testing.
+* exchange: core payment processing logic with a REST API, plus various
+ helper processes for interaction with banks and cryptographic
+ computations. Also includes the logic for the auditor and an
+ in-memory "bank" API implementation for testing.
- * libeufin: implementation of the "bank" API using the EBICS protocol
- used by banks in the EU. Allows an exchange to interact with
- European banks.
+* libeufin: implementation of the "bank" API using the EBICS protocol
+ used by banks in the EU. Allows an exchange to interact with
+ European banks.
- * depolymerization: implementation of the "bank" API on top of
- blockchains, specifically Bitcoin and Ethereum. Allows an exchange
- to interact with crypto-currencies.
+* depolymerization: implementation of the "bank" API on top of
+ blockchains, specifically Bitcoin and Ethereum. Allows an exchange
+ to interact with crypto-currencies.
- * merchant: payment processing backend to be run by merchants,
- offering a REST API.
+* merchant: payment processing backend to be run by merchants,
+ offering a REST API.
- * wallet-core: platform-independent implementation of a wallet to be run by
- normal users. Includes also the WebExtension for various browsers.
- Furthermore, includes various single-page apps used by other
- components (especially as libeufin and merchant). Also includes
- command-line wallet and tools for testing.
+* wallet-core: platform-independent implementation of a wallet to be run by
+ normal users. Includes also the WebExtension for various browsers.
+ Furthermore, includes various single-page apps used by other
+ components (especially as libeufin and merchant). Also includes
+ command-line wallet and tools for testing.
- * taler-android: Android Apps including the Android wallet, the
- Android point-of-sale App and the Android casher app.
+* taler-android: Android Apps including the Android wallet, the
+ Android point-of-sale App and the Android casher app.
- * taler-ios: iOS wallet App.
+* taler-ios: iOS wallet App.
- * sync: backup service, provides a simple REST API to allow users to
- make encrypted backups of their wallet state.
+* sync: backup service, provides a simple REST API to allow users to
+ make encrypted backups of their wallet state.
- * anastasis: key escrow service, provides a simple REST API to allow
- users to distribute encryption keys across multiple providers and
- define authorization policies for key recovery.
+* anastasis: key escrow service, provides a simple REST API to allow
+ users to distribute encryption keys across multiple providers and
+ define authorization policies for key recovery.
- * taler-mdb: integration of Taler with the multi-drop-bus (MDB) API
- used by vending machines. Allows Taler payments to be integrated
- with vending machines.
+* taler-mdb: integration of Taler with the multi-drop-bus (MDB) API
+ used by vending machines. Allows Taler payments to be integrated
+ with vending machines.
- * gnu-taler-payment-for-woocommerce: payment plugin for the
- woocommerce (wordpress) E-commerce solution.
+* gnu-taler-payment-for-woocommerce: payment plugin for the
+ woocommerce (wordpress) E-commerce solution.
- * twister: man-in-the-middle proxy for tests that require fuzzing a
- REST/JSON protocol. Used for some of our testing.
+* twister: man-in-the-middle proxy for tests that require fuzzing a
+ REST/JSON protocol. Used for some of our testing.
- * challenger: implementation of an OAuth 2.0 provider that can be used
- to verify that a user can receive SMS or E-mail at particular addresses.
- Used as part of KYC processes of the exchange.
+* challenger: implementation of an OAuth 2.0 provider that can be used
+ to verify that a user can receive SMS or E-mail at particular addresses.
+ Used as part of KYC processes of the exchange.
- * taler-mailbox: messaging service used to store and forward payment
- messages to Taler wallets.
+* taler-mailbox: messaging service used to store and forward payment
+ messages to Taler wallets.
- * taldir: directory service used to lookup Taler wallet addresses for
- sending invoices or payments to other wallets.
+* taldir: directory service used to lookup Taler wallet addresses for
+ sending invoices or payments to other wallets.
- * taler-merchant-demos: various demonstration services operated at
- 'demo.taler.net', including a simple shop and a donation page.
+* taler-merchant-demos: various demonstration services operated at
+ 'demo.taler.net', including a simple shop and a donation page.
There are other important repositories without code, including:
- * gana: Hosted on git.gnunet.org, this repository defines various
- constants used in the GNU Taler project.
+* gana: Hosted on git.gnunet.org, this repository defines various
+ constants used in the GNU Taler project.
- * docs: documentation, including this very document.
+* docs: documentation, including this very document.
- * marketing: various presentations, papers and other resources for
- outreach.
+* marketing: various presentations, papers and other resources for
+ outreach.
- * large-media: very large data objects, such as videos.
+* large-media: very large data objects, such as videos.
- * www: the taler.net website.
+* www: the taler.net website.
Fundamentals
============
@@ -161,6 +161,31 @@ warning if the version(s) you support and the version(s) offered by the server
are incompatible.
+Tagging and Package Versioning
+------------------------------
+
+Release tags are of the form ``v${major}.${minor}.${patch}``. Release tags *should* be
+annotated git tags.
+
+We usually consider Debian packaging files (in ``debian/``) to be part of a release.
+When only the Debian packaging files need to be changed, there are two options:
+
+* Make a new patch release (``v${major}.${minor}.${patch+1}``)
+* Make a Debian release:
+
+ * Debian version now includes a revision: ``${major}.${minor}.${patch}-${debrevision}``
+ * The tag is Debian-specific: ``debian-${major}.${minor}.${patch}-${debrevision}``
+
+All source repos *should* include a ``contrib/bump`` script that automates bumping the\
+version in all relevant source and packaging files.
+In the future, we might add an option to the script to only release a packaging bump.
+Right now, that process is manual.
+
+We support tagged and published pre-release versions via tags of the form ``v${major}.${minor}.${patch}-dev.${n}``.
+The corresponding Debian version must be ``${major}.${minor}.${patch}~dev${n}``.
+
+Nightly Debian packages should follow the `Debian conventions <https://wiki.debian.org/Versioning>`__ of ``{upcoming_version}~git{date}.{hash}-{revision}``.
+
Testing Tools
-------------
