Development Branches

The development of major changes shall be done on a development branch of this trunk, meaning, temporarily on a different track in parallel until the changes are stable enough in order to be merged back in the trunk. The development branch is created and maintained by the developer implementing the change. Under some circumstances, development may be done in a private development tree, but the Orocos community strongly favours the use of a branch in the publicly accessible Orocos development tree. In order to setup a branch consult the Orocos branch management document.

 Trunk / HEAD
       |
       +-- Development branch created ------+
       |                                     \
       |                                      \
       |                                       \ Develop a major change
       |                                        \
       |        merge in Stage 1 (see below)     x (done)
       |  <-------------------------------------/
       |
       v
  Orocos Development
       |
       V

Examples of major changes which require a development branch include:

• A port to a new processor target or OS
• Refactoring involving the core infrastructure (interface changes)
• Development of new Components or Application Templates

There is no firm guideline for what constitutes a "major change" and what does not. If a developer is unsure, he or she should ask for guidance on the Orocos mailing lists. In general, any change that has the potential to be extremely destabilizing should be done on a branch.

Changes from a development branch may be merged with the trunk only after:

• They meet the standards for any other check-in. For example, the code must be well-documented, and any user-visible changes should be documented in the manual(s).
• The code must contain test cases for new functionality or be sufficiently covered by current tests.
• The branch has been validated on at least two different targets. Validation should consist of 'make robot_control check', and checking that there are no new regression test failures. The same is repeated for 'make control_services check'

Release Branches

Release branches are created and maintained by the Orocos Maintainer. They are 'spawned' at well defined times from the trunk (see below) and serve to facilitate release packaging and backwards compatible bug fixing.

As an exception, development releases do not come from release branches, but directly from trunk. Their 'minor' versions are unevenly numbered (like 2.1.0) and provide a 'snapshot' of the current status of the trunk. A development release may thus in the worst case not provide working software.

Rationale

Making major improvements to the code is good. However, such changes are inevitably somewhat destabilizing. By using a branch, it is possible for people to test and improve the code, but without impacting other developers. By testing major changes more thoroughly than ordinary changes, we will help reduce the impact on other developers.

In addition, the presence of half-finished projects on the mainline presents a variety of problems when preparing for a release. If serious bugs remain, it may be impossible to do a release until the bugs are fixed, thereby impacting the release schedule. If functionality is present, but not robust (for example, crashes upon wrong user input), then we can seriously confuse users.

Schedule

Development on our main branch will proceed in three stages. Each stage after stage 1 will be one month in length.

Stage 1 : Accept new projects

During this period, changes of any nature may be made to the code. In particular, major changes may be merged from branches. In order to avoid chaos, the Release Manager will ask for a list of major projects proposed for the coming release cycle before the start of Stage 1. The Release Manager will attempt to sequence the projects in such a way as to cause minimal disruption. The Release Manager will not reject projects that will be ready for inclusion before the end of Stage 1. Similarly, the Release Manager has no special power to accept a particular patch or branch beyond what his or her status as a maintainer affords. The Release Manager's role during Stage 1 is merely to attempt to order the inclusion of major features in an organized manner.

In case no candidate projects are ready for Stage 1, we remain in this stage until a candidate project merges. After this merge Stage 2 may be announced.

Stage 2 : Improve code

During this period, major changes may not be merged from branches. However, other smaller improvements may be made. For example, extending the interface of a component, implementing an algorithm more efficiently, adding support for a new kinematic chain etc.

Stage 3 : Hunt down bugs

During this period, the only (non-documentation) changes that may be made are changes that fix bugs (or add tests to detect bugs) or new ports which do not require changes to other parts of the compiler. New functionality may not be introduced during this period.

Rationale

In order to produce releases on a regular schedule, we must ensure that the mainline is reasonably stable some time before we make the release. Therefore, more radical changes must be made earlier in the cycle, so that we have time to fix any problems that result.

In order to reach higher standards of quality, we must focus on fixing bugs; by working exclusively on bug-fixing through Stage 3, we will have a higher quality source base as we prepare for a release.

Although maintaining a development branch, including merging new changes from the mainline, is somewhat burdensome, the absolute worst case is that such a branch will have to be maintained for two months (thus until before the merge). During one month, the only mainline changes will be bug-fixes, so it is unlikely that many conflicts will occur.

Patch Reversion

If a patch is committed which introduces a regression on any target which the Release Manager considers to be important and if:

