Orbit/Promotion, Release, and Retention Policies
Orbit itself does not have releases, per se, since the 3rd party jars that are bundled have already been released. But, we will still use the Eclipse Simultaneous Release rhythm to set deadlines for ourselves and promote and retain bundles.
An Orbit milestone date will be considered the same as the base Eclipse platform milestone date, since for anyone in a Simultaneous Release to use an Orbit Bundle, it would have to be ready (and final) at least a week or two before their milestone deadline.
Our continuous builds produce builds in the committers area. Their purpose is for the committers to have something to see or download and confirm all is as they expect it to be. These builds are often short lived and can be deleted without notice.
Weekly Declared Builds
Once per week, currently by Monday noon (Eastern time), the latest continuous build will be copied over to the downloads area. These are similar or analogous to weekly Integration Builds, and will be retained in place until the Milestone release.
Milestones and Recommended ("Final") Bundles Area
Once per milestone, (roughly simultaneous with the platform's milestone), the most recent Weekly Build will be declared the milestone build, and the earlier weekly builds deleted. The bundles from that milestone build, that committers judge as finished, will be copied to the downloads directory. This is to be considered the final home for the bundles added to Orbit. That is, these final bundles should not normally ever have to be re-built. In case they do, they will have different qualifiers in the fourth field. In this case, the older qualified versions will be kept for approximately 1 milestone period, to give consumers a chance to update any build scripts, without suddenly breaking their builds. We anticipate it being very rare to have to change a bundle after being moved to the final bundles area. Each Milestone Build will be retained until an Eclipse Simultaneous Release and then all deleted.
Issue: This permanent home for the bundles will not have "timestamp" directories, so it is easier to specify a permanent URL, write scripts, etc. The issue is that while these can currently be easily obtained one by one, but we have not yet decided what, if any, archive or update files to create for these final bundles.
It was decided in June 12, 2007 status meeting to (still) have dated directories for the "final" builds, and was decided to call them "R-builds", which may sound like "Released", but is "Recommended" for Orbit, since Orbit does not have Releases in the Eclipse sense of that word. The bundles in "Recommended" builds will only be changed (re-created) if there are serious bugs found with them. Even then, any "Recommended" builds will be retained long term, such as for 2 years or so, so build scripts will not break and be recreatable. It is expected that Recommended builds will be produced once or twice per year. Certainly for any yearly trains, but perhaps at other times, since not all projects always have to release only in June.
Milestones and Recommended Build "Notes" Column
On the main download page is a column labeled "Notes". While technically any "note" can be put in there, at a minimum for every "R-build" and "S-build" a note should be added for which Simultaneous Release the build was first recommended for.
Adding notes to the file is a matter of "hand editing" the "notes.php" file on the download server. It is under
and new entries are added, by adding new array entries, which are indexed by the "display name" of the download. For example, if existing file started with the following:
<?php $notes = array(); $notes["R20140525021250"]="Luna, Luna SR1"; $notes["R20140114142710"]="Kepler SR2";
then the next R-build was for Mars, and named R201506011000, and no new R-build for Luna SR2, that file would end up starting with:
<?php $notes = array(); $notes["R20150601100000"]="Mars"; $notes["R20140525021250"]="Luna, Luna SR1, Luna SR2"; $notes["R20140114142710"]="Kepler SR2";
This file, and others are stored in module org.eclipse.orbit.releng.downloadsites but there is no automatic update or anything from those files, to download server.
The Orbit milestones dates will be a -1 delivery in Simultaneous Releases, to allow all projects to pick up prereqs (even the Platform, the 0 delivery).
Milestone builds will be retained until the Recommend build is produced.
Recommended builds will be kept forever, the most recent one(s) on 'download.eclipse.org' but older ones will be moved to 'archive.eclipse.org' (which is not mirrored) The old, archived builds should rarely be needed, used only be used if someone needed to re-create some old build which was based upon it, such as for long term maintenance.
Bundle Retention in active builds
It is our Orbit project's policy that once a bundle is delivered in an R-build, it will be retained forever in that R-build (or its repository). But, in active (or, current) builds, to be used for future releases, we may remove old versions of bundles according to the following guidelines.
- Normally up to 3 versions of a bundle can be in active builds. But after that, older bundle versions should be removed, since they would presumably never be used by other, active Eclipse projects. If projects or adopters still needed some older version, say for maintenance builds, they can get them from the older R-build repositories where they were last provided.
- If committers are relatively sure that some older bundle versions are no longer being actively used by current Eclipse projects, they can be removed from active builds. This might leave only one or two of the most recent versions in active builds ... normally only two at most would truly be needed, and sometimes only one (and sometimes maybe zero, in some exceptional cases). Committers must use good judgment here. If there is any question or doubt about removing it, then it should not be removed. Committers can ask on orbit-dev (info, mail) or cross-project-issues-dev (info, mail) for others' opinions or advise.
- There is no need to be overly aggressive about removing things, but we do need to be respectful of using our computing resources wisely. Other Eclipse project and adopters share in this responsibility ... and in this case, that means they need to let us know if they have some special case and need some old version even in active builds. This might be required for example if there is some subtle changes in signing, license files, etc., that must be obtained. Simply open a bugzilla with what is needed and why.
- Any removal of an older version will be done by M6 of the current yearly release cycle (M6 is normally considered the "API freeze" date). This allows exceptions or mistakes to be corrected in time for the yearly release with no danger of "last minute" breakage. And M6 is the latest possible time ... committers should make an effort to do much earlier in a yearly release cycle.
- [update 02/15/2012] There are cases where bundles should be removed more aggressively. One case might be when the original authors of a third party package recommend it be removed due to serious bugs or limitations for which later releases fix. See bug 371396 for an example of a case where this was discussed. Another case we might be more aggressive in removing bundles from active builds is if there are known security issues with some bundle. Keep in mind, this all still just refers to "active builds", once a bundle is in an R-build, it will be there forever, except in the most serious of problems, such as newly discovered IP issues, or extremely dangerous security flaws). These aggressive removals, especially if they occur late, such as after M6, should be well communicated such as on cross-project list.
- Older versions will stay in CVS, as they are, forever. That is, the older versions are simply removed from the map and build-feature file ... never from CVS nor existing R-build repositories. This is partially so someone could find them if needed to investigate something, but also so we can easily add them back to active builds if needed.
- Removals should be documented in bugzilla ... similar to how additions are documented.
- Mechanics: When a bundle is to be removed from active builds, the following steps should be followed:
- have a bugzilla entry that mentions what is being removed, when, and ideally states the "last good R-build" that contains the old version.
- remove bundle entry from the feature.xml file (and release it for a build, at some point, when ready)
- remove the bundle entry from the bundles.map file.
- leave the entry in the IP Log file, but add a note that says something similar to "No longer in active builds since this version is no longer current. If required, please get from an older R-build repository, CVS, or open a bugzilla if needs to be re-instantiated in active builds".
- ideally should update the original "Orbit CQ" to simply mention that version is no longer actively built by Orbit. This is just to help cross-reference information, in case someone is looking for that bundle. Orbit does, technically, still "distributes" it, since it is available in old repositories ... it is just an informational message.
- update the orbit.psf file if desired.
- There are some other files that may need updating ... but they usually will not, but can check these if there seems to be some problem:
- the list of exclude-from-pack-conditioning list in buildutilities.xml (in org.eclipse.orbit.releng.builder project),
- the config.properties in layout tests (in org.eclipse.orbit.releng.tests project).
Old Comments from Martin Oberhuber and Kim Moir:Moved to the "discussion" tab