Difference between revisions of "Development Process"
m (→Changes on the Build System: minor supplements) |
(Replace Subversion with Git, trunk with master, and rework the branching section a bit to reflect the way Git differs from subversion.) |
||
| Line 1: | Line 1: | ||
| − | This page describes the development process for developing [[GnuCash]] code. It talks about how we use [[ | + | 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== | ==Development Process Goals== | ||
| Line 15: | Line 15: | ||
==Branches== | ==Branches== | ||
| − | Branches in [[ | + | 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 |
| − | * '' | + | * ''<release>'' -- the current release branch(es) |
| + | |||
| + | [[Git]] transition note: Until the conversion to Git is completed after the release of Gnucash-2.6, committers will use <tt>git svn dcommit</tt> to push changes to the Subversion repository. One may experience difficulties with using branch ''master'' instead of branch ''trunk'' during that time. At the time of this writing, all active committers are already practiced at this, so this note is merely for completeness. | ||
Developers may also have other branches in use for development or bugfixing. This is described later in this document. | Developers may also have other branches in use for development or bugfixing. This is described later in this document. | ||
| Line 24: | Line 26: | ||
==Developing New Features== | ==Developing New Features== | ||
| − | All development should target the '' | + | All development should target the ''master'' branch. This includes new features, bug fixes, 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''. |
| + | |||
| + | At any particular time, ''master'' should be "as stable as possible". We use feature branches to limit the chance 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 [https://github.com/Gnucash/gnucash 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|major changes]] it is better to rebase a series of changes into ''master''. | |
===Minor Changes=== | ===Minor Changes=== | ||
| − | Minor changes may be | + | Minor changes may be pushed directly to ''master''. |
===Major Changes=== | ===Major Changes=== | ||
| − | Use your judgement about whether your major change should be done directly on '' | + | Use your judgement about whether your major change should be done directly on ''master'' or whether you should use a development branch. We trust you. Just remember, smaller changesets are easier to audit. |
==Backwards-Incompatible Schema Changes== | ==Backwards-Incompatible Schema Changes== | ||
| Line 54: | Line 58: | ||
* it requires unvetted changes be committed to the release branch | * it requires unvetted changes be committed to the release branch | ||
* it fails to work well if we have multiple release branches | * it fails to work well if we have multiple release branches | ||
| − | * as '' | + | * as ''master'' diverges, the merging can become even more challenging. While cherry-picking changesets to pull into a release branch requires typing more commands, merging a large set of changes from the release branch back into ''master'' can become a huge tangled mess if any of the changes don't apply cleanly. |
| − | * when looking at a change in '' | + | * when looking at a change in ''master'' to see why a line of code changed '''git blame''' would only show that the change came from a "merge from stable branch" instead of showing who actually made the change or why. |
| − | It is true that as '' | + | It is true that as ''master'' diverges some bugfixes might require a lot of work to "backport" to the release branch (assuming that the fix even IS a backport). In that case, the developer should use a bugfix branch (based off the release branch) to work on the fix. However, that same bugfix if made in the release branch would require the same amount of work to merge into ''master'' so it's not saving any work to do it that way, and there are many drawbacks to the approach. |
===Bugfix Branches=== | ===Bugfix Branches=== | ||
| − | Many times a bugfix is simple and the code has not diverged. In that case the bug can be fixed on '' | + | Many times a bugfix is simple and the code has not diverged. In that case the bug can be fixed on ''master'' and the changeset can be merged (cherry picked) directly onto the release branch. This will happen more often than not early on in the development cycle because ''master'' and the release started the same. As time goes on it may happen less often depending on the actual change and how much the code has diverged. |
| − | If the code has diverged enough that a simple bugfix can't be applied, or the bugfix is sufficiently complicated, then that bugfix warrants a bugfix branch. The developer can create a branch off the release branch to work on the bugfix, and once that's been tested that branch can be merged back into the release branch. Note that the bug should STILL be fixed in '' | + | If the code has diverged enough that a simple bugfix can't be applied, or the bugfix is sufficiently complicated, then that bugfix warrants a bugfix branch. The developer can create a branch off the release branch to work on the bugfix, and once that's been tested that branch can be merged back into the release branch. Note that the bug should STILL be fixed in ''master'' first. |
===Changeset Auditing Process=== | ===Changeset Auditing Process=== | ||
All changes to a release branch must be audited. | All changes to a release branch must be audited. | ||
| − | * Before any changes may be made to a release branch, the changeset should exist either in '' | + | * Before any changes may be made to a release branch, the changeset should exist either in ''master'' (if it's a simple fix) or a specific bugfix branch (if the changeset is complicated enough that it just can't apply cleanly). This way the change is already in [[Git]] and has a chance to be vetted before pulled onto the release branch. |
* Developers should request changesets get audited and approved before they are pulled into the release branch. You can tag a changeset for audit by putting '''BP''' on a line by itself in your commit log. ("BP" stands for "BackPort"). Make sure the '''BP''' is on a line by itself with no surrounding whitespace. Once upon a time, the '''commit-hook''' would send an extra email to gnucash-devel requesting that the change be audited, but that's been commented out. It still adds [Audit] to the front of the subject line of the commit email. | * Developers should request changesets get audited and approved before they are pulled into the release branch. You can tag a changeset for audit by putting '''BP''' on a line by itself in your commit log. ("BP" stands for "BackPort"). Make sure the '''BP''' is on a line by itself with no surrounding whitespace. Once upon a time, the '''commit-hook''' would send an extra email to gnucash-devel requesting that the change be audited, but that's been commented out. It still adds [Audit] to the front of the subject line of the commit email. | ||
Revision as of 17:22, 23 November 2013
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.
Contents
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 do the documentation self, 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
- <release> -- the current release branch(es)
Git transition note: Until the conversion to Git is completed after the release of Gnucash-2.6, committers will use git svn dcommit to push changes to the Subversion repository. One may experience difficulties with using branch master instead of branch trunk during that time. At the time of this writing, all active committers are already practiced at this, so this note is merely for completeness.
Developers may also have other branches in use for development or bugfixing. This is described later in this document.
Developing New Features
All development should target the master branch. This includes new features, bug fixes, 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.
At any particular time, master should be "as stable as possible". We use feature branches to limit the chance 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
Minor changes may be pushed directly to master.
Major Changes
Use your judgement about whether your major change should be done directly on master or whether you should use a development branch. We trust you. Just remember, smaller changesets are easier to audit.
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
Contrary to some beliefs, bug fixing is still development; it's just a different type of development. Indeed, whenever a bug exists that bug most likely exists in all branches, so it should get fixed in all branches. Therefore, the bugfix process should provide a way to fix a bug in trunk and, when necessary or appropriate, also on release branches.
Fixing bugs leads to its own set of issues, especially due to the fact that trunk will diverge from the release branches. Some may think that it would be easier to just commit bugfixes directly to the release branch and then merge back into trunk, but while this might require fewer command-line operations, it has many pitfalls.
Pitfalls of fixing directly on a release branch
- it requires unvetted changes be committed to the release branch
- it fails to work well if we have multiple release branches
- as master diverges, the merging can become even more challenging. While cherry-picking changesets to pull into a release branch requires typing more commands, merging a large set of changes from the release branch back into master can become a huge tangled mess if any of the changes don't apply cleanly.
- when looking at a change in master to see why a line of code changed git blame would only show that the change came from a "merge from stable branch" instead of showing who actually made the change or why.
It is true that as master diverges some bugfixes might require a lot of work to "backport" to the release branch (assuming that the fix even IS a backport). In that case, the developer should use a bugfix branch (based off the release branch) to work on the fix. However, that same bugfix if made in the release branch would require the same amount of work to merge into master so it's not saving any work to do it that way, and there are many drawbacks to the approach.
Bugfix Branches
Many times a bugfix is simple and the code has not diverged. In that case the bug can be fixed on master and the changeset can be merged (cherry picked) directly onto the release branch. This will happen more often than not early on in the development cycle because master and the release started the same. As time goes on it may happen less often depending on the actual change and how much the code has diverged.
If the code has diverged enough that a simple bugfix can't be applied, or the bugfix is sufficiently complicated, then that bugfix warrants a bugfix branch. The developer can create a branch off the release branch to work on the bugfix, and once that's been tested that branch can be merged back into the release branch. Note that the bug should STILL be fixed in master first.
Changeset Auditing Process
All changes to a release branch must be audited.
- Before any changes may be made to a release branch, the changeset should exist either in master (if it's a simple fix) or a specific bugfix branch (if the changeset is complicated enough that it just can't apply cleanly). This way the change is already in Git and has a chance to be vetted before pulled onto the release branch.
- Developers should request changesets get audited and approved before they are pulled into the release branch. You can tag a changeset for audit by putting BP on a line by itself in your commit log. ("BP" stands for "BackPort"). Make sure the BP is on a line by itself with no surrounding whitespace. Once upon a time, the commit-hook would send an extra email to gnucash-devel requesting that the change be audited, but that's been commented out. It still adds [Audit] to the front of the subject line of the commit email.
- Provided the audit is approved, or more likely no-one objects, then the changes can be added to the release branch.
- Git svn users can, after checking out the release branch, run the script util/git-backport.sh <svn release number>. It will look up the SHA using git svn find-rev, then cherry-pick and modify the commit message. Also, if your local username ("whoami") is different from the SVN username, you can set the environment variable WHOAMI to your SVN username. This is used to decide whether a line saying "Original commit by ..." is appended as well.
- Any change that gets requested to merge onto a release branch should have an associated entry in Bugzilla. The bug should contain the changeset number with the bugfix in trunk (or the name of the bugfix branch).
- If you audit a changeset and believe that it is safe for backporting and does not introduce other bugs (i.e., you've tested it and haven't noticed new issues) then you should add a comment in the bug report and/or respond to the audit-request email.
- Releases can have a catch-all bug to keep as a blocker dependency of all audit-changeset bugs. (The last time this was used was for 2.2.0, Bug #486922). When you request an audit for a change which fixes a bug, you make the bug a blocker of the catch-all. Once the requested and audited change is pulled into the release branch (or rejected) the bug will get closed.
- Alternatively, set the milestone on the bug to the next stable release. When the change is rejected for backport, the developer rejecting it can close the bug; if it's accepted, the bug should be closed by whoever commits the backport.
Changes on the Build System
Currently we are using the Autotools - only Cutecash uses CMake.
If you change e.g. configure.ac you should also check, if e.g (FIXME: please complete this list!)
- CMakeLists.txt,
- README.* and Dependencies,
- packaging/gnucash.spec.in (used to build RPM Packages) or
- packaging/win32/*
need some adjustments.
Updating Translations
Translations are "special". Translation updates can be made directly into the po directory of the release branch.
