Revision as of 11:15, 28 January 2011

The Orion builds follow many of the same practices used by the Eclipse Platform Project. The builds are based on PDE/Build and run automatically on build.eclipse.org via cron job.

There are two types of builds: Nightly and Integration. Nightly ("N") builds run every night and are built with the latest on the HEAD stream in the repository. Integration ("I") builds run once a week and build specific versions of the code as tagged in the repository.

Contributing changes to the build

Contributing to a nightly build is easy, just commit your code to the Orion repository and it will be included in the nightly build.

Contributing to an Integration build involves tagging your changes and modifying the map files. Map files are used to specify where a project is located in the repository and what version of that project to use in the build. The map files are located in the org.eclipse.orion.releng project.

Setting up your workspace

1. See Orion/Getting the source for instructions on how to set up your workspace to work with Orion source code.
2. Import 'org.eclipse.orion.releng' into your workspace. It is located in the org.eclipse.orion.server.git repository under the releng folder.

Contributing your changes

Once you have made code changes, you can contribute them to the Integration build as follows:

• Commit your changes to the local repository and push them to the master

git commit -a -m "fix lots of bugs"                   #commits all changes
git push                                              #push local commits to the master

• Tag the git repository and push the tag to the master
  

git tag v20110127-1300
git push --tags

Tag Format

The tag specified for a project in the map file will be used as the version qualifier for that bundle (or feature) in the build. It is important for this tag to follow a standard format and that we use the same time zone so that the bundle version increments properly over time.

The standard format to use is vYYYYMMDD-HHMM (HH is in 24 hour form. By convention we use EST time zone, the time zone for Ottawa.)

Unlike CVS, in git tags apply to the entire repository. It is important to include the time in the tag instead of just the day because if someone else tags another project in the same repository, we don't want the original tag to get moved, which would change which changes make it into the build.

Update the Map File

Open the map file containing the entry for your project. This is usually org.eclipse.orion.releng/maps/orion.map.

• Find the entry for the project containing your changes and update it to match your new tag.

As an example, the entry for org.elipse.orion.client.core looks like this:

plugin@org.eclipse.orion.client.core=GIT,tag=v20110127-1300,repo=dev.eclipse.org:/gitroot/e4/org.eclipse.orion.client.git,path=bundles/org.eclipse.orion.client.core
                                         ^^^^^^^^^^^^^^^^^^

• Commit your change to the git repo and push it back to the master

git add releng/org.eclipse.orion.releng/maps/orion.map   #in the server repo, add this change to be committed
git commit -m "bug ####"                                 #commit the change
git push                                                 #push the change to the master

Advanced Tagging

For lots of good reasons, a project's tag in the map file should generally only updated if that project contains changes. If a single person is going to tag multiple projects and does not know which of those projects actually contain changes, then some tooling is required.

There is currently no equivalent of the cvs releng tool used by the Eclipse Platform team to manage map files. (See bug 328745). There is a shell script written for e4, see the E4/Git#Submitting_for_a_build page for details.

FAQ

How often do I need to tag?

You don't need to tag every commit. Changes only need to be tagged when a build is scheduled. I-builds are scheduled to run Monday Night/early Tuesday morning, changes should be tagged and map files updated at the end of day Monday. For high-traffic projects that many people are working on, it is good to coordinate who will tag those projects. For low-traffic bundles that rarely get changed, sometimes it is good to tag right away when a change is made so that you don't forget later.

Do I need to follow the tag format above?

The tags in the map file get used as the final segment in the bundle's version when it gets built. If the tag does not conform to OSGi rules about allowed characters, then the build will fail. (Allowed characters are a-z,A-Z,0-9,'-' and '_').

Version numbers are expected to increase over time, if a version number decreases it can cause problems for people consuming that bundle. This is why we use a date/time-stamp format.

Can I reuse the same tag again if I only make a small change?

Tags should not be reused for a few reasons:

• In git, tags apply to the entire repository, if you move a tag by reusing it, you could be changing what is being included in other projects contained in that same repository
• Updating to changes: If a tag is moved then we can end up with new content in a bundle but still have the same version. Provisioning systems like p2 won't realize the bundle is changed because the version is still the same.
• Tracking bugs: if a tag was moved we could end up with subsequent builds containing different content for a bundle but the version on that bundle staying the same. This is a problem for bug reporting because you don't know which content is being used.
• Builds are expected to be reproducible, we can't go back later and rebuild specific versions if the tags have been moved around.