Jump to: navigation, search

Difference between revisions of "WTP/Build/WTP Patches for Release 2.0.2"

< WTP‎ | Build
(Technical Notes for Release Engeneers)
 
(16 intermediate revisions by the same user not shown)
Line 11: Line 11:
 
Normally, only the "releng team" need to mess with  
 
Normally, only the "releng team" need to mess with  
 
patches. There should be very few, very special purpose, handled and produced on a  
 
patches. There should be very few, very special purpose, handled and produced on a  
case-by-case bases.  
+
case-by-case bases. But, occasionally developers will need to commit code or create patch features.  
  
For WTP 2.0.2 these fixes and related files will be released to the R2_0_2_patches stream. (If there is not already  
+
=== Branches ===
 +
 
 +
For WTP 2.0.2 these fixes and related files will be released to the <code>R2_0_2_patches</code> stream. (If there is not already  
 
such a stream for a component, it will of course have to be created, by branching from the R2_0_maintenance stream).  
 
such a stream for a component, it will of course have to be created, by branching from the R2_0_maintenance stream).  
 
For those projects at the 1.0.2 level (JSF and JPT) the same is true except it's the R1_0_2_patches stream.  
 
For those projects at the 1.0.2 level (JSF and JPT) the same is true except it's the R1_0_2_patches stream.  
Line 19: Line 21:
 
We do it this way so the main maintenance branch remains exactly like it was for release. If it is ever decided to do a 2.0.3 release, that will be the time to merge back the patches branch to the maintenance branch (if appropriate).  
 
We do it this way so the main maintenance branch remains exactly like it was for release. If it is ever decided to do a 2.0.3 release, that will be the time to merge back the patches branch to the maintenance branch (if appropriate).  
  
The map files used during a build will to be pulled from the R2_0_2_patches branch (or R1_0_2_patches). All the maps files have already been branched. So ... those are the branches to release changes to, for patch builds.  
+
The map files used during a build will to be pulled from the R2_0_2_patches branch (or R1_0_2_patches). All the maps files have already been branched. So ... those are the branches to release changes to, for patch builds.
 +
 
 +
=== Creating a Patch Feature ===
 +
 
 +
The patch feature is typically a brand new feature, and must be added to a map file (in the patches stream). Of course, if that feature already exists, and another plugin is being added to it, then it only needs the new version released to the patches branch.
 +
 
 +
These patch features must correspond to the "build component features" since those are the assumed lowest unit by which anyone consumes our features (for example, org.eclipse.wst.xml_core.feature.patch ... usually not lower, such as org.eclipse.wst.xsd.feature.patch, nor higher, such as org.eclipse.wst.feature.patch).
 +
 
 +
For consistent end-user readability, the name of the patch feature should be the same as the feature it is patching, with the word "Patches" added. For example, if original was named "WST Server Core", the patch feature should be named "WST Server Core Patches".
 +
 
 +
The end-result is
 +
