Changes between Version 4 and Version 5 of ImprovingPractices


Ignore:
Timestamp:
Aug 8, 2007, 2:13:02 AM (15 years ago)
Author:
Darren Garvey
Comment:

Fixed anchors and svn links; unfortunately had to change layout of definitions

Legend:

Unmodified
Added
Removed
Modified

  • ImprovingPractices

    v4 v5  
    1313 * 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.
    1414
    15  * The latest [#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.
     15 * The latest [#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.
    1616
    1717 * Release preparation does not require super-human effort by the release manager, developers, or testers.
    1818
    19  * A [#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.
     19 * A [#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.
    2020
    2121 * 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.
    2222
    23  * [#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.
     23 * [#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.
    2424
    2525 * Error reporting, including pestering, does not produce false positives, such as when failure for a library is due to instability in its dependencies.
    … …  
    2929== Definitions  ==
    3030
    31 '''''Release-ready''''' - 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.
     31 ==== ''Release-ready'' ====
     32 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.
    3233
    33 '''''Stable''''' - A library or branch that passes regression tests, but does not necessarily meet other release criteria.
     34 ==== ''Stable'' ====
     35 A library or branch that passes regression tests, but does not necessarily meet other release criteria.
    3436
    35 '''''Prerequisite library''''' - A library other libraries are dependent upon.
     37 ==== ''Prerequisite library'' ====
     38 A library other libraries are dependent upon.
    3639
    3740== Strategies ==
    … …  
    3942 * The starting point for each new release is the prior release.
    4043
    41  * A [#release-ready release-ready] repository tree is maintained at all times.
     44 * A [#Release-ready release-ready] repository tree is maintained at all times.
    4245
    4346 * Reduce the time lag between when a library developer needs fresh test results and when those results actually become available.
    … …  
    4952== Repository Organization ==
    5053
    51 '''''Release tree'''''  -  [#release-ready release-ready] tree to which libraries are copied after release-ready. ''We may decide to make this tree read-only except for the release management team.''
     54 ==== ''Release tree'' ====
     55 [#Release-ready release-ready] tree to which libraries are copied after release-ready. ''We may decide to make this tree read-only except for the release management team.''
    5256
    53  The URL for the release tree is //svn.boost.org/svn/boost/release
     57 The URL for the release tree is [source:/release http://svn.boost.org/svn/boost/release]
    5458
    55 '''''Release tags''''' - These are copies of the the Release tree 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.
     59 ==== ''Release tags'' ====
     60 These are copies of the the Release tree 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.
    5661
    57  The URLs for release candidates are in the form //svn.boost.org/svn/boost/release/Version_1_35_0_RC1
     62 The URLs for release candidates are in the form [source:/release/Version_1_35_0_RC1 http://svn.boost.org/svn/boost/release/Version_1_35_0_RC1]
    5863
    59  The URLs for final releases are in the form //svn.boost.org/svn/boost/release/Version_1_35_0
     64 The URLs for final releases are in the form [source:/release/Version_1_35_0 http://svn.boost.org/svn/boost/release/Version_1_35_0]
    6065
    61 '''''Main trunk''''' - The main development and test location.
     66 ==== ''Main trunk'' ====
     67 The main development and test location.
    6268
    63 Every effort must be made to keep [#prerequisite-libraries prerequisite libraries] stable in the main trunk, since failures in these libraries cascade into the testing of other libraries.
     69 Every effort must be made to keep [#Prerequisitelibrary prerequisite libraries] stable in the main trunk, since failures in these libraries cascade into the testing of other libraries.
    6470
    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.
     71 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.
    6672
    67  The URL for the main trunk is //svn.boost.org/svn/boost/trunk
     73 The URL for the main trunk is [source:/trunk http://svn.boost.org/svn/boost/trunk]
    6874
    69 '''''Development branches''''' - Location for speculative/experimental/future work on an individual library or set of libraries.
     75 ==== ''Development branches'' ====
     76 Location for speculative/experimental/future work on an individual library or set of libraries.
    7077
    71  The URL for development branches is //svn.boost.org/svn/boost/branches/branch-name
     78 The URL for development branches is [source:/branches/branch-name http://svn.boost.org/svn/boost/branches/branch-name]
    7279
    7380== Development Cycle ==
    7481
    75 Developers can ensure a [#stable stable] development environment by checking out //svn.boost.org/svn/boost/release as their working copy, and then [http://svnbook.red-bean.com/en/1.1/ch04s05.html switching] only the library they are working with to //svn.boost.org/svn/boost/trunk or a library specific development branch.
     82Developers can ensure a [#Stable stable] development environment by checking out [source:/release http://svn.boost.org/svn/boost/release] as their working copy, and then [http://svnbook.red-bean.com/en/1.1/ch04s05.html switching] only the library they are working with to [source:/trunk http://svn.boost.org/svn/boost/trunk] or a library specific development branch.
    7683
    7784=== Copying from main trunk to release tree ===
    7885
    79 Only when a library update is tested and stable on trunk, and is fully [#release-ready release-ready], is it copied into the [#release-tree release tree]. (This copy operation is performing what in CVS would be called tagging.)
     86Only when a library update is tested and stable on trunk, and is fully [#Release-ready release-ready], is it copied into the [#Release-tree release tree]. (This copy operation is performing what in CVS would be called tagging.)
    8087
    8188''Details of when copies into the release tree are acceptable and who actually does the copy are yet to be worked out. One possibility is to allow any developer to copy into the release tree at any time except immediately before a release.''
    … …  
    8390=== Special case: Prerequisite libraries ===
    8491
    85 [#prerequisite-libraries Prerequisite library] 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.
     92[#Prerequisitelibrary Prerequisite library] 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.
    8693
    8794The 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.
    … …  
    99106=== Trunk testing ===
    100107
    101 The [#trunk main trunk] 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.
     108The [#Maintrunk main trunk] 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.
    102109
    103110=== Release testing ===
    104111
    105 In theory, it should not be necessary to test the [#release-tree release tree] at all, since everything merged into it should already be known to be [#release-ready release-ready].
     112In theory, it should not be necessary to test the [#Releasetree release tree] at all, since everything merged into it should already be known to be [#Release-ready release-ready].
    106113
    107114In 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.