Difference between revisions of "Indigo/Contributing to Indigo Build"

From Eclipsepedia

Jump to: navigation, search
(New page: Previous instructions are at Contributing to Helios Build ''Disclaimer: the following hints have been collected by a newbie to this process, vali...)
 
(added a few tips, and changed formatting a little)
Line 1: Line 1:
Previous instructions are at [[Helios/Contributing_to_Helios_Build | Contributing to Helios Build]]
+
This instructions outline how to contribute to the Indigo aggregation build for the common repository. They also may be useful for those updating contributions for Helios maintenance releases, though Helios not covered explicitly (the basics are the same).
  
''Disclaimer: the following hints have been collected by a newbie to this process, validation required.''
+
If at anytime, there are questions, issues or problems, don't hesitate to ask on cross-project mailing list, or open a cross-project bug.  
  
For Indigo build aggregation has moved to using <code>.b3aggrcon</code> files. On this topic read:
+
== Checkout CVS indigo.build project ==
* [http://dev.eclipse.org/mhonarc/lists/cross-project-issues-dev/msg04575.html [cross-project-issues-dev]] Ready for Helios SR1 builds? .... and file format change?
+
* {{bug|312645}} -  Consider moving to b3 aggregator for Helios
+
  
 +
Check out project <code>org.eclipse.indigo.build</code> from <code>dev.eclipse.org:/cvsroot/callisto</code>.  If you do not have write access to this repository location, contact the [mailto:webmaster@eclipse.org webmaster], explaining which project you are working with, and CC the Planning Council chairperson (currently david_williams@us.ibm.com).
  
'''CVS location:'''
+
== Install the b3 Aggregator ==
Check out project <code>org.eclipse.indigo.build</code> from <code>dev.eclipse.org:/cvsroot/callisto</code>.  If you do not have write access to this repository location, contact the [mailto:webmaster@eclipse.org webmaster].
+
  
'''"Old" projects:'''
+
* Follow instructions to install the [[Eclipse_b3/aggregator/manual | b3 Aggregator editor]] (and checkout the above mentioned CVS project). Tip: many find it preferable to have a separate workspace for this aggregation work, as it works with many p2 repositories and can add a lot of background processing as it works with all those repositories.  
For projects that already participated in Helios all build files have been migrated.
+
  
'''New project:'''
+
* Open the file <code>indigo.b3aggr</code> using the '''Aggregator Model Editor'''
Projects joining the simultaneous release train at this stage need to do:
+
* Follow instructions to install the [[Eclipse_b3/aggregator/manual | b3 Aggregator editor]]
+
* Checkout the above mentioned CVS project
+
* Open file <code>indigo.b3aggr</code> using the '''Aggregator Model Editor'''
+
 
: ''Note: at this stage metadata from a lot of repository will be downloaded, the UI may become unresponsive, but after some minutes it should return to a working state, see {{bug|323733}}''.
 
: ''Note: at this stage metadata from a lot of repository will be downloaded, the UI may become unresponsive, but after some minutes it should return to a working state, see {{bug|323733}}''.
 +
: Because of this initial, first time, long download time, it is advisable that all indigo releng engineers install the editor, and open the indigo.b3aggr file "early" before its actually needed.
 +
: Tip: Having the model "loaded" and allowing it to update itself (staying current with latest contents of referenced repos) and syncing up the indigo.build project on a regular basis, can often help you spot errors or inconsistencies with your own contributions, and allow fixes to be made before committing your own updates. 
 +
 +
== For new project contributions ==
 +
 +
* Tip: if you are nervous about making large changes you can always tag the CVS indigo.build project before making large changes, so there is an obvious restore point. For example, you could tag with <youruserid>_pre<project>addition<datetime> or some such easily recognizable marker.
 +
 
* Create the following elements ('''New Child''') under '''Aggregator Indigo''':
 
* Create the following elements ('''New Child''') under '''Aggregator Indigo''':
** A '''Contact''' (show Property View to specify '''Email''' and '''Name''')
+
** One or more '''Contacts''' (show Property View to specify '''Email''' and '''Name''')
 
** A '''Contribution''' (specify '''Label''' and link to '''Contact''')
 
** A '''Contribution''' (specify '''Label''' and link to '''Contact''')
 
*** A '''Mapped Repository''' (specify '''Location''': URL of your p2 repository)
 
*** A '''Mapped Repository''' (specify '''Location''': URL of your p2 repository)
 
**** Your '''Feature'''s (select name from features found in your repository, select '''Categories''' from pre-defined set, specify exact version to be included in aggregation under '''Version Range''')
 
**** Your '''Feature'''s (select name from features found in your repository, select '''Categories''' from pre-defined set, specify exact version to be included in aggregation under '''Version Range''')
*: When done select your Contribution and invoke '''Detach Resource''' from the context menu. Choose a filename like <code>''projectname''.b3aggrcon</code> (renaming this file at a later stage is not supported).
+
* Select your Contribution and invoke '''Detach Resource''' from the context menu. Choose a filename like <code>''projectname''.b3aggrcon</code> (renaming this file at a later stage is not supported). For ease of bookkeeping, it is advisable to use the "exact" name of your project as it appears in the Eclipse Foundation databases, including top level and subproject names, as appropriate, for example, <code>emf-validation.b3aggrcon</code> is preferable to <code>validation.b3aggrcon</code> or <code>webtools.b3aggrcon</code> preferable to <code>wtp.b3aggrcon</code>.
 +
 
 +
* Checkin. At this point, you are ready to checkin your contribution. You will need to synchronize and check in changes to the indigo.b3aggr file, as well as your <code>''projectname''.b3aggrcon</code> file.
 +
 
 +
== Updating contributions ==
 +
 
 +
* To change things like Contributors, Categories, or adding or removing features, you should use the b3 Aggregator with the top level <code>indigo.b3aggr</code> file ... as these things often have relationships that cross files and you need to update, synchronize and checkin all effected files. Note: the Categories are normally only added or edited by Planning Council, so be sure large changes there have been discussed via bugzilla, etc. (You can do this via e-mail, or a bugzilla entry).
 +
 
 +
* To changes values of feature versions, or repository URLs, you can directly change your <code>''projectname''.b3aggrcon</code> file with text editor (or build scripts) and check those in, in isolation. Of course, you still can use the b3 aggregator editor, and it is often desirable to so, as it will do a "workbench build" and will tell you if something is wrong. For example, if the repository URL does not point to a valid repository, you'll know about it right away, if you use the b3 Aggregator Editor.
 +
 
 +
* Note that contributions, features, and repositories can be enabled or disabled, via property page. This allows temporary changes with minimal disruption. For example, if you disable a contribution or feature, it will be left out of a category, without having to also edit the category). This is especially useful if there is a leaf component that is "broken" and should temporarily be omitted from the build. '''Important: ''' One implication of this is you may need to sometimes re-enable your contribution or feature, even if you did not disable it. These are sometimes disabled by others -- without notice -- especially if a contribution or feature is causing build breaks for an extended period of time especially if there's been no communication explaining it or describing status or outlook on cross-project list. Of course, fixing the issue is the desired first choice, as disabling one contribution or feature will often require other contributions or features to be disabled simply because they depend on the broken one. 
 +
 
 +