* a compressed archive (zip file) on [http://download.eclipse.org/webtools/patches/ patches download site].
 +
* a feature and plugin suitable for an update site. These update jars are actually in the same directory as the zip download, but normally not visible from the download web page, but when appropriate will be copied to the official /webtools/updates site.
 +
 
 +
=== Conventions ===
 +
# Remember to increment the service field of any plugins by +1.
 +
# The version of the feature patch should "match" the feature version it corresponds to (e.g. 2.0.2.qualifier). '''But''', if subsequent versions of a patch feature are needed (to contain cumulative fixes) then the service field also needs to be incremented. This is important for those that have already applied the previous patch feature to be offered the new patch feature ... a qualifier only increment is not enough.
 +
# update the features.properties file so it lists the bug that is fixed by the patch.
 +
# update or provide a buildnotes file that lists the bug fixed by the patch.
 +
# All patches are produced in a cumulative fashion -- cumulative from the release, that is, not from any previous patches.
 +
# In the event that different patches depend on each other (that is, several must be applied together) be sure to document it in the build notes and bugzillas.
 +
 
 +
=== Reminders ===
 +
 
 +
These are tips on avoiding problems that have been hit before. They are especially problematic, since everything may appear to work fine, but then various install or update manager scenarios will not work.
 +
 
 +
# The patch feature must "requires" the feature that it is patching, '''including all 4 fields of the version''' -- the 'qualifier' field is not computed automatically during the batch build, as other qualifiers are. This won't show up as a problem just unzipping the features and plugins, but will when update manager is used.
 +
# Remember to "match" features and patch features ... that is, if a plugin is in another feature, besides the one that the patch feature 'requires', then various paths of using update manager won't work. For WTP, this is most easily accomplished by having patch features which parallel the build component features.
 +
# Be positive that the "unpack" attribute of the include plugin element is exactly the same in the original feature, and the patch feature. If it was unpacked in the original, it must be unpacked in the patch. Again, this won't often show up as a problem until much later in the process.
 +
 
 +
=== Examples/Samples ===
 +
 
 +
You can check out modules from the R2_0_2_patches branch to see existing patch features to use as a starting point.
  
 
== Technical Notes for Release Engeneers ==  
 
== Technical Notes for Release Engeneers ==  
Line 35: Line 69:
  
 
will produce <b>patch features</b> that contains a special feature to "host" the plugin. See Eclipse Help for details on patch features.  
 
will produce <b>patch features</b> that contains a special feature to "host" the plugin. See Eclipse Help for details on patch features.  
 
== Creating a Patch Feature ==
 
 
The patch feature is typically a brand new feature, and must be added to a map file (in the patches stream). Of course, if that feature already exists, and another plugin is being added to it, then it only needs the new version released to the patches branch.
 
 
These patch features must correspond to the "build component features" since those are the assumed lowest unit by which anyone consumes our features (for example, org.eclipse.wst.xml_core.feature.patch ... usually not lower, such as org.eclipse.wst.xsd.feature.patch, nor higher, such as org.eclipse.wst.feature.patch).
 
 
The end-result is
 
* a compressed archive (zip file) on http://download.eclipse.org/webtools/patches/2.0.2/
 
* a feature and plugin suitable for an update site. These update jars are actually in the same directory as the zip download, but normally not visible from the download web page, but when appropriate will be copied to the official /webtools/updates site.
 
  
 
=== Update Site ===  
 
=== Update Site ===  
Line 56: Line 80:
 
Bugs which will be made public on update site must go through PMC Review and typically some regression testing before being put on update site, since in theory any such fixes could effect other adopters/products, so they deserve extra review.
 
Bugs which will be made public on update site must go through PMC Review and typically some regression testing before being put on update site, since in theory any such fixes could effect other adopters/products, so they deserve extra review.
  
== Changes to Tests ==  
+
=== Changes to Unit Tests ===
  
 
The JUnit's are ran as-is (or, as-was) in the released version, except for "number of plugins and features" -- which have to be incremented by 1 for each plugin and patch feature -- and the versioning checks. Be sure to update the versioning reference data so the patch builds are compared against the released build.
 
The JUnit's are ran as-is (or, as-was) in the released version, except for "number of plugins and features" -- which have to be incremented by 1 for each plugin and patch feature -- and the versioning checks. Be sure to update the versioning reference data so the patch builds are compared against the released build.
  
== Getting the feature patch in to a build ==
+
=== Getting the feature patch in to a build ===
  
 
There is a special feature that drives the patch build:  
 
There is a special feature that drives the patch build:  
Line 66: Line 90:
 
  org.eclipse.wtp.patch.assembly.feature
 
  org.eclipse.wtp.patch.assembly.feature
  
The feature patch which hosts the fixed bundle needs to be added to this special feature, and all released to the releng project (maps) in the patches branch.  
+
The patch feature is added to this assembly feature by the releng team.and released to the releng project map in the patches branch.  
  
The patch build is not done automatically but must be started manually from the "force build" button on the dashboard.
+
=== Doing the build ===
  
== Conventions ==
+
The patch build is never done automatically but must be started manually from the "force build" button on the dashboard.
  
# Remember to increment the service field of any plugins by +1.
+
=== Testing the patch ===
# The version of the feature patch should "match" the feature version it corresponds to (e.g. 2.0.2.qualifier).
+
# update the features.properties file so it lists the bug that is fixed by the patch.
+
# update or provide a buildnotes_x file that lists the bug fixed by the patch.
+
  
== Reminders ==
+
If testing the zip file, it can be unzipped right on top of an existing installation.  
 
+
These are tips on avoiding problems that have been hit before. They are especially problematic, since everything may appear to work fine, but then various install or update manager scenarios will not work.
+
 
+
# The patch feature must "requires" the feature that it is patching, '''including all 4 fields of the version''' -- the 'qualifier' field is not computed automatically during the batch build, as other qualifiers are. This won't show up as a problem just unzipping the features and plugins, but will when update manager is used.
+
# Remember to "match" features and patch features ... that is, if a plugin is in another feature, besides the one that the patch feature 'requires', then various paths of using update manager won't work. For WTP, this is most easily accomplished by having patch features which parallel the build component features.
+
# Be positive that the "unpack" attribute of the include plugin element is exactly the same in the original feature, and the patch feature. If it was unpacked in the original, it must be unpacked in the patch. Again, this won't often show up as a problem until much later in the process.
+
  
== Examples/Samples ==
+
If testing from an preliminary update site, you could add the preliminary. testUpdates site as a new remote site in update manager. Even easier, see [[Using Policy Files]] for some tips on using policy files to "mimic" the normal update site, so that things like "find updates for currently installed features" will work as though coming from the final update site. As an example, the following might be a policy file for testing WTP updates from a "testUpdates" site:
  
You can check out modules from the R2_0_2_patches branch to see existing patch features to use as a starting point.  
+
<pre><nowiki>
 +
<?xml version="1.0" encoding="UTF-8"?>
 +
<update-policy>
 +
  <url-map pattern="org.eclipse.wst" url="http://download.eclipse.org/webtools/testUpdates/site.xml"/>
 +
  <url-map pattern="org.eclipse.jst" url="http://download.eclipse.org/webtools/testUpdates/site.xml"/>
 +
  <url-map pattern="org.eclipse.jpt" url="http://download.eclipse.org/webtools/testUpdates/site.xml"/>
 +
  <url-map pattern="*" url=""/>
 +
</update-policy>
 +
</nowiki></pre>
  
== Questions ==
+
'''Note:''' You may have to turn off "automatically select mirror" and get directly from the eclipse site (since the heuristic for finding mirror sites is very simple minded, and the mirroring is most likely not complete at the time of testing).
  
Feel free to ask questions on <code>wtp-releng@eclipse.org</code> if there are questions.
+
== Questions? ==
  
 +
Feel free to ask questions on <code>[mailto:wtp-releng@eclipse.org wtp-releng]</code>. And, please, update this page when you find the answer!
  
;[[WTP Build Process and Procedures | Back to WTP Build Process and Procedures]]
 
  
;[[Category:Eclipse Web Tools Platform Project]]
+
[[Category:WTP Build Related| ]]

Latest revision as of 22:33, 12 September 2008

What is an "official patch"?

Under some circumstance the WTP project may find it desirable to produce a "feature patch" which typically includes exactly one jar, that has a fix for exactly one bug. These are done for bugs which happen to be considered extremely severe or blocking -- but may not even apply to all installs, or all users. So, as a general rule, they are not to be installed by everyone ... but any bugs fixed by patches will be fixed in the next maintenance release, if there is one ... though the exact fix might be different.

While few, it is important to create and apply these in a controlled, repeatable process in order to maintain product level professional quality. For example, it is important to compile with exactly the same compiler, and exactly the same "pre-reqs" that was used to create the original build.


Technical Notes for Developers

Normally, only the "releng team" need to mess with patches. There should be very few, very special purpose, handled and produced on a case-by-case bases. But, occasionally developers will need to commit code or create patch features.

Branches

For WTP 2.0.2 these fixes and related files will be released to the R2_0_2_patches stream. (If there is not already such a stream for a component, it will of course have to be created, by branching from the R2_0_maintenance stream). For those projects at the 1.0.2 level (JSF and JPT) the same is true except it's the R1_0_2_patches stream.

We do it this way so the main maintenance branch remains exactly like it was for release. If it is ever decided to do a 2.0.3 release, that will be the time to merge back the patches branch to the maintenance branch (if appropriate).

The map files used during a build will to be pulled from the R2_0_2_patches branch (or R1_0_2_patches). All the maps files have already been branched. So ... those are the branches to release changes to, for patch builds.

Creating a Patch Feature

The patch feature is typically a brand new feature, and must be added to a map file (in the patches stream). Of course, if that feature already exists, and another plugin is being added to it, then it only needs the new version released to the patches branch.

These patch features must correspond to the "build component features" since those are the assumed lowest unit by which anyone consumes our features (for example, org.eclipse.wst.xml_core.feature.patch ... usually not lower, such as org.eclipse.wst.xsd.feature.patch, nor higher, such as org.eclipse.wst.feature.patch).

For consistent end-user readability, the name of the patch feature should be the same as the feature it is patching, with the word "Patches" added. For example, if original was named "WST Server Core", the patch feature should be named "WST Server Core Patches".

The end-result is

  • a compressed archive (zip file) on patches download site.
  • a feature and plugin suitable for an update site. These update jars are actually in the same directory as the zip download, but normally not visible from the download web page, but when appropriate will be copied to the official /webtools/updates site.

Conventions

  1. Remember to increment the service field of any plugins by +1.
  2. The version of the feature patch should "match" the feature version it corresponds to (e.g. 2.0.2.qualifier). But, if subsequent versions of a patch feature are needed (to contain cumulative fixes) then the service field also needs to be incremented. This is important for those that have already applied the previous patch feature to be offered the new patch feature ... a qualifier only increment is not enough.
  3. update the features.properties file so it lists the bug that is fixed by the patch.
  4. update or provide a buildnotes file that lists the bug fixed by the patch.
  5. All patches are produced in a cumulative fashion -- cumulative from the release, that is, not from any previous patches.
  6. In the event that different patches depend on each other (that is, several must be applied together) be sure to document it in the build notes and bugzillas.

Reminders

These are tips on avoiding problems that have been hit before. They are especially problematic, since everything may appear to work fine, but then various install or update manager scenarios will not work.

  1. The patch feature must "requires" the feature that it is patching, including all 4 fields of the version -- the 'qualifier' field is not computed automatically during the batch build, as other qualifiers are. This won't show up as a problem just unzipping the features and plugins, but will when update manager is used.
  2. Remember to "match" features and patch features ... that is, if a plugin is in another feature, besides the one that the patch feature 'requires', then various paths of using update manager won't work. For WTP, this is most easily accomplished by having patch features which parallel the build component features.
  3. Be positive that the "unpack" attribute of the include plugin element is exactly the same in the original feature, and the patch feature. If it was unpacked in the original, it must be unpacked in the patch. Again, this won't often show up as a problem until much later in the process.

Examples/Samples

You can check out modules from the R2_0_2_patches branch to see existing patch features to use as a starting point.

Technical Notes for Release Engeneers

There is a special component

wtp-patches2

in the releng.wtpbuilder cvs project that along with special distribution targets

patches2.build
patches2.site
patches2.upload
patches2.tests

will produce patch features that contains a special feature to "host" the plugin. See Eclipse Help for details on patch features.

Update Site

If it is desired to be generally available to all WTP users (by them using the Eclipse Update Manager), then the update features and plugins have to be copied to the downloads/webtools/updates directory. If update is done, remember to

  1. update the site.xml
  2. recreate the digest
  3. run pack200

Bugs which will be made public on update site must go through PMC Review and typically some regression testing before being put on update site, since in theory any such fixes could effect other adopters/products, so they deserve extra review.

Changes to Unit Tests

The JUnit's are ran as-is (or, as-was) in the released version, except for "number of plugins and features" -- which have to be incremented by 1 for each plugin and patch feature -- and the versioning checks. Be sure to update the versioning reference data so the patch builds are compared against the released build.

Getting the feature patch in to a build

There is a special feature that drives the patch build:

org.eclipse.wtp.patch.assembly.feature

The patch feature is added to this assembly feature by the releng team.and released to the releng project map in the patches branch.

Doing the build

The patch build is never done automatically but must be started manually from the "force build" button on the dashboard.

Testing the patch

If testing the zip file, it can be unzipped right on top of an existing installation.

If testing from an preliminary update site, you could add the preliminary. testUpdates site as a new remote site in update manager. Even easier, see Using Policy Files for some tips on using policy files to "mimic" the normal update site, so that things like "find updates for currently installed features" will work as though coming from the final update site. As an example, the following might be a policy file for testing WTP updates from a "testUpdates" site:

<?xml version="1.0" encoding="UTF-8"?>
<update-policy>
  <url-map pattern="org.eclipse.wst" url="http://download.eclipse.org/webtools/testUpdates/site.xml"/>
  <url-map pattern="org.eclipse.jst" url="http://download.eclipse.org/webtools/testUpdates/site.xml"/>
  <url-map pattern="org.eclipse.jpt" url="http://download.eclipse.org/webtools/testUpdates/site.xml"/>
  <url-map pattern="*" url=""/>
</update-policy>

Note: You may have to turn off "automatically select mirror" and get directly from the eclipse site (since the heuristic for finding mirror sites is very simple minded, and the mirroring is most likely not complete at the time of testing).

Questions?

Feel free to ask questions on wtp-releng. And, please, update this page when you find the answer!