| 3 | | This page describes how the [https://projects.coin-or.org/CoinTLC/wiki/VersionsAndReleases policy for releases suggested by COIN] can be maintianed with subversion. 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. |
| | 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. |
| | 4 | |
| | 5 | == Overview == |
| | 6 | |
| | 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. |
| | 8 | |
| | 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). |
| | 10 | |
| | 11 | An 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. |
| | 14 | |
| | 15 | To 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. |
| | 19 | |
| | 20 | == What to Tell Users == |
| | 21 | |
| | 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. |
| | 23 | |
| | 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 | |
| | 26 | 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. |
| | 27 | |
| | 28 | 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. |
