Changes between Version 9 and Version 10 of pm-svn-releases


Ignore:
Timestamp:
Oct 10, 2006 2:12:31 PM (14 years ago)
Author:
lou
Comment:

Typos and minor editorial changes.

Legend:

Unmodified
Added
Removed
Modified
  • pm-svn-releases

    v9 v10  
    11= Suggestions for Handling Stable Versions and Releases =
    22
    3 This page describes how the [https://projects.coin-or.org/CoinTLC/wiki/VersionsAndReleases policy for versioning suggested by COIN] can be implemented within the subversion repository for your project. You might want to first read the page on [wiki:pm-svn-branches understanding branches and tags], or other pages for [wiki:pm-svn understanding subversion]. Below, the string ''YourProject'' is to be repleaced by the name of your project.
     3This page describes how the [https://projects.coin-or.org/CoinTLC/wiki/VersionsAndReleases policy for versioning suggested by COIN] can be implemented within the subversion repository for your project. You might want to first read the page on [wiki:pm-svn-branches understanding branches and tags], or other pages for [wiki:pm-svn understanding subversion]. Below, the string ''YourProject'' is to be replaced by the name of your project.
    44
    55== Overview ==
    66
    7 The overall philosophy of the COIN-OR versioning and release system is to specify standard procedures for maintaining the code base of COIN-OR projects that allow various groups of users to obtain the version of the code most appropriate for them. The recommended [wiki:pm-svn subversion] repository layout for COIN-OR projects includes the top-level directories {{{trunk/}}}, {{{branches/}}}, {{{tags/}}}, {{{stable/}}}, and {{{releases/}}}. At all times, the main development line is to be contained in {{{trunk/}}}. The code in {{{trunk/}}} is not expected to be completely functional and is the "bleeding edge" of the project. At specified points in time, specific versions can be slit off from this main development line for the purpose of implementing special features or declaring a '''stable release''' (see below). The directories {{{branches/}}} are optional directories that can contain version implementing or testing experimental features. The directory {{{tags/}}} is for storing fixed and named snapshots of code for future reference. No new code should ever be committed to the {{{tags/}}} directory. The use of the {{{stable/}}} and {{{releases/}}} directory is to create stable versions of the project for users to download and other projects to link to. This explained in more detail next.
     7The purpose of the COIN-OR versioning and release system is to specify standard procedures for maintaining the code base of COIN-OR projects so that users can obtain the version of the code most appropriate for them. The recommended [wiki:pm-svn subversion] repository layout for COIN-OR projects includes the top-level directories {{{trunk/}}}, {{{branches/}}}, {{{tags/}}}, {{{stable/}}}, and {{{releases/}}}.
    88
    9 A '''stable version''' is created whenever the PM wishes to declare a new version of the project. Creating a '''stable version''' means roughly that the feature set and API associated with that particular version should be frozen, but the code may continue to evolve through the application of patches to fix bugs, the addition of documentation, etc. Such a "stable version" is identified by a two-digit version number (i.e., 5.1) and is associated with a similarly-named subdirectory in {{{stable/}}} created by branching (copying) the code in {{{trunk/}}} (see below for specific commands to be used for this prupose). In subversion, such a two-digit version is not frozen once copied to {{{stable/}}}. It is intended to continue evolving and new code can be committed to subdirectories in the {{{stable/}}} directory. However, this evolution should generally consist of bug fixes and minor tweaking only---development of new features for future versions can continue at the same time in {{{trunk/}}}. Bug fixes applied to versions in {{{stable/}}} may also need to be merged into {{{trunk/}}}, as appropriate (see below).
     9At all times, the main development line is to be contained in {{{trunk/}}}. The code in {{{trunk/}}} is not expected to be completely functional and is the "bleeding edge" of the project. At appropriate points in time, specific versions can be split off from the main development line for the purpose of declaring a '''stable release''' (see below) or implementing special features.
     10
     11The {{{branches/}}} and {{{tags/}}} directories may be used at the developer's convenience. Directories under {{{branches/}}} typically contain versions of the code created to implement or test experimental features. The {{{tags/}}} directory can be used for storing fixed and named snapshots of code for future reference. To maintain the utility of tags, subversion usage conventions recommend that no new code should ever be committed to the {{{tags/}}} directory.
     12
     13The {{{stable/}}} and {{{releases/}}} directories hold the stable versions of a project that are referenced as externals by other projects and downloaded by users.
     14A '''stable version''' is created whenever the PM wishes to declare a new version of the project. Creating a '''stable version''' means roughly that the feature set and API associated with that particular version are frozen, but the code may continue to evolve through the application of patches to fix bugs, the addition of documentation, ''etc.'' Such a "stable version" is identified by a two-digit version number (''i.e.'', 5.1) and is associated with a similarly-named subdirectory in {{{stable/}}} created by branching (copying) the code in {{{trunk/}}} (see below for specific commands to be used for this purpose). Stable versions are not considered frozen when copied to {{{stable/}}}. It is intended that they continue to evolve and new code can be committed to subdirectories in the {{{stable/}}} directory. However, this evolution should generally consist of bug fixes and minor tweaking only---development of new features for future versions can continue at the same time in {{{trunk/}}}. Bug fixes applied to versions in {{{stable/}}} may also need to be merged back to {{{trunk/}}}, as appropriate (see below).
    1015
    1116An important notion is that declaring a new stable version is not the same as creating a new '''point release'''. A point release is a fixed snapshot of a stable version intended for distribution in source and/or
    12 binary form (i.e., a tarball). Whenever the PM deems appropriate (usually when the current stable version, along with previously applied patches, passes some sort of litmus test established by the PM), a '''point release,''' identified by a three-digit release number (i.e., 5.1.1) can be copied from {{{stable/}}} to {{{releases/}}}. The first two digits indicate the stable version and the last number is the '''patch level'''.
    13 Such point releases are frozen and are never changed. If a bug is found in a point release, it gets fixed in {{{stable/}}} and then a new point release created (i.e., 5.1.2), as appropriate.
     17binary form (''i.e.'', a tarball). Whenever the PM deems it appropriate (usually when the current stable version, along with previously applied patches, passes some sort of litmus test established by the PM), a '''point release,''' identified by a three-digit release number (''i.e.'', 5.1.1) can be copied from {{{stable/}}} to {{{releases/}}}. The first two digits indicate the stable version and the last number is the '''patch level'''.
     18Such point releases are frozen and are never changed. If a bug is found in a point release, it gets fixed in {{{stable/}}} and a new point release is created (''i.e.'', 5.1.2) when appropriate.
    1419
    1520To reiterate, the point releases are what we will distribute as tarballs and what we will use to create binaries because they are fixed versions that do not evolve. Therefore, if someone finds a bug in a binary or a
    16 version created from a tarball, we will be able to recreate the exact version of the code they are using by checking out the appropriate point release from SVN. There is probably no reason why anyone (besides a
    17 developer trying to fix a bug) would want to check out something from {{{releases/}}} in SVN. Because these version never change, there is no point in using SVN because {{{svn update}}} will not retrieve the bug fixes.
    18 To update, a user would have to manually check a new point release, but then the user might as well have just download the tarballs since that is easier.
     21version created from a tarball, we will be able to recreate the exact version of the code they are using by checking out the appropriate point release from the repository. There is probably no reason why anyone other than a developer trying to fix a bug would want to check out something from {{{releases/}}}. Because the point releases never change, there is no point in using subversion because {{{svn update}}} will not retrieve the bug fixes. To update, a user would have to manually check out a new point release, but then the user might just as well download the tarball since that is easier.
    1922
    2023== What to Tell Users ==
    2124
    22 It is up to each developer to determine exactly what they will recommend to their users as far as how to obtain the source code or binaries for their project. However, here are some suggested categories of users and what is the recommended way for them to get the codes in COIN-OR.
     25It is up to each developer to determine exactly what they will recommend to their users as far as how to obtain the source code or binaries for their project. However, here are some suggested categories of users and the recommended way for them to get the codes in COIN-OR.
    2326
    24  1. For casual users and those who do not want to be bothered with frequent updates or installing SVN, they should download the latest tarball (point release) in either source or binary form. To report bugs, they can use the three-digit release number of the tarball they downloaded. To get a new version containing a bug fix (or a capability they want that has been added), they will need to download a new tarball. Such users can expect the version they check out to be mature and mostly bug-free.
    25  1. For power users who want to get updates and bug fixes as soon as they are committed, but want a stable API that will not change out from under them, they should use SVN to check out the latest stable release in {{{stable/*.*}}}. Such users would have to report bugs based on the SVN version number they are using (a little more of a pain for the developers), but can get the fixes using "svn update". Such users may experience a slightly bumpier ride, as there may occasionally be incorrect patches committed to {{{stable/}}} and other minor difficulties. Most of the time, however, this code should be mature and stable.
    26  1. Developers and any really adventurous power users who want the bleeding edge can check out {{{trunk/}}}. This probably not to be encouraged for users and certainly the PM won't be expected to be too responsive to bug reports from people using the code in {{{trunk/}}}, since it is not intended to be bug-free.
     27 1. Casual users and those who do not want to be bothered with frequent updates or installing subversion should download the latest tarball (point release) in either source or binary form. To report bugs, they can use the three-digit release number of the tarball they downloaded. To get a new version containing a bug fix (or an added capability they want to use), they will need to download a new tarball. Such users can expect the version they check out to be mature and mostly bug-free.
     28 1. Power users who want to get updates and bug fixes as soon as they are committed, but want a stable API that will not change out from under them, should use subversion to check out the latest stable release in {{{stable/*.*}}}. These users would have to report bugs based on the subversion version number they are using (a little more of a pain for the developers), but can get fixes using {{{svn update}}}. These users may experience a slightly bumpier ride, as there may occasionally be incorrect patches committed to {{{stable/}}} and other minor difficulties. Most of the time, however, this code should be mature and stable.
     29 1. Developers and really adventurous power users who want the bleeding edge can check out {{{trunk/}}}. This should probably not to be encouraged for users and certainly the PM won't be expected to be too responsive to bug reports from people using the code in {{{trunk/}}}, since it is not intended to be bug-free.
    2730
    2831== Setting up your Repository ==
    2932
    30 First you want to make sure that the directories '''trunk''', '''stable''', and '''releases''' exist for your project.  An easy way to do this is to load the webpage {{{https://projects.coin-or.org/svn/YourProject}}} (such as https://projects.coin-or.org/svn/BuildTools).  This lists the base directories in your project.
     33First, make sure that the directories '''trunk/''', '''stable/''', and '''releases/''' exist for your project.  An easy way to do this is to load the webpage {{{https://projects.coin-or.org/svn/YourProject}}} (''e.g.'', https://projects.coin-or.org/svn/BuildTools).  This lists the base directories in your project.
    3134
    32 If a directory, say {{{releases}}}, does not yet exist, you can create it directly in the svn repository with the {{{svn mkdir}}} command, giving it the full URL.  For example:
     35If a directory, say, {{{releases/}}}, does not yet exist, you can create it directly in the repository with the {{{svn mkdir}}} command, giving it the full URL.  For example:
    3336
    3437{{{
     
    3942== Working with Stable Versions ==
    4043
    41 The idea of a {{{stable}}} branch is that you maintain a stable line of your code here, that can be used by a user who wants to be up-to-date with your "official" version of the code.  You start with a version that you think is good enough to be made "official".  Later, you update the code in a particular {{{stable}}} branch, for example to include bug fixes, or because you add some improvements.  Typically, when you fixed a bug reported by a user, you would fix it in the corresonding stable release, and tell the user how to get it.  When it seems to work, you should probably make a new release (see below).
     44The idea of a {{{stable}}} branch is that you maintain a stable line of your code here, that can be used by a user who wants to be up-to-date with your "official" version of the code.  You start with a version that you think is good enough to be made "official".  Later, you update the code in a particular {{{stable}}} branch, for example to include bug fixes, or because you add some improvements.  Typically, when you fix a bug reported by a user, you would fix it in the corresonding stable release, and tell the user how to get it.  When it seems to work, you should consider a new release (see below).
    4245
    43 Note: We strongly [https://projects.coin-or.org/CoinTLC/wiki/VersionsAndReleases suggest] to create a new stable branch when the user interface for your code changes in a way, so that users of your code would have to change their code in order to use the new code.  By creating a new stable branch, a user will not find any bad surprises when updating his/her local copy of a stable branch, and can instead switch to a new stable branch later, whenever (s)he is ready.
     46Note: We strongly [https://projects.coin-or.org/CoinTLC/wiki/VersionsAndReleases suggest] that you create a new stable branch when the user interface for your code changes in such a way that users of your code would have to change their code in order to use the new interface.  By creating a new stable branch, a user will not find any bad surprises when updating his/her local copy of a stable branch, and can instead switch to a new stable branch later, whenever (s)he is ready.
    4447
    4548
    4649=== Creating a New Stable Version ===
    4750
    48 You usually create a new stable branch, with a version number {{{x,y}}}, say {{{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 releases the current {{{trunk}}} version in the repository as a new stable branch.
     51You 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.
    4952
    50 A new {{{stable}}} branch with the chosen version number is create in the repository, using the {{{svn copy}}} command.  In order to create stable branch {{{2.3}}} from {{{trunk}}} you could use
     53A 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
    5154
    5255{{{
     
    6669=== Maintaining a Stable Version ===
    6770
    68 To change the content for a stable version, you work with it as usual: creating a local copy of the code in that branch, making changes there (directly by editing, or 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.
     71To 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 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.
    6972
    7073== Working With Point Releases ==
    7174
    72 The {{{release}}} directory is the place where a user can find particular, numbered releases.  The tarballs distributed on the COIN-OR website are created from those releases.  It is mandatory that by checking out a release from this place in the repository always proves the identical code, so that restore older versions is possible (for example for reproducing bugs).  In this context you need to be careful if you use {{{svn:externals}}}.  '''Once a release has been created it must not be changed!'''
     75The {{{release}}} directory is the place where a user can find particular, numbered releases.  The tarballs distributed on the COIN-OR website are created from these releases.  It is mandatory that checking out a release from this place in the repository always provides the identical code, so that it's possible to restore older versions (''e.g.'', to reproduce a bug reported by a user).  In this context you need to be careful if you use {{{svn:externals}}}.  '''Once a release has been created it must not be changed!'''
    7376
    7477=== Creating a New Point Release ===
    7578
    76 Typically, you would have a version of your code in a stable branch, say 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.
     79Typically, you would have a version of your code in a stable branch, say 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.
    7780
    78 '''If you are using [wiki:pm-svn-externals Externals]''':  Before creating the new releaes from the current version in the stable branch, '''you need to make sure that all {{{svn:externals}}}, in the version that you want to make the release, are pointing to ''releases'' of the dependencies''' so that your release can be recreated exactly at any point in time, even if the development of the dependencies progressed.  So, please make sure that all URLs in your {{{Externals}}} file are pointing to something in the {{{release}}} directory of the dependencies.  Also, make sure that the externals are indeed set according to the file content (verify with {{{svn pget svn:externals https://projects.coin-or.org/svn/YourProject/stable/2.3}}}).  (Note: If for some reason a compatible release for a dependency does not exist, you must specify the subversion revision number, using the "{{{-r}}}" flag in the {{{externals}}} definition.)  Please read [wiki:pm-svn-externals here] how to handle externals in COIN.
     81'''If you are using [wiki:pm-svn-externals Externals]''':  Before creating the new release from the current version in the stable branch, '''you need to make sure that all {{{svn:externals}}}, in the version that you want to make the release, are pointing to ''releases'' of the dependencies''' so that your release can be recreated exactly at any point in time, independent of continuing development of the dependencies.  Please make sure that all URLs in your {{{Externals}}} file are pointing to something in the {{{release}}} directory of each dependency.  Also, make sure that the {{{svn:externals}}} property is indeed set according to the file content (verify with, ''e.g.'', {{{svn pget svn:externals https://projects.coin-or.org/svn/YourProject/stable/2.3}}}).  (Note: If for some reason a compatible release for a dependency does not exist, you must specify the subversion revision number, using the "{{{-r}}}" flag in the {{{externals}}} definition.)  Please read [wiki:pm-svn-externals here] for additional explanation of how to handle externals in COIN.
    7982
    80 To create a new release, say 2.3.6, you use the {{{svn copy}}} command:
     83To create a new release, say 2.3.8, you use the {{{svn copy}}} command:
    8184
    8285{{{