Jump to: navigation, search

Difference between revisions of "Debug/DebugRelEng"

(Committing the Release)
(Releasing Bundles)
 
(5 intermediate revisions by the same user not shown)
Line 9: Line 9:
 
#you have commit rights to all of the [[#Bundle Needed To Release|required bundles]]
 
#you have commit rights to all of the [[#Bundle Needed To Release|required bundles]]
 
#you have no pending changes in your RelEng workspace
 
#you have no pending changes in your RelEng workspace
#the RelEng tools are [[#Installing The RelEng Tools|installed]] in your host Eclipse
+
#you have EGit and/or Git on the command line
 
+
There is also another pretty good write-up on how to release bundles on the [http://eclipsesource.com/blogs/tag/releng/ EclipseSource blog]
+
  
 
== Bundles Needed To Release ==
 
== Bundles Needed To Release ==
  
The bundles that must be released each week can be found in the [http://wiki.eclipse.org/images/c/c4/Debug.psf project set file].
+
Now that Platform / JDT debug in is Git, it is much easier to get the required bundles. You simply have to check out the following two repos:
 +
#[http://git.eclipse.org/c/jdt/eclipse.jdt.debug.git/ JDT Debug]
 +
#[http://git.eclipse.org/c/platform/eclipse.platform.debug.git/ Platform Debug]
  
They include:
+
There is an additional required bundle that contains all of the map files that must be updated, which is: <code>org.eclipse.releng</code> and can be
<pre>
+
found in the [http://git.eclipse.org/c/platform/eclipse.platform.releng.maps.git/ RelEng maps] Git repo.
org.eclipse.core.variables
+
org.eclipse.debug.core
+
org.eclipse.debug.examples.core
+
org.eclipse.debug.examples.ui
+
org.eclipse.debug.tests
+
org.eclipse.debug.ui
+
org.eclipse.jdt.debug
+
org.eclipse.jdt.debug.tests
+
org.eclipse.jdt.debug.ui
+
org.eclipse.jdt.launching
+
org.eclipse.jdt.launching.macosx
+
org.eclipse.jdt.launching.ui.macosx
+
org.eclipse.ui.console
+
</pre>
+
 
+
There is an additional required bundle that contains all of the map files that must be updated, which is: <code>org.eclipse.releng</code>  
+
 
+
This bundle is available in the default Eclipse CVS repository:
+
<pre>
+
dev.eclipse.org/cvsroot/eclipse/org.eclipse.releng
+
</pre>
+
 
+
== The RelEng Tools ==
+
 
+
The key to being able to release all of the bundle is to use the Eclipse RelEng tools.
+
 
+
These tools do not come installed in Eclipse by default, but can easily be installed from any of the release update sites. For example the [http://download.eclipse.org/releases/indigo Indigo update site].
+
 
+
Alternatively download it as an archive.  The link to the archive at the bottom of any build page.  Then select Help > Install New Software > Add Site > Archive.  After adding archive, select it and make sure to uncheck "Group items by category".
+
 
+
To confirm that the RelEng tools have successfully been installed simply select a debug project in your workspace, right-click, select the <code>Team</code> fly-out menu and look for the <code>Release...</code> command. If the <code>Release...</code> command is present the tools are installed and ready to go.
+
  
 
== Releasing Bundles ==
 
== Releasing Bundles ==
  
With the RelEng tools installed and working, <em>and</em> all of the [[#Bundles Needed To Release|required projects]] selected you must start the <code>Release</code> wizard by doing one of the following:
+
=== Using EGit ===
#right-clicking on the selected projects and using the '''Team > Release...''' command
+
#click the '''Release Projects''' toolbar button in the main toolbar. This option is not available by default, so to use it you first must go to '''Window > Customize Perspective''' and enable the command group for '''RelEng Tools'''
+
  
=== Map Files ===
+
With the EGit tools installed and working, <em>and</em> all of the [[#Bundles Needed To Release|required Git repos]] up to date; you must start the '''Tag..''' wizard <em>for each repo</em> by right-clicking on one of the projects from the repo and using the '''Team > Advanced > Tag...''' command.
  
If you have used the wizard before and told it to not ask for a map project anymore, you will not see the following page of the wizard. If this is your first time, the first page of the <code>Release</code> wizard asks you to select the map file project.
+
In the next step we create the new tag using the '''Tag''' wizard, which looks like the following:
<gallery widths="280px" heights="290px" perrow="1">
+
Image:Debug_map_selection.png|The map project selection page
+
</gallery>
+
 
+
For the debug projects this will always be <code>org.eclipse.releng</code>. If at some point you have told the wizard to always use a given project, and would like to choose another - i.e. once again show you the first page of the wizard above - you can enable the option to always ask for map projects on the '''Team > Releng Map Project Selection''' preference page within Eclipse.
+
 
+
With the map file project selected, the next step allows you to select all of the projects you want to release. You can see in the following screen shot that all of the projects we selected in the workspace are initially selected and they presented grouped under the map file they belong to.
+
  
 
<gallery widths="280px" heights="290px" perrow="1">
 
<gallery widths="280px" heights="290px" perrow="1">
Image:Debug_project_selection.png|The project selection page
+
Image:Tag_wizard.png|The tag wizard
 
</gallery>
 
</gallery>
  
It is expected that all of the debug projects appear under the <code>jdtdebug</code> map and that <code>org.eclipse.core.variables</code> appears under the <code>core-variables</code> map.
+
In the '''Tag name''' field, enter the new tag - making sure to follow the rules outlined in the [[#Choosing_tags]] section - and add a comment why you are adding a new tag. After pressing Ok in the tag wizard, we have successfully added the new tag to our local repo. Now we have to make sure that the new tag makes it to the remote repo. To do this we want to use the '''Team > Remote > Push...''' command, not the '''Team > Push to Upstream''' command. The reason we want to use the latter command is that we need to have finite control over only pushing the one new tag, and not pushing all of the tags that might be in our local repo.
  
There is a very important preference on this page, it is the ''Release only projects that have changed since the last release'' preference. When this option is checked the wizard will consult CVS to find what change have been made to the projects since the last time the bundles were released. If the wizard finds no changes the bundles will not be released. If you want to tag all of the bundles regardless of changes since the last release, you must un-check this option. Doing so will also cause the wizard to skip past the '''Project Changes''' and the '''Notes for Build Changes''' pages mentioned below.
+
To ensure we only get the tag we want, in the '''Push...''' wizard we enter the name of the tag in the '''Source ref''' field and hit '''Ctrl+Space''' (content-assist) to fill in the correct value in the '''Destination ref''' field like the following:
 
+
The last step in choosing what and where to release is to view the changes that have been found since the last time the bundles were released. If, however, you un-checked the ''only released changed projects...'' option from above you will not see this page.
+
  
 
<gallery widths="280px" heights="290px" perrow="1">
 
<gallery widths="280px" heights="290px" perrow="1">
Image:Debug_project_changes.png|The project changes page
+
Image:Push_tag_picking.png|The push wizard source and destination ref fields
 
</gallery>
 
</gallery>
  
This page also contains an important, but often overlooked option - the ''Generate Build Notes'' option. This option will consult CVS and collect all of the commit comments for any of the project changes it shows you on this page. The advantage of using this is so you can easily send the status email once the bundles are released. More on this in the next section.
+
After the '''Source ref''' and '''Destination ref''' values are entered, hit the '''Add Spec''' button and then '''Next'''. After the test push completes successfully you can press '''Finish''' to push the new tag to the remote repo. At this point it is good to go to the repo web site and double-check to makes sure the push was successful.
  
=== Build Notes ===
+
With the new tag added to the repo, we have to update the map file with the new tag. For platform / JDT debug the map file to be edited is in the following workspace location: <code>org.eclipse.releng/maps/jdtdebug.map</code>.
  
First thing to note is, if you un-checked the ''only released changed projects...'' option mentioned above, you will not be presented with this page. If you left that option checked and also left the ''Generate Build Notes'' option mentioned above checked, you will see the '''Notes For Build Changes''' page.
+
There are two ways we can update the map:
 +
*we can change the tag for each entry to be the new tag
 +
*we can check the repo webpage(s) to see if there have been any commits since the last tagging and only update the projects that have changed
  
<gallery widths="280px" heights="290px" perrow="1">
+
Once the map file is updated, commit it to your local repo and then push the changes to the remote repo. Again, it is good to double-check on the repo web pae to ensure the push was successful.
Image:Debug_build_notes.png|The notes for build changes page
+
</gallery>
+
  
This page allows you to automatically update a build notes file - which we do not use in debug - and presents you with a nicely formatted text blurb of all of the commit comments for the changes that will be released. At this point you will want to copy that text as it is used in the status email that <em>must</em> be sent to the debug mailing lists (platform-debug-dev@eclipse.org and jdt-debug-dev@eclipse.org )after the release is complete. The reason for this is so that the other debug committers (and any other interested parties) know what fixes / enhancements will be available in the next I-build. Also it lets the other committers know that the bundles have been released.
+
=== Using the command line ===
  
=== Choosing Tags ===
+
If you have Git available form the command line you can also release to the build.
Other than making sure you are releasing all of the correct changes, selecting the ''right'' tag is probably the most important step in the process. Typically, using the drop-down and selecting the first selection will be fine, but there are exceptions.
+
  
Exceptions:
+
The first step is to create a new tag for each repo by doing the following:
#if you have to release the same bundle more than once on the same day you '''must''' add a postfix to the tag and '''never''' select the option to move the tag if it exists. For example say you released the bundles under the tag <code>v20110511</code> at noon, but then later in the day a new fix was added and you had to re-tag. In this case the default choice would again be <code>v20110511</code>, but you already used it. In this case the de-facto standard debug uses is to append a letter to the tag as needed: <code>v20110511a</code>, <code>v20110511b</code>, etc, etc for as many times as you release the bundles in the same day.
+
#change directory to the repo you wish to tag
#if you need to tag the bundles for a particular release for a non-HEAD branch. In this case it is the de-facto standard for debug to add a postfix about the branch to the tag name. For example if you had to release the bundles in the <code>R3_6_maintenance</code> branch you would use something like: <code>v20110511_r362</code>.
+
#run <pre>$ git tag -a <your_new_tag_name> -m <your_new_tag_comment></pre>
 +
#push the new tag to the remote repo <pre>$ git push master <your_new_tag_name></pre>
  
 +
With the new tag added to the repo, we have to update the map file with the new tag. For platform / JDT debug the map file to be edited is in the following location: <code><path_to_the_eclipse.platform.releng.maps_git_repo>org.eclipse.releng/maps/jdtdebug.map</code>.
  
<gallery widths="280px" heights="290px" perrow="1">
+
There are two ways we can update the map:
Image:Debug_tag_selection.png|The release tag page
+
*we can change the tag for each entry to be the new tag
</gallery>
+
*we can check the repo webpage(s) to see if there have been any commits since the last tagging and only update the projects that have changed
  
The absolutely most important part of choosing tags is to '''never EVER''' select the option to move a tag if it already exists. This can cause all kinds of problems in the Eclipse build process.  
+
Once the map file is updated, commit it to your local repo and then push the changes to the remote repo. Again, it is good to double-check on the repo web page to ensure the push was successful.
  
 +
=== Choosing Tags ===
 +
Other than making sure you are releasing all of the correct changes, selecting the ''right'' tag is probably the most important step in the process. Typically, we create tags with the following format:
 +
<pre>v<year><month><day>-<hour><minute></pre>
  
After you have selected the tag you want to use, the next page allows you to view the changes that will be made to the map files.
+
There are exceptions to this general format as outlined below.
  
<gallery widths="280px" heights="290px" perrow="1">
+
Exceptions:
Image:Debug_map_file_changes.png|The map file changes page
+
#if you have to release the same bundle more than once on the same day you '''must''' make sure you add the time postfix to the tag. For example, say you released the bundles under the tag <code>v20110511</code> at noon, but then later in the day a new fix was added and you had to re-tag. If you already use the standard format and always include the time, everything will be fine, otherwise you have to ensure the time postfix is present - i.e. you had to re-release at 12:30 on the same day, the new tag format would be: <code>v20110511-1230</code>.
</gallery>
+
#if you need to tag the bundles for a particular release for a non-MASTER branch. In this case it is the de-facto standard for debug to add a postfix about the branch to the tag name. For example if you had to release the bundles in the <code>R3_7_maintenance</code> branch you would use something like: <code>v20110511-1200_r372</code>.
 
+
=== Committing the Release ===
+
 
+
This one is easy. You have to enter a commit comment and press the finish button to perform the release.  
+
 
+
<gallery widths="280px" heights="290px" perrow="1">
+
Image:Debug_commit_comment.png‎|The commit comment page
+
</gallery>
+

Latest revision as of 14:31, 15 November 2011

Platform Debug
Website
Download
Community
Mailing ListForumsIRC
Bugzilla
Open
Help Wanted
Bug Day
Contribute
Browse Source
JDT Debug
Website
Download
Community
Mailing ListForumsIRC
Bugzilla
Open
Help Wanted
Bug Day
Contribute
Browse Source

Introduction

Being part of the Eclipse platform requires that for each I-build in the Eclipse build schedule all of the debug plugins must be released to the build.

This process only has a few requirements:

  1. you have all of the required bundles
  2. you have commit rights to all of the required bundles
  3. you have no pending changes in your RelEng workspace
  4. you have EGit and/or Git on the command line

Bundles Needed To Release

Now that Platform / JDT debug in is Git, it is much easier to get the required bundles. You simply have to check out the following two repos:

  1. JDT Debug
  2. Platform Debug

There is an additional required bundle that contains all of the map files that must be updated, which is: org.eclipse.releng and can be found in the RelEng maps Git repo.

Releasing Bundles

Using EGit

With the EGit tools installed and working, and all of the required Git repos up to date; you must start the Tag.. wizard for each repo by right-clicking on one of the projects from the repo and using the Team > Advanced > Tag... command.

In the next step we create the new tag using the Tag wizard, which looks like the following:

In the Tag name field, enter the new tag - making sure to follow the rules outlined in the #Choosing_tags section - and add a comment why you are adding a new tag. After pressing Ok in the tag wizard, we have successfully added the new tag to our local repo. Now we have to make sure that the new tag makes it to the remote repo. To do this we want to use the Team > Remote > Push... command, not the Team > Push to Upstream command. The reason we want to use the latter command is that we need to have finite control over only pushing the one new tag, and not pushing all of the tags that might be in our local repo.

To ensure we only get the tag we want, in the Push... wizard we enter the name of the tag in the Source ref field and hit Ctrl+Space (content-assist) to fill in the correct value in the Destination ref field like the following:

After the Source ref and Destination ref values are entered, hit the Add Spec button and then Next. After the test push completes successfully you can press Finish to push the new tag to the remote repo. At this point it is good to go to the repo web site and double-check to makes sure the push was successful.

With the new tag added to the repo, we have to update the map file with the new tag. For platform / JDT debug the map file to be edited is in the following workspace location: org.eclipse.releng/maps/jdtdebug.map.

There are two ways we can update the map:

  • we can change the tag for each entry to be the new tag
  • we can check the repo webpage(s) to see if there have been any commits since the last tagging and only update the projects that have changed

Once the map file is updated, commit it to your local repo and then push the changes to the remote repo. Again, it is good to double-check on the repo web pae to ensure the push was successful.

Using the command line

If you have Git available form the command line you can also release to the build.

The first step is to create a new tag for each repo by doing the following:

  1. change directory to the repo you wish to tag
  2. run
    $ git tag -a <your_new_tag_name> -m <your_new_tag_comment>
  3. push the new tag to the remote repo
    $ git push master <your_new_tag_name>

With the new tag added to the repo, we have to update the map file with the new tag. For platform / JDT debug the map file to be edited is in the following location: <path_to_the_eclipse.platform.releng.maps_git_repo>org.eclipse.releng/maps/jdtdebug.map.

There are two ways we can update the map:

  • we can change the tag for each entry to be the new tag
  • we can check the repo webpage(s) to see if there have been any commits since the last tagging and only update the projects that have changed

Once the map file is updated, commit it to your local repo and then push the changes to the remote repo. Again, it is good to double-check on the repo web page to ensure the push was successful.

Choosing Tags

Other than making sure you are releasing all of the correct changes, selecting the right tag is probably the most important step in the process. Typically, we create tags with the following format:

v<year><month><day>-<hour><minute>

There are exceptions to this general format as outlined below.

Exceptions:

  1. if you have to release the same bundle more than once on the same day you must make sure you add the time postfix to the tag. For example, say you released the bundles under the tag v20110511 at noon, but then later in the day a new fix was added and you had to re-tag. If you already use the standard format and always include the time, everything will be fine, otherwise you have to ensure the time postfix is present - i.e. you had to re-release at 12:30 on the same day, the new tag format would be: v20110511-1230.
  2. if you need to tag the bundles for a particular release for a non-MASTER branch. In this case it is the de-facto standard for debug to add a postfix about the branch to the tag name. For example if you had to release the bundles in the R3_7_maintenance branch you would use something like: v20110511-1200_r372.