Difference between revisions of "Simrel/Contributing to Simrel Aggregation Build"

From Eclipsepedia

Jump to: navigation, search
(Install the b3 Aggregator)
(edit for change in names and repository)
Line 1: Line 1:
These instructions outline how to contribute to the Juno aggregation build for the common repository. The instructions are very similar
+
These instructions outline how to contribute to the Juno aggregation build for the common repository.  
to the [[Indigo/Contributing_to_Indigo_Build| instructions for Indigo]]. There are the following, relatively small changes:
+
  
* the recommended or required version of b3 aggregator is different (this will likely require two instances of Eclipse installed, each with their own workspace -- one for 'indigo' and one for 'juno'. 
+
These instructions were substantially changed in August of 2012, to accommodate migration to new source repository, and at the same time a rename of the main project needed from that repository. The instructions and process for Juno (SR1 and SR2) are very similar to those for Kepler (SR0, in June 2013) except for the branch to use to for modifications/updates; Juno_maintenance for the former, master for the latter. For history of migration and change of project names, see {{bug|359240}}.  
* the main aggregation model file was renamed to a more generic term, "simrel.b3aggr"
+
* the normal rename of any cvs projects, test packages or urls ... they will now have 'juno' in place of 'indigo'
+
  
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.  
+
If at anytime, there are questions, issues or problems, don't hesitate to ask on [mailto://cross-project-issues-dev@eclipse.org cross-project list], or [https://bugs.eclipse.org/bugs/enter_bug.cgi?product=Community&component=Cross-Project open a cross-project bug].  
  
== Checkout CVS juno.build project ==  
+
== Get the simrel.build project ==  
  
Check out project <code>org.eclipse.juno.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) or [https://bugs.eclipse.org/bugs/enter_bug.cgi?product=Community&component=CVS open a bugzilla entry] (with that same information).
+
If you don't have it already, you'll need to install Eclipse EGit, from common repository or their own repository at
  
Note: once per year, after SR1, approximately mid-October, anyone who has not committed anything to the "build" project (governed by callisto-dev Linux group) will simply be removed from that group. So, if you need write access again (after not needing it for a year) simply re-request to be added, again stating which project you are committing for. [Note: there is at least one id, 'genie', that is a member of callisto-dev that should not be removed, even though it will show no "commits", as it is required to be there for signing purposes. See {{bug|362436}} for problems that result from removing it.]
+
  <code><nowiki>http://download.eclipse.org/egit/updates/</nowiki></code>
  
== Install the b3 Aggregator ==
+
Clone the repository named <code>org.eclipse.simrel.build.git</code> and import the project of similar name, <code>org.eclipse.simrel.build</code>. There is only the one project in that repository. An appropriate URL would be similar to
  
* Update as of 9/7/2011: Back to 0.2 version ... pretty sure it (and I) are ready now.  
+
  <code><nowiki>ssh://yourCommitterUserId@git.eclipse.org/gitroot/simrel/org.eclipse.simrel.build.git</nowiki></code>.
  
* <del>Update as of 8/12/11: For at least Juno M1, we are going to continue using the 0.1.x version of aggregator. [We will (likely) update to 0.2.x aggregator (and evolve model) later during Juno cycle.] </del>
+
If you do not have write access to this repository location, then [https://bugs.eclipse.org/bugs/enter_bug.cgi?product=Community&component=Cross-Project open a bugzilla entry] or send an email to 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).
  
::<del>In Eclipse 3.6.2  install the b3 aggregator editor from the following URL: </del>
+
Note: To control "inactive committers", once per year, usually around SR1, anyone who has not committed anything to the "build" project (governed by callisto-dev Linux group) will simply be removed from that group. So, if you need write access again (after not needing it for a year) simply re-request to be added, again stating which project you are committing changes for. [Reminder: there is at least one id, 'genie', that is a member of callisto-dev that should not be removed, even though it will show no "commits", as it is required to be there for signing purposes. See {{bug|362436}} for problems that result from removing it.]
  
  <del><nowiki>http://download.eclipse.org/modeling/emft/b3/updates-3.6/</nowiki></del>
+
The 'master' branch of that repo is used for the most forward looking release (namely Kepler, as of this writing) and maintenance for SR1 and SR2 will be named following the pattern of '<Release>_maintenance' (so, Juno_maintenance for Juno SR1 and Juno SR2).  
  
* Use the 0.2.x version of the b3 aggregator, running on Eclipse 3.7, installed from b3's "3.7 repo", at following URL:
+
== Install the b3 Aggregator ==
  
  <nowiki>http://download.eclipse.org/modeling/emft/b3/updates-3.7/</nowiki>
+
* Use the 0.2.x version of the b3 aggregator Editor, running on Eclipse 3.7.2 (Indigo SR2) or 4.2 (Juno), installed from b3's "3.7 repo", at following URL:
  
* 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.  
+
  <code><nowiki>http://download.eclipse.org/modeling/emft/b3/updates-3.7/</nowiki></code>
 +
 
 +
* Follow instructions to install the [[Eclipse_b3/aggregator/manual | b3 Aggregator editor]] (and get the above mentioned project in your workspace). Tip: you may prefer 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 <code>simrel.b3aggr</code> using the '''Aggregator Model Editor'''
 
* Open the file <code>simrel.b3aggr</code> using the '''Aggregator Model Editor'''
  
: Tip: Having the model "loaded" and allowing it to update itself (staying current with latest contents of referenced repos) and syncing up the juno.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 update to CVS.
+
: Tip: Having the model "loaded" and allowing it to update itself (staying current and caching the latest contents of referenced repos) and syncing up (pulling) the simrel.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 you commit and push your changes to the repository and risk breaking the build.  
  
 
== For new project contributions ==  
 
== For new project contributions ==  
  
* Tip: if you are nervous about making large changes you can always tag the CVS juno.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 top '''Aggregation: ''' node or '''Validation set:'''.
 
+
** One or more '''Contacts''' (show Property View to specify both '''Email''' and '''Name'''). [It must be a real email, not dev list].
* Create the following elements ('''New Child''') under '''Aggregator Juno''':
+
** 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''')
* 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>.  
+
* To create your b3aggrcon file, select your specific '''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>.  
  
* Verify. To ensure that your contribution will not break the build, right-click on your contribution and select "Verify Repository".
+
* Verify. Be sure to "pull" to be sure you have current contents of every thing (with no conflicts). To ensure that your contribution will not break the build, right-click on top-most Aggregation: node and  
 +
#'''Validate''' checks the general XML and EMF Model validity (short running), then
 +
#'''Validate Aggregation''' checks the whole model specifies correct and valid repo locations and compatibility dependencies (long running).  
  
* Checkin. At this point, you are ready to checkin your contribution. You will need to synchronize and check in changes to the simrel.b3aggr file, as well as your <code>''projectname''.b3aggrcon</code> file.
+
* Commit and Push. At this point, you are ready to commit and push your contribution. You will need to check in changes to the <code>simrel.b3aggr</code> file, as well as your <code>''<projectname>''.b3aggrcon</code> file.
  
 
== Updating contributions ==  
 
== Updating contributions ==  
  
* To change things like Contributors or Categories, or adding or removing features, you should use the b3 Aggregator with the top level <code>simrel.b3aggr</code> file ... as these things often have relationships that span 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 in cross-project category).  
+
* To change things like Contributors or Categories, or adding or removing features, you should use the b3 Aggregator with the top level <code>simrel.b3aggr</code> file ... as these things often have relationships that span multiple 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 a bugzilla entry in cross-project category).  
  
