| | 1 | = Development and Release Practices = |
| | 2 | |
| | 3 | == Introduction == |
| | 4 | |
| | 5 | Boost developers are currently reengineering development tools, workflow, and practices aimed at more timely Boost releases with less heroics required to get releases ready to ship. |
| | 6 | |
| | 7 | This Wiki page focuses on reorganizing our development practices and repository structure, and assumes only existing tools and scripts. Other parallel efforts focus on tools and other aspects of our release process. |
| | 8 | |
| | 9 | == Objectives == |
| | 10 | |
| | 11 | * Professional, reliable Boost releases suitable for users ranging from simple projects by individuals on up to very large multi-developer projects in large organizations. |
| | 12 | |
| | 13 | * Timely Boost releases on a predictable schedule, with no possibility that problems with a few libraries can delay a release of Boost as a whole. |
| | 14 | |
| | 15 | * The latest [wiki:ImprovingPractices#release-ready release-ready] Boost code available from the Subversion repository at all times, including both fixes and new libraries added subsequent to the last official release. Users of this version should not have to wait for a formal release, and should not have to run the risk of instability associated with purely developmental branches. |
| | 16 | |
| | 17 | * Release preparation does not require super-human effort by the release manager, developers, or testers. |
| | 18 | |
| | 19 | * A [wiki:ImprovingPractices#stable stable] development environment is maintained at all times, with the development of any one library decoupled from development of other libraries. In particular, there is no "wild west" syndrome where the overall development environment is unstable because the current development state of one or more individual libraries is unstable. |
| | 20 | |
| | 21 | * Boost subset releases are both possible and reasonably easy. For example, Spirit should be able to do a release of it and its dependencies at any time the Spirit team wishes to do so. Note: This implies many of the other objectives, and may also require changes in where Boost header files live within the directory structure. Forwarding headers or links can be used so that such a change is transparent to users. |
| | 22 | |
| | 23 | * [wiki:ImprovingPractices#release-ready release-ready] criteria include not only regression test failures, but also inspection failures, tool-chain errors, configuration errors, missing files, and any other detectable errors that reduce release quality or impact development environment stability. |
| | 24 | |
| | 25 | * Error reporting, including pestering, does not produce false positives, such as when failure for a library is due to instability in its dependencies. |
| | 26 | |
| | 27 | * Boost can to scale up to an ever-larger number of libraries, and do so without the incremental weight of each new library having a negative impact on development of other libraries or on release management. |
| | 28 | |
| | 29 | == Definitions == |
| | 30 | |
| | 31 | <a name="#release-ready"><i><b>Release-ready</b></i></a> - A library or branch that passes all appropriate tests and inspections, and meets all other release criteria, such as documentation being up-to-date. Note that the requirements for being release-ready are transitive; if a library has dependent libraries, it isn't considered release-ready if it breaks any of those dependent libraries. |
| | 32 | |
| | 33 | #stable '''''Stable''''' - A library or branch that passes regression tests, but does not necessarily meet other release criteria. |
| | 34 | |
| | 35 | <a name="#prerequisite-library"><i><b>Prerequisite library</b></i></a> - A library other libraries are dependent upon. |
| | 36 | |
| | 37 | == Strategies == |
| | 38 | |
| | 39 | * The starting point for each new release is the prior release. |
| | 40 | |
| | 41 | * A [wiki:ImprovingPractices#release-ready release-ready] repository tree is maintained at all times. |
| | 42 | |
| | 43 | * Reduce the time lag between when a library developer needs fresh test results and when those results actually become available. |
| | 44 | |
| | 45 | * Use existing tools wherever possible, particularly the tools Boost is already using like bjam and Subversion. Avoid introducing additional complex tool chains. |
| | 46 | |
| | 47 | * Encourage tool maintainers to increase tool robustness. |
| | 48 | |
| | 49 | == Repository Organization == |
| | 50 | |
| | 51 | <a name="#release-tree"><i><b>Release tree</b></i></a> - [wiki:ImprovingPractices#release-ready release-ready] tree into which libraries are merged after beta testing. <i>We may decide to make this tree read-only except for the release management team.</i> |
| | 52 | |
| | 53 | :The URL for the release tree is //svn.boost.org/svn/boost/release |
| | 54 | |
| | 55 | <i><b>Release tags</b></i> - These are copies of the the Release Branch made by the release manager, identifying the basis for generating tarballs and such. There are two forms; one for release candidates, another for final releases. |
| | 56 | |
| | 57 | :The URLs for release candidates are in the form <nowiki>//svn.boost.org/svn/boost/tags/Version_1_35_0_RC1</nowiki> |
| | 58 | |
| | 59 | :The URLs for final releases are in the form <nowiki>//svn.boost.org/svn/boost/Version_1_35_0</nowiki> |
| | 60 | |
| | 61 | <a name="#main-trunk"><i><b>Main trunk</b></i></a> - The main development and test location. |
| | 62 | |
| | 63 | Every effort must be made to keep <a href="#prerequisite-libraries">prerequisite libraries</a> stable in the main trunk, since failures in these libraries cascade into the testing of other libraries. |
| | 64 | |
| | 65 | There is no need or obligation for non-prerequisite libraries to be stable in the main trunk, since by definition no other libraries depend on non-prerequisite libraries. |
| | 66 | |
| | 67 | :The URL for the main trunk is //svn.boost.org/svn/boost/trunk |
| | 68 | |
| | 69 | <i><b>Development branches</b></i> - Location for speculative/experimental/future work on an individual library or set of libraries. |
| | 70 | |
| | 71 | :The URL for development branches is //svn.boost.org/svn/boost/branches/branch-name |
| | 72 | |
| | 73 | == <a name="#development">Development Cycle</a> == |
| | 74 | |
| | 75 | Developers can ensure a <a href="#stable">stable</a> development environment by checking out //svn.boost.org/svn/boost/release as their working copy, and then <a href="http://svnbook.red-bean.com/en/1.1/ch04s05.html">switching</a> only the library they are working with to //svn.boost.org/svn/boost/trunk or a library specific development branch. |
| | 76 | |
| | 77 | === Merging from main trunk to release tree === |
| | 78 | |
| | 79 | Only when a library update is tested and stable on trunk, and is fully [wiki:ImprovingPractices#release-ready release-ready], is it merged into the <a href="#release-tree">release tree</a>. |
| | 80 | |
| | 81 | <i>Details of when the release tree merges are acceptable and who actually does the merge are yet to be worked out. One possibility is to allow any developer to merge into the release tree at any time except immediately before a release. A "Release_candidate" tag could be maintained, and either manually or by script moved up to the head of the release tree once the newly merged library passes all tests.</i> |
| | 82 | |
| | 83 | === Special case: Prerequisite libraries === |
| | 84 | |
| | 85 | <a href="#prerequisite-libraries">Prerequisite library</a> changes that run any risk of breaking libraries that depend on them should always be first applied and tested on a branch, and only merged into the main trunk when stable. |
| | 86 | |
| | 87 | The rationale is that changes to the main trunk that break prerequisite libraries are a serious problem because these changes destabilize the test environment for all libraries that depend on them. This causes developers of other libraries to expend needless effort tracking down test failures that aren't their fault. |
| | 88 | |
| | 89 | In an ideal world changes to prerequisite library branches should be tested on various platforms prior to merging into the main trunk. In the absence of test-on-demand facilities, we will have to rely on rapid test cycling and a willingness to revert changes when changes to a prerequisite library inadvertently breaks tests of other libraries. |
| | 90 | |
| | 91 | === Special case: Breaking changes to prerequisite libraries === |
| | 92 | |
| | 93 | This case will require special coordination among affected developers. Details yet to be worked out. It may simply come down to good coordination via the developers mailing list. |
| | 94 | |
| | 95 | == Testing == |
| | 96 | |
| | 97 | Both trunk and release testing go on continuously, independent of when releases actually occur. Testers never have to change the repository URLs they test against. |
| | 98 | |
| | 99 | === Trunk testing === |
| | 100 | |
| | 101 | The <a href="#trunk">main trunk</a> is where most testing resources should be concentrated, since these tests are what tell developers that their library works on all tested platforms and tell the release management team that it is OK to merge a library into the release tree. |
| | 102 | |
| | 103 | === Release testing === |
| | 104 | |
| | 105 | In theory, it should not be necessary to test the <a href="#release-tree">release tree</a> at all, since everything merged into it should already be known to be [wiki:ImprovingPractices#release-ready release-ready]. |
| | 106 | |
| | 107 | In practice, the release criteria platform/compiler combinations at the minimum should be tested on the release tree. A single reliable test runner for each release criteria platform/compiler combination should be sufficient. |
| | 108 | |
| | 109 | == Acknowledgments == |
| | 110 | |
| | 111 | This Wiki page is being maintained by Beman Dawes. |
| | 112 | |
| | 113 | Although the details differ, the release model described here is similar to <a href="http://lists.boost.org/Archives/boost/2006/01/99522.php">proposed by Robert Ramey</a> where he suggested "Each library could be developed at its own pace and schedule." |
| | 114 | |
| | 115 | Refinements of a May, 2006, draft proposal by Beman Dawes were based on comments from Michael Fawcett, Simon Carter, Arkadiy Vertleyb, Pedro Lamarão, Robert Ramey, Anthony Williams, and Thorsten Ottosen. |
| | 116 | |
| | 117 | Discussion during <a href="http://www.boostcon.com"><nowiki>BoostCon</nowiki> 2007</a> between Beman Dawes, Thomas Witt, Troy Straszheim, Dave Abrahams, Eric Niebler, and Doug Gregor shaped this proposal. |
| | 118 | |
| | 119 | Comments and corrections to this page were contributed by Stefan Seefeld, Peter Dimov, ... |