== Historical References ==
  
At this point you ''should'' be ready to checkin your contribution and wait for it to be picked up by the next aggregation run, ''but someone familiar with this process should probably complete this description.''
+
* For Helios June release, the b3 aggregator was used on the backend, translating the previous .build files under the covers, in batch mode. See {{bug|312645}}.  
  
'''Updating your contribution:''' For any changes to your contribution always open and edit the toplevel <code>indigo.b3aggr</code>, even though a separate <code>.b3aggrcon</code> file is maintained per project. The editor will transparently handle this.
+
* For Helios maintenance and the Indigo release, the .build file format was dropped and the b3 aggreator native format files used instead. See [http://dev.eclipse.org/mhonarc/lists/cross-project-issues-dev/msg04575.html [cross-project-issues-dev]] Ready for Helios SR1 builds? .... and file format change?

Revision as of 01:05, 27 August 2010

This instructions outline how to contribute to the Indigo aggregation build for the common repository. They also may be useful for those updating contributions for Helios maintenance releases, though Helios not covered explicitly (the basics are the same).

If at anytime, there are questions, issues or problems, don't hesitate to ask on cross-project mailing list, or open a cross-project bug.

Contents

Checkout CVS indigo.build project

Check out project org.eclipse.indigo.build from dev.eclipse.org:/cvsroot/callisto. If you do not have write access to this repository location, contact the webmaster, explaining which project you are working with, and CC the Planning Council chairperson (currently david_williams@us.ibm.com).

Install the b3 Aggregator

  • Follow instructions to install the b3 Aggregator editor (and checkout the above mentioned CVS project). Tip: many find it preferable to have a separate workspace for this aggregation work, as it works with many p2 repositories and can add a lot of background processing as it works with all those repositories.
  • Open the file indigo.b3aggr using the Aggregator Model Editor
Note: at this stage metadata from a lot of repository will be downloaded, the UI may become unresponsive, but after some minutes it should return to a working state, see bug 323733.
Because of this initial, first time, long download time, it is advisable that all indigo releng engineers install the editor, and open the indigo.b3aggr file "early" before its actually needed.
Tip: Having the model "loaded" and allowing it to update itself (staying current with latest contents of referenced repos) and syncing up the indigo.build project on a regular basis, can often help you spot errors or inconsistencies with your own contributions, and allow fixes to be made before committing your own updates.

For new project contributions

  • Tip: if you are nervous about making large changes you can always tag the CVS indigo.build project before making large changes, so there is an obvious restore point. For example, you could tag with <youruserid>_pre<project>addition<datetime> or some such easily recognizable marker.
  • Create the following elements (New Child) under Aggregator Indigo:
    • One or more Contacts (show Property View to specify Email and Name)
    • A Contribution (specify Label and link to Contact)
      • A Mapped Repository (specify Location: URL of your p2 repository)
        • Your Features (select name from features found in your repository, select Categories from pre-defined set, specify exact version to be included in aggregation under Version Range)
  • Select your Contribution and invoke Detach Resource from the context menu. Choose a filename like projectname.b3aggrcon (renaming this file at a later stage is not supported). For ease of bookkeeping, it is advisable to use the "exact" name of your project as it appears in the Eclipse Foundation databases, including top level and subproject names, as appropriate, for example, emf-validation.b3aggrcon is preferable to validation.b3aggrcon or webtools.b3aggrcon preferable to wtp.b3aggrcon.
  • Checkin. At this point, you are ready to checkin your contribution. You will need to synchronize and check in changes to the indigo.b3aggr file, as well as your projectname.b3aggrcon file.

Updating contributions

  • To change things like Contributors, Categories, or adding or removing features, you should use the b3 Aggregator with the top level indigo.b3aggr file ... as these things often have relationships that cross files and you need to update, synchronize and checkin all effected files. Note: the Categories are normally only added or edited by Planning Council, so be sure large changes there have been discussed via bugzilla, etc. (You can do this via e-mail, or a bugzilla entry).
  • To changes values of feature versions, or repository URLs, you can directly change your projectname.b3aggrcon file with text editor (or build scripts) and check those in, in isolation. Of course, you still can use the b3 aggregator editor, and it is often desirable to so, as it will do a "workbench build" and will tell you if something is wrong. For example, if the repository URL does not point to a valid repository, you'll know about it right away, if you use the b3 Aggregator Editor.
  • Note that contributions, features, and repositories can be enabled or disabled, via property page. This allows temporary changes with minimal disruption. For example, if you disable a contribution or feature, it will be left out of a category, without having to also edit the category). This is especially useful if there is a leaf component that is "broken" and should temporarily be omitted from the build. Important: One implication of this is you may need to sometimes re-enable your contribution or feature, even if you did not disable it. These are sometimes disabled by others -- without notice -- especially if a contribution or feature is causing build breaks for an extended period of time especially if there's been no communication explaining it or describing status or outlook on cross-project list. Of course, fixing the issue is the desired first choice, as disabling one contribution or feature will often require other contributions or features to be disabled simply because they depend on the broken one.

Historical References

  • For Helios June release, the b3 aggregator was used on the backend, translating the previous .build files under the covers, in batch mode. See bug 312645.
  • For Helios maintenance and the Indigo release, the .build file format was dropped and the b3 aggreator native format files used instead. See [cross-project-issues-dev] Ready for Helios SR1 builds? .... and file format change?