* To change 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 can and should still use the b3 aggregator editor, and it is often desirable to do 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.  
+
* To change 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 can and should still use the b3 aggregator editor, and it is often desirable to do so, as it will do a "validate aggregation" and will tell you if something is wrong. For example, if there is a typo, and 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 will 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.   
 
* 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 will 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.   

Revision as of 15:32, 6 August 2012

These instructions outline how to contribute to the Juno aggregation build for the common repository.

These instructions were substantially changed in August of 2012, to accommodate migration to new source repository, and at the same time a rename of the main project needed from that repository. The instructions and process for Juno (SR1 and SR2) are very similar to those for Kepler (SR0, in June 2013) except for the branch to use to for modifications/updates; Juno_maintenance for the former, master for the latter. For history of migration and change of project names, see bug 359240.

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

Contents

Get the simrel.build project

If you don't have it already, you'll need to install Eclipse EGit, from common repository or their own repository at

 http://download.eclipse.org/egit/updates/

Clone the repository named org.eclipse.simrel.build.git and import the project of similar name, org.eclipse.simrel.build. There is only the one project in that repository. An appropriate URL would be similar to

 ssh://yourCommitterUserId@git.eclipse.org/gitroot/simrel/org.eclipse.simrel.build.git.  

If you do not have write access to this repository location, then open a bugzilla entry or send an email to the webmaster, explaining which project you are working with, and CC the Planning Council chairperson (currently david_williams@us.ibm.com).