• the problem is reported to the original poster;
• 48 hours pass without the original poster or any other party indicating that a fix will be forthcoming in the very near future;
• two people with write privileges to the affected area of the code determine that the best course of action is to revert the patch;

then they may revert the patch.

After the patch has been reverted, the poster may appeal the decision to the Release Manager.

Note that no distinction is made between patches which are themselves buggy and patches that expose latent bugs elsewhere in the code.

Rationale

If an important platform is broken, then it will be difficult to prepare a release. If nobody volunteers to fix the problem, then we will have an unpleasant choice: delay the release, or release a product that we know to be worse than the previous release. Therefore, it is important that we be able to revert patches that cause problems. In addition, regressions on the mainline can impede the development of other improvements.

On the other hand, we want to encourage new development, and new development inevitably introduces new bugs. Therefore, it is important that decisions be made on a case-by-case basis, and that the proponent of a change have an opportunity to argue that the benefits of the change outweigh the costs.

Schedule

At the conclusion of Stage 3, a release branch will be created on which the releases will be made.

On the release branch, the focus will be fixing any regressions from the previous release, so that each release is better than the one before.

The first release will occur one month after the creation of the branch. (Stage 1 of the next release cycle will occur in parallel.) If, however, support for an important platform has regressed significantly from the previous release or support for a platform with active maintenance has regressed significantly relative to an earlier Stage in the current release cycle, the release will be postponed until the regressions are corrected, unless the Release Manager releases the automatic hold on the release.

   End of Stage 3
       |
       +- Release branch created --+                ---
       |                            \                 |
       |                             v                | Takes 1 Month.
       |                       Orocos 0.22.0 release --
       |                              \
       |                               v
       |                         Orocos 0.22.1 release
       |                                         :
       v                                         :
  Orocos Main Development

Rationale

While making releases on schedule is important, quality should not be subordinate to schedule. If a major platform is not adequately supported, but was well supported in a previous release, then we should address the problems. Presumably, this will not be unduly difficult, since we will have spent four months fixing bugs by the time the release would occur.

Bug-fix Releases

Bug-fix releases will be made two and four months after the initial release, as necessary.

Rationale

By waiting for two months to make a bug-fix release, we will be able to accumulate fixes for the most important problems, and avoid spending undue amounts of time on release testing and packaging.

Release Timeline

Here is a history of recent and a tentative timeline of upcoming stages of development, branch points, and releases:

  ... former releases ...
       |
       +-- Orocos 0.18 branch created ------+
       |              (15 Dec 2004)          \
       |                                      v
       |                                   Orocos 0.18.0 release (15 Dec 2004)
       |                                       \
       |                                        v
       |                                     Orocos 0.18.1 release (31 Jan 2005)
       |                                         \
       v                                          v
  Orocos Development                           Orocos 0.18.2 release (08 Feb 2005)
       |
       |
       +-- Orocos 0.20 branch created ------+
       |              (07 May 2005)          \
       |                                      v
       |                                   Orocos 0.20.0 release (23 May 2005)
       |                                       \
       |                                        v
       |                                     Orocos 0.20.1 release (1 Aug 2005)
       v
  New Development Plan in Effect (6 Feb 2006)
       |
       |
       +-- Orocos 0.22 branch created ------+
       |              (24 Feb 2006)          \
       |                                      v
  Orocos 0.24 Stage 1 (ended 13 Apr 2006)   Orocos 0.22.0 release (13 Mar 2006 )
       |                                       \
       |                                        v
  Orocos 0.24 Stage 2 (ended 13 May 2006)     Orocos 0.22.1 release (13 Apr 2006 )
       |
       v
  Orocos 0.24 Stage 3 (ends 1 June 2006)
       |
       |
       +-- Orocos 0.24 branch created ------+
       |                                     \
       |                                      v
  Orocos 1.0 Stage 1  (June 2006)          Orocos 0.24.0 release (26 June 2006 )
       |                                       \
       |                                        v
  Orocos 1.0 Stage 2  (July 2006)          Orocos 0.24.1 release (27 July 2006 )
       |
       v
  Orocos 1.0 Stage 3  (10 Okt 2006)
       |
       +-- Orocos 1.0  branch created ------+
       |                                     \
       |                                      v
  Orocos 1.2 Stage 1                       Orocos 1.0 release ( 10 Nov 2006 )
       :
       v