Changes between Version 19 and Version 20 of pm-svn-releases


Ignore:
Timestamp:
Nov 24, 2010 2:17:03 PM (10 years ago)
Author:
lou
Comment:

Update to push PMs towards the stable and release scripts.

Legend:

Unmodified
Added
Removed
Modified
  • pm-svn-releases

    v19 v20  
    6363You usually create a new stable branch with a version number {{{x.y}}} (''e.g.'', {{{2.3}}}) from some version of your code that exists in the repository.  Typically, you would have been working in {{{trunk/}}} (where the active development takes place), and want to release the current {{{trunk/}}} version in the repository as a new stable branch.
    6464
    65 A new stable branch with the chosen version number is created in the repository using the {{{svn copy}}} command.  In order to create stable branch {{{2.3}}} from {{{trunk/}}} you could use
     65'''It is strongly recommended''' that you use the {{{prepare_new_stable}}} and {{{commit_new_stable}}} scripts provided in !BuildTools. These scripts will automatically make the changes to configuration files and externals required to conform with COIN standards for stable branches.
     66The first script, {{{prepare_new_stable}}}, does the following things for you:
     67
     68 * automatically determines the next minor revision within the current major revision
     69 * checks out a clean copy of the trunk (without externals)
     70 * creates a {{{Dependencies}}} file from the {{{Externals}}} file, if one does not already exist
     71 * updates {{{Dependencies}}} to reference the most recent stable branch of each external, then sets {{{svn:externals}}} to the most recent release
     72 * updates version information in your {{{configure.ac}}} and {{{ProjConfig.h}}} files
     73 * checks out the code for the externals and checks to see if they are using the same version of !BuildTools
     74 * uses the "get.*" scripts to download any !ThirdParty code
     75 * executes {{{run_autotools}}} to rebuild configuration files
     76 * runs the configure script and compiles the code
     77 * runs the unit test
     78
     79The result is left in a local directory. Once you're satisfied, use the {{{commit_new_stable}}} script to commit the new stable branch to the repository. It will
     80 * commit the stable branch candidate to trunk
     81 * perform a repository-side copy of the trunk into the new stable branch
     82 * restore the local copy to its original state by backing out all changes
     83 * commit the restored local copy to trunk, restoring trunk to its original state
     84
     85The scripts have extensive help texts. There are options to bump the major version and to control the handling of externals and checks for !BuildTools mismatches.
     86
     87If, for some reason, you elect to create a new stable branch by hand, here are rough instructions. A new stable branch with the chosen version number is created in the repository using the {{{svn copy}}} command.  In order to create stable branch {{{2.3}}} from {{{trunk/}}} you could use
    6688
    6789{{{
     
    81103=== Maintaining a Stable Version ===
    82104
    83 To change the content of a stable version, you work with it as usual: creating (checking out) a local copy of the code in that branch, making changes there (directly by editing, or [wiki:pm-svn-branches by using {{{svn merge}}}] to include changes made in a different version in the repository, such as {{{trunk}}}), and finally submitting the changes back to the repository.
     105To change the content of a stable version, you work with it as usual: creating (checking out) a local copy of the code in that branch, making changes there (directly by editing, or [wiki:pm-svn-branches by using svn merge] to include changes made in a different version in the repository, such as {{{trunk}}}), and finally submitting the changes back to the repository.
    84106
    85107== Working With Point Releases ==
     
    91113Typically, you would have a version of your code in a stable branch, say {{{stable/2.3/}}}, which you now want to make an official release.  '''Remember, it is mandatory that one can recreate exactly the same version in the future''', ''i.e.'', you should not change anything in a point release after you set it up.
    92114
    93 If you have no [wiki:pm-svn-externals Externals] then the simplest way is to use "svn copy" similar to the in the example above. To create release {{{2.3.2}}} from stable branch {{{2.3}}} you could use
     115'''It is strongly recommended''' that you use the {{{prepare_new_release}}} and {{{commit_new_release}}} scripts provided in !BuildTools. These scripts will automatically make the changes to configuration files and externals required to conform with COIN standards for releases (including libtool library versioning).
     116The scripts have extensive help texts.
     117
     118The first script, {{{prepare_new_release}}}, does the following things for you:
     119
     120 * automatically determines the next patch level (release) within the specified minor revision (stable branch)
     121 * checks out a clean copy of the stable branch (without externals)
     122 * sets {{{svn:externals}}} to the most recent release of each external, based on the stable branch specifications in {{{Dependencies}}}
     123 * updates version information in your {{{configure.ac}}} and {{{ProjConfig.h}}} files
     124 * checks out the code for the externals and checks to see if they are using the same version of !BuildTools
     125 * uses the "get.*" scripts to download any !ThirdParty code
     126 * executes {{{run_autotools}}} to rebuild configuration files
     127 * runs the configure script and compiles the code
     128 * runs the unit test
     129
     130The result is left in a local directory. Once you're satisfied, use the {{{commit_new_release}}} script to commit the new release to the repository. It will
     131 * commit the release candidate to the stable branch
     132 * perform a repository-side copy of the stable branch into the new release
     133 * restore the local copy to its original state by backing out all changes
     134 * commit the restored local copy to the stable branch, restoring the stable branch to its original state
     135
     136The scripts have extensive help texts. There are options to control the handling of externals and checks for !BuildTools mismatches.
     137
     138
     139If, for some reason, you elect to create a release by hand, the simplest way is to use "svn copy" similar to the example above for manual creation of a new stable branch. To create release {{{2.3.2}}} from stable branch {{{2.3}}} you could use
    94140
    95141{{{
     
    107153and looked at the line that starts with "{{{Revision:}}}".
    108154
    109 If you do have externals (especially externals pointing to other COIN projects), or if you want to take advantage of the sanity checks in the scripts to be described, then {{{BuildTools}}} provide two convenient scripts that make it easy for you to create a new release from a stable branch.  In case you are using [wiki:pm-svn-externals Externals], you need to be using only references to externals in ''stable'' branches of other projects.
    110 
    111 '''NOTE: both scripts contain very subtle "bashisms", i.e., they may not run correctly unless executed using bash. The simplest way to ensure this is to specify bash as the shell to run them, e.g.,
    112 {{{
    113 bash BuildTools/prepare_new_release
    114 }}}
    115 
    116 The first script, {{{BuildTools/prepare_new_release}}}, does the following things for you:
    117 
    118  * automatically determines the next release number
    119  * checks out a clean copy of the stable version specified
    120  * updates the externals to point to the latest releases in the dependencies (for the same stable branch as specified in the Externals file)
    121  * updates the version number in your configure.ac files
    122  * receives the code for the externals
    123  * uses the "get.*" scripts to download !ThirdParty code (if there are any)
    124  * reruns the autotools
    125  * checks if all dependencies are using the same version of the !BuildTools
    126  * runs the configure script and compiles the code
    127  * runs the unit test
    128 
    129 If any of those steps fail, you need to correct the errors first before you can continue.  It is a good idea to have a good look at the output of the compilation and unit test, even if no errors are reported.
    130 
    131 Once there are no errors and you are happy with what you saw in the output, you can use the {{{commit_new_release}}} script to commit the new release to the repository.  This second script will do the following:
    132 
    133  * temporarily commits the modified local copy of your stable branch to the repository (including externals pointing to release versions of the dependencies)
    134  * creates the new release by copying the temporarily committed stable branch to a new {{{releases/x.y.z}}} directory in the repository
    135  * restores the previous definition of the externals in your stable branch and commits the restored stable branch to the repository
    136 
    137 Here an example:  Assume, that in your project {{{YourProject}}} you have a stable branch {{{stable/2.3}}} from which you want to make a new release.  In a shell, go into a temporary directory and type:
    138 
    139 {{{
    140 /path/to/your/local/copy/BuildTools/prepare_new_release YourProject/stable/2.3
    141 }}}
    142 
    143 As you see, the specified argument is simple the last part of the URL in the repository, i.e., the stuff that comes after {{{https://projects.coin-or.org/svn/}}}.
    144 
    145 This will run for a while (you need to be connected to the network, of course).  If everything works fine, you will see something like:
    146 
    147 {{{
    148 ===> ALL TESTS PASSED
    149 
    150 Please review the output above, particularly the one of make test
    151 
    152 Also, please check the Externals:
    153 BuildTools  https://projects.coin-or.org/svn/BuildTools/releases/0.5.13
    154 ...
    155 
    156 After reviewing the output above, you can create a new release by going into
    157 the directory
    158 
    159           /path/to/tempdir/tmp_checkout
    160 
    161 and run the commit_new_release script
    162 }}}
    163 
    164 Just follow the instructions (use the {{{commit_new_release}}} script that is in the same directory as the {{{prepare_new_release}}} script you just ran).
    165 
    166 
    167155== Tarball Creation ==
    168156