Note: To control "inactive committers", once per year, usually around SR1, anyone who has not committed anything to the "build" project (governed by callisto-dev Linux group) will simply be removed from that group. So, if you need write access again (after not needing it for a year) simply re-request to be added, again stating which project you are committing changes for. [Reminder: there is at least one id, 'genie', that is a member of callisto-dev that should not be removed, even though it will show no "commits", as it is required to be there for signing purposes. See bug 362436 for problems that result from removing it.]

The 'master' branch of that repo is used for the most forward looking release (namely Kepler, as of this writing) and maintenance for SR1 and SR2 will be named following the pattern of '<Release>_maintenance' (so, Juno_maintenance for Juno SR1 and Juno SR2).

Install the b3 Aggregator

  • Use the 0.2.x version of the b3 aggregator Editor, running on Eclipse 3.7.2 (Indigo SR2) or 4.2 (Juno), installed from b3's "3.7 repo", at following URL:
 http://download.eclipse.org/modeling/emft/b3/updates-3.7/
  • Follow instructions to install the b3 Aggregator editor (and get the above mentioned project in your workspace). Tip: you may prefer 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 simrel.b3aggr using the Aggregator Model Editor
Tip: Having the model "loaded" and allowing it to update itself (staying current and caching the latest contents of referenced repos) and syncing up (pulling) the simrel.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 you commit and push your changes to the repository and risk breaking the build.

For new project contributions

  • Create the following elements (New Child) under top Aggregation: node or Validation set:.
    • One or more Contacts (show Property View to specify both Email and Name). [It must be a real email, not dev list].
    • 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)
  • To create your b3aggrcon file, select your specific 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.
  • Verify. Be sure to "pull" to be sure you have current contents of every thing (with no conflicts). To ensure that your contribution will not break the build, right-click on top-most Aggregation: node and
  1. Validate checks the general XML and EMF Model validity (short running), then
  2. Validate Aggregation checks the whole model specifies correct and valid repo locations and compatibility dependencies (long running).
  • Commit and Push. At this point, you are ready to commit and push your contribution. You will need to check in changes to the simrel.b3aggr file, as well as your <projectname>.b3aggrcon file.

Updating contributions

  • To change things like Contributors or Categories, or adding or removing features, you should use the b3 Aggregator with the top level simrel.b3aggr file ... as these things often have relationships that span multiple 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 a bugzilla entry in cross-project category).
  • To change 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 can and should still use the b3 aggregator editor, and it is often desirable to do so, as it will do a "validate aggregation" and will tell you if something is wrong. For example, if there is a typo, and 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 will 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.

Categories

The overall categories used in the common repository are the responsibility of the Planning Council (in that they have the final say about any new ones, removals, etc.). So ... please open a cross-project bug if you'd like to propose new categories or some reorganization. But otherwise, feel free to add or remove your features to what ever categories you think are appropriate (using the full aggregator editor, since two files are changed when doing so) and others will open bugs if something seems wrong, or in the wrong category.

Runtime Target Platform Category

Some features (or bundles) are not intended to be installed into an IDE ... they do not contribute to the IDE (such as menu items, etc.). By convention, such features should be placed in the "EclipseRt Target Platform Category". This would be the case for, say, a "server" that someone was coding and testing for. In some cases, a runtime feature might "cause harm" (or, change behavior) if a user mistakenly installed it into their IDE. To prevent a feature (or bundle) from being installed into an IDE, the current "process" is for that feature or bundle to specify a negative requirement on a "magic IU". This is usually done in a p2.inf file, with contents of

# this bundle should not be installed into IDE
requires.0.namespace = A.PDE.Target.Platform
requires.0.name = Cannot be installed into the IDE
requires.0.range = 0.0.0

The details of the "magic" solution may change in Juno, as a cleaner solution is being discussed in bug 365004 ... it would be a similar "negative requirement" but just may be on a different (non magic) IU.