Development Process

This page describes the development process for developing GnuCash code. It talks about how we use Git and in particular how we use branches to manage the GnuCash source code and release process.

Development Process Goals

The goal of this process is to limit the number of potential bugs that enter the stable release branch(es) due to changes made to the sources. We want to make sure that changes made to releases have been audited and vetted BEFORE they are commited to the release branches. At the same time we want to try to keep the main development branch as stable as practical.

In particular, we want to prevent "bad releases". Those are releases where a bugfix inadvertantly breaks other code.

Documentation

Documentation should start before coding ...

New or reworked features should also be documented as it turns out, some bugs are a problem of communication between user and developer. If you do not have the resources to update the documentation yourself, you should at least assign a bugzilla entry to the documentation team with the essential information.

Branches

Branches in Git are cheap, therefore we should use branches to our advantage. There are always two "interesting" branches in use:

• master -- the main development branch
• maint -- the current release branch.

Older release series are labeled with the release number, e.g. 2.4. Those branches are normally closed to new work shortly after a new maint branch is created from master at the beginning of a new release series.

Developers may also have other branches in use for development or bugfixing. This is described later in this document. These will generally not be pushed to the main repository.

Developing New Features

All new development work should target the master branch. This includes new features and enhancements. Small changes can be commited directly to master. Larger features or architectural changes should happen on a feature-branch; once that feature is working it can get merged back into master.

Bug fixes should be built against the maint branch. See Fixing Bugs below for details.

At any particular time, master should be "as stable as possible". We use feature branches to limit the risk that a feature never completes. If development of a feature were done solely in master and that feature never got completed it could leave master in a state where it doesn't compile, or it fails the regression tests.

If you are at all questioning whether to develop directly in master or in a branch, do it in a branch.

As a general rule, development branches should not be pushed back to the main repository. If one needs to publish a development branch, fork the Github repository to your personal account and publish the branch there. This carries a cost, though: Merging a private branch will put all of the changes into a single "merge commit" and that will be all of the history on the main repository. For major changes it is better to rebase a series of changes into master.

Minor Changes

Developers with the requisite privs may push minor changes directly to master or to maint as appropriate without a feature branch.

Major Changes

Use your judgement about whether your major change should be done directly on master/maint or whether you should use a feature branch. We trust you. Just remember, smaller changesets are easier to audit. When possible try to ensure that each commit can compile; that makes it much easier to bisect when tracking down a regression.

Backwards-Incompatible Schema Changes

To make the policy clearer, backwards-incompatible schema changes in an unstable release, e.g. 2.5, require a change to the previous stable release, e.g. 2.4, to provide a read facility for the new schema.

Often it is easier to add a new KVP which will be simply ignored by older versions than to change the schema. But then it would become harder to get the database normalized for the SQL backend.

Fixing Bugs

In general bug fixes should always target the oldest active branch that features the bug. If the bug is present in the current stable version of gnucash, the bug should be fixed on maint (or a sub branch thereof). If the bug exists only in the development version of gnucash, the bug should be fixed on master only.

The exception here would be a bug in the stable branch for which the fix itself is a very complex or large body of code. Since this code has a higher risk of introducing new bugs in itself it should not be applied on the maint branch. Instead such a bug can only be fixed on the master branch (unstable version).

Since we frequently merge the maint branch into master, please do a test merge of maint into master in your local repository to ensure that your patch merges cleanly.

If it doesn't and you don't know what to do about it, say so on the bug report when you attach your patch so that a developer can help you asses the situation and decide how to resolve it.

Bugfix Branches

Many times a bugfix is simple. In that case the bug can be fixed directly on the maint branch and the changeset can be merged forward to the master branch so future major releases carry it as well.

If the bugfix is sufficiently complicated then that bugfix warrants a bugfix branch. The developer can create a branch off the release branch (maint) to work on the bugfix, and once that's been tested that branch can be merged back into the release branch.

Release Version Numbering

Each GnuCash version number consists of 3 numbers separated by a period, in format Fundamental.Major.Bugfix E.g. 2.4.11

Fundamental

A change in the fundamental number indicates the greatest change. There is no agreed convention for what changes need a new fundamental number. The decision to increase the fundamental number is made on a case by case basis.

Some possible considerations for increasing the fundamental number are

• Huge architectural changes

• Major GUI changes

• Changes that affect many users

• API changes in say Scheme or Python bindings that may require script changes

• A file compatibility change that means the GnuCash data file can no longer be used with an older version. Refer http://wiki.gnucash.org/wiki/FAQ#Using_Different_Versions.2C_Up_And_Downgrade

The last fundamental change, from 1 to 2, involved changing most of the code from Scheme to C and upgrading the GUI from Gtk1 to Gtk2. The next planned huge architectural change (the C++ rewrite of the engine including making it SQL query driven instead of all in memory) will merit a first-number change.

Major

Any change (large or small), that is not merely a fix to a bug in a previous major release, will be included in a release with a new Major version number.

There are 2 types of Major releases, Stable and Unstable.

Stable

Stable releases are those with an even Major version number E.g.

1.8.11

2.4.2

2.6.0

Stable releases are intended for use by users with their live data.

Unstable

Unstable releases are those with an odd Major version number E.g.

2.1.0

2.3.2

2.5.1

Unstable releases are the precursors to a stable release, and are intended only for testing, by either developers or interested community members that don't have the time or skills to build GnuCash from source. They are meant to expose the developers' work to a wide audience, so changes can be tested in a range of environments, before being included in a stable release.

Unstable releases come late in a major development cycle. By the time unstable releases are issued, relevant longer term modifications should be nearly done (except for some bug fixing).

Unstable releases are very short-lived, normally only six months or so, with new releases every month and a final pre-stable release two weeks before the stable release. If a significant problem surfaces in that last release, the developers will focus on that problem and do another pre-stable with the stable to follow two weeks later.

Due to the possibility of data corruption, unstable releases should only be used on a copy of live GnuCash data.

Bugfix

Bugfix releases are only to fix significant problems in major releases that cannot wait for the next major release. E.g.

2.5.1		first bugfix to unstable release 2.5
2.6.1		first bugfix to stable release 2.6
2.6.2		second bugfix to stable release 2.6

Bugfix releases should never break file compatibility with other releases in the same major version.

Bugfix releases are sometimes referred to as point or patch releases.

Changes on the Build System

See Build System#Changes on the Build System.

Updating Translations

Translations are "special". Translation updates can be made directly into the po directory of the release branch.