Difference between revisions of "Eclipse/Workspace/Committer FAQ"

From Eclipsepedia

Jump to: navigation, search
(New page: == Meta FAQ == === Who is this FAQ for? === This FAQ is for the JDT/Core committers, and anyone who is willing to participate in the development of JDT/Core. === What is this FAQ about? ...)
 
(The resolution REMIND is deprecated. What should I use instead?)
(36 intermediate revisions by 4 users not shown)
Line 2: Line 2:
  
 
=== Who is this FAQ for? ===
 
=== Who is this FAQ for? ===
This FAQ is for the JDT/Core committers, and anyone who is willing to participate in the development of JDT/Core.
+
This FAQ is for the Platform workspace committers, and anyone who is willing to participate in the development of Platform workspace.
  
 
=== What is this FAQ about? ===
 
=== What is this FAQ about? ===
This FAQ is about the rules that JDT/Core committers follow when developing the JDT/Core component.  
+
This FAQ is about the rules that Platform/Workspace committers follow when developing the Platform/Workspace component.  
  
 
=== How do I contribute to this FAQ? ===
 
=== How do I contribute to this FAQ? ===
Line 11: Line 11:
  
 
=== What should I do after contributing to this FAQ? ===
 
=== What should I do after contributing to this FAQ? ===
You should send a message to jdt-core-dev@eclipse.org with the diff url (e.g. http://wiki.eclipse.org/index.php?title=JDT_Core_Committer_FAQ&diff=50788&oldid=50780) so that every JDT/Core committer is aware of the change.
+
For significant changes in development practice, you should send a message to platform-core-dev@eclipse.org with the diff url (e.g. http://wiki.eclipse.org/index.php?title=Eclipse/Workspace/Committer_FAQ&diff=50788&oldid=50780) so that every Platform/Workspace committer is aware of the change.
  
 
== Coding ==
 
== Coding ==
  
=== Where is the JDT/Core code? ===
+
=== Where is the Platform/Workspace code? ===
All the JDT/Core code is in the Eclipse CVS repository. The JDT/Core projects are:
+
All the Platform/Workspace code is in the following Eclipse Git repositories:
* org.eclipse.jdt.compiler.tool
+
* org.eclipse.jdt.compiler.tool.tests
+
* org.eclipse.jdt.core
+
* org.eclipse.jdt.core.tests.builder
+
* org.eclipse.jdt.core.tests.compiler
+
* org.eclipse.jdt.core.tests.model
+
* org.eclipse.jdt.core.tests.performance
+
  
=== How do I create a CVS repository connection? ===
+
* {{Git|platform|eclipse.platform.resources.git}}
The following information must be used to create a CVS repository connection:
+
* {{Git|platform|eclipse.platform.team.git}}
* Connection type: extssh (or pserver if you are not yet a committer and don't have an Eclipse account)
+
 
* User: <your id> (or anonymous if you are not yet a committer and don't have an Eclipse account)
+
Q: ''Any interesting Team Project Sets, such as the old [http://dev.eclipse.org/viewcvs/index.cgi/platform-vcm-home/plugins/target/target-project-sets/all-target.psf?view=co all-target.psf] for the FTP/WebDAV stuff? What about other retired code? What about Wiki & Website contents under Platform/Workspace supervision?''
* Password: <your password>
+
 
* Host: dev.eclipse.org
+
=== How do I checkout code from Git? ===
* Repository path: /cvsroot/eclipse
+
Read the [[Git]] wiki page for instructions on using Git with Eclipse.
* Use default port
+
  
 
=== What branch should I use? ===
 
=== What branch should I use? ===
* HEAD: used for the development of the upcoming release. For example, HEAD is currently used for the development of 3.5.
+
* master: used for the development of the upcoming annual release.
* R3_x_maintenance: used for the maintenance of a release. For example, R3_4_maintenance is currently used for the development of 3.4.2.
+
* R4_x_maintenance: used for the maintenance of a release. For example, R4_3_maintenance is used for the development of 4.3.x.
  
 
=== How should I format my code? ===
 
=== How should I format my code? ===
We currently don't have a formatter profile available. But the rule is that you should try to format your code as the surrounding code.  
+
Each project has formatter options in the project-specific settings. So, just hit Ctrl+Shift+F. Javadoc comments are not formatted, but just ensure they have reasonable
If you are not sure, use the Eclipse [built-in] formatter profile which is very close to the JDT/Core team's formatting style.
+
line breaks. See additional core conventions [http://www.eclipse.org/eclipse/platform-core/documents/coding_conventions.html here]. Class members are generally sorted alphabetically.
 +
 
 +
Q: ''What about doing a FindBugs run, would we do that privately without committing the FindBugs settings?''
  
 
=== What should I do to backport a fix? ===
 
=== What should I do to backport a fix? ===
<p>When a bug is fixed in HEAD, it is sometimes interesting (or necessary) to backport the fix to the maintenance branch. The fix needs first to be modified in order to be applied on top of the maintenance branch's code. It may be easy or tricky depending on how the patch's code area has been touched in the branch.</p>
+
When a bug is fixed in HEAD, it is sometimes interesting (or necessary) to backport the fix to the maintenance branch. This is typically only done for critical bugs, since milestone builds undergo less testing and stability is the most important factor for the maintenance stream. The fix needs first to be modified in order to be applied on top of the maintenance branch's code. It may be easy or tricky depending on how the patch's code area has been touched in the branch.
<p>The bug is either in RESOLVED/FIXED or VERIFIED/FIXED state, which means respectively either in '''State 2''' or in '''State 2.1''' according to the [[#What_is_the_JDT.2FCore_bugs_life_cycle.3F|JDT/Core bug life cycle]].</p>
+
* Clone the bug, and mark the clone with the maintenance branch target milestone.
<p>So depending of that state, when the fix is ready, you have to:</p>
+
** Q: ''Do we keep the cloned bug as bugzilla "depends on"? Do we attach a patch for the backport?''
# Set the target of the bug and all its duplicates to the corresponding maintenance target (e.g. 3.4.2)
+
** A: Yes, and yes.
# Release the fix in the maintenance branch (e.g. R3_4_maintenance branch)
+
* Release the fix in the maintenance branch, and tag with the org.eclipse.releng project from the same maintenance branch
# Add the corresponding comment (e.g. ''Released for 3.4.2'')
+
** Q: ''Who is responsible for updating version numbers in the feature(s) containing a bundle which gets a new version due to a backport?''
# Set the Status Whiteboard to:
+
## if the bug is in '''State 2''': "To be verified for <maintenance target>" (e.g. ''To be verified for 3.4.2'')
+
## if the bug is in '''State 2.1''': "To be verified for <next milestone>" (e.g. ''To be verified for 3.5M3''). ''Note that in this case, the bug might need to be reopened if the maintenance stream was frozen owing to a service release end of cycle (see [[#What_is_the_JDT.2FCore_bugs_life_cycle.3F|JDT/Core bug life cycle (State 2.2)]].''
+
  
== Committing to CVS ==
+
== Contributing ==
  
=== How do I maintain the build notes? ===
+
=== Contributing a fix ===
The build notes (in org.eclipse.jdt.core/buildnotes_jdt-core.html) should be updated just before committing a bug fix. This file should be
+
committed at the same time as the bug fix. To update the build notes, use the JDT/Core tool (right click on the file, then JDT Core tools > Add to build note...).
+
  
=== What comment should I associate with a commit? ===
+
There are several ways available to contribute a patch:
The comment of a commit should be of the form: <branch> - <bug number with optional comments>, e.g.
+
* HEAD - 1234567
+
* R3_3_maintenance - fix for 123678 (with tests)
+
  
=== Can I release code during the milestone week? ===
+
* Via the [[Gerrit]] repositories: [https://git.eclipse.org/r/#/admin/projects/platform/eclipse.platform.resources Resources Gerrit], [https://git.eclipse.org/r/#/admin/projects/platform/eclipse.platform.team Team Gerrit].
<p>Initial answer is: '''NO'''</p>
+
* Forking the Git repositories, committing a fix, and requesting that a committer "pull" your change.
<p>The milestone stream has to stay clean until the milestone is declared. Then, we would be able to fix a stop shipping bug and contribute again without introducing any other changes since the [[#What_is_the_verification_process_for_a_milestone.3F|verification process]].</p>
+
* Attaching a patch in bugzilla. Use the "git format-patch" command to produce a properly formatted commit patch.
<p>However, looking at milestone history, re-contributing seldom happened, so <b>if this is really necessary and only for HEAD stream</b>, code releases are allowed if the verification process has well finished and the stream reopened for development.</p>
+
<p>See also ''[[#What_should_I_do_if_I_need_to_contribute_after_the_verification_was_finished.3F|What should I do if I need to contribute after the verification was finished?]]'' question...</p>
+
  
=== Can I release code during the build input? ===
+
For more details see [[Development_Resources/Contributing_via_Git]].
<p>Again, the answer is: '''NO'''</p>
+
<p>The development stream also needs to stay clean during the build input process. It usually starts three hours before the build starts (e.g. 5:00 am - Eastern time) the day of the build input and it ends when "''Released v_XXX for today's build input''" message is sent on jdt-core-dev@eclipse.dev mailing list.</p>
+
<p>However, if you have an important fix to release and you're not 100% sure that it will be done before the build input starts (sometimes this happens for European committers...), then just ask to delay it until you're ready. As the process can be shorten a little bit, it is possible to accept <b><u>safe</u></b> contribution until one hour before the build starts... But of course you should not abuse this flexibility. Three hours is the necessary time to run all tests and to have the time to react in case of failures. This is of course not possible when the build input process starts just one hour before!</p>
+
  
=== How do I warn users after I changed the build state version or the index file version? ===
+
Note: All contributors must sign the Eclipse [[CLA| Contributor License Agreement]].
Changing the build state version <code>org.eclipse.jdt.internal.core.builder.State#VERSION</code> will cause a full build when the user restarts the workspace with the new version. As well changing the index file version <code>org.eclipse.jdt.internal.core.index.DiskIndex#SIGNATURE</code> will cause all files in the workspace to be reindexed when the user restarts the workspace with the new version. In both case, you should add an entry in the build notes in the "What's new" section so that users are aware of this change.  
+
  
* If the build state version is changed, you can add the following entry:
+
=== Becoming a Committer ===
<pre>
+
<li>Fix for <a href="http://bugs.eclipse.org/bugs/show_bug.cgi?id=?????">bug ?????</a> required the build state format to change.
+
    As a consequence, a full rebuild is expected when reusing existing workspaces.
+
</li>
+
</pre>
+
  
* If the index version is changed, you can add the following entry:
+
According to the [http://eclipse.org/eclipse/eclipse-charter.php Eclipse Project Charter], contributors who provide "frequent and valuable" contributions can have their status promoted to that of committer. Here are some things to look for when evaluating a contributor for commit rights
<pre>
+
* A strong track record of contributions that have been committed into our code base. Since it is difficult to evaluate the quality of a contribution on a bug that has not been committed, the focus is on evaluating the body of committed contributions. Size and complexity of contributions is more important than raw number of contributions. One major new feature is more interesting than a dozen fixed javadoc typos
<li>Fix for <a href="http://bugs.eclipse.org/bugs/show_bug.cgi?id=?????">bug ?????</a> required the index version to be incremented.  
+
* Active participation in other aspects of the project - mailing list discussions, reporting, triaging, and evaluating incoming bugs, writing tests, documentation, etc.  
    Indexes will be automatically regenerated upon subsequent search queries (accounting for indexing notification in search progress
+
* Strong technical programming skill
    dialogs).
+
* Ability to negotiate and find consensus with other committers on changes
</li>
+
</pre>
+
  
== Bugzilla ==
+
== Committing to Git ==
  
=== What is the JDT/Core bugs life cycle? ===
+
=== What comment should I associate with a commit? ===
Here's the diagram for the main states of the JDT/Core bug life cycle:
+
The comment of a commit should be of the form: <bug number and title> [optional comments]<br/>
 +
Example: '''Bug 210770 Add IResource#HIDDEN and support for adding hidden projects'''.
 +
* Q: ''May it also be [210770] Add IResource#HIDDEN and support for adding hidden projects?''
 +
* A: No, the releng tool to send E-Mail about released changes only understands the "Bug nnnn" syntax, which has the additional benefit of being available by direct copy-and-paste from the respective Bugzilla headline.
 +
* Q: ''What if two bugs are associated with the same commit?''
  
[[Image:JDTCore_bugs2.jpg]]
+
=== What else should I do when I commit a change? ===
 +
When you commit a change, you should:
 +
* Mark the corresponding bug fixed. Trivial changes in HEAD don't need a bug report.
 +
* Ensure the copyright statement is updated based on the source of the contribution. Mark the iplog+ flag in the bug report if applicable
 +
* Run the test suites for the corresponding project (not necessary for trivial changes)
 +
* Q: ''How do we do New&Noteworthy's?''
 +
* A: 1 week before a milestone, an E-Mail is sent asking for new&noteworthy contributions. Committers who added significant changes in a milestone are requested to create a respective N&N item after coordinating with their component lead.
  
Please note the following points which may help to better understand this picture:
+
=== Can I release code during the milestone week? ===
# not all bug states have been put in this diagram due to an obvious the lack of space. So, the represented states are _only_ those for which committers need to have a peculiar attention and has to apply some rules defined in this FAQ when changing the state of a bug
+
* Initial answer is: '''NO'''
# some branch may not exist for certain bug. Typically, change the target of a bug to "Y" will not occur when the bug is not backported to another stream than "X". E.g. the left-most branch of this diagram will end at the first "VERIFIED" state for this kind of bug...
+
* The milestone stream has to stay clean until the milestone is declared. This enables us to fix a stop ship bug and contribute again without introducing any other changes.
# [ target = X ] means that the committer ''[[#What_target_milestone_should_be_used.3F|sets the bug target to X]]''
+
* Once our team has signed off on a milestone candidate, we can reopen the stream for development
# [ Released for X ] means that the committer released a fix for the bug and ''[[#What_comment_should_be_used_when_fixing_a_bug.3F|adds the comment 'Released for X']]'' to the bug
+
# verif X ok ---- means that ''[[#What_is_the_bugs_verification_phase.3F|the bug verification]]'' was OK for the milestone/rollup X (failing verifications are not in the diagram to keep it readable...)
+
  
=== What bugs are currently opened against JDT/Core? ===
+
=== Can I release code during the build input? ===
[https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced&short_desc_type=allwordssubstr&short_desc=&classification=Eclipse&product=JDT&component=Core&long_desc_type=allwordssubstr&long_desc=&bug_file_loc_type=allwordssubstr&bug_file_loc=&status_whiteboard_type=allwordssubstr&status_whiteboard=&keywords_type=allwords&keywords=&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&bug_status=RESOLVED&resolution=LATER&resolution=REMIND&resolution=---&emailtype1=substring&email1=&emailtype2=substring&email2=&bugidtype=include&bug_id=&votes=&chfieldfrom=&chfieldto=Now&chfieldvalue=&cmdtype=doit&order=Reuse+same+sort+as+last+time&field0-0-0=noop&type0-0-0=noop&value0-0-0= Bugs opened and not resolved yet.]
+
* Again, the answer is: '''NO'''
 +
* The build input is prepared between 6-10 PM EST on Monday prior to the regular Tuesday integration build. Please avoid making contributions during this time.
 +
* If you release a change after this period, you need to perform a separate build contribution for your change.
 +
** Q: ''Huh? What is "perform a build contribution", is this equivalent to "release to the mapfile"?''
  
=== What target milestone should be used? ===
+
== Bugzilla ==
# If you mark the bug FIXED (<b>[[#What_is_the_JDT.2FCore_bugs_life_cycle.3F|State 1]]</b> -> <b>[[#What_is_the_JDT.2FCore_bugs_life_cycle.3F|State 2]]</b>):
+
#: First, assign it to you, (as we always do).
+
#: Then, set the target with the next milestone (as we always do)
+
# If you mark the bug as WORKSFORME (<b>[[#What_is_the_JDT.2FCore_bugs_life_cycle.3F|State 1]]</b> -> <b>[[#What_is_the_JDT.2FCore_bugs_life_cycle.3F|State 3]]</b>):
+
#: First, assign it to you ''(this will help bugs dispatching during the verification process - see [[#What_are_the_bugs_I_have_to_verify.3F|What are the bugs I have to verify]])''.
+
#: Then,
+
#: a) if you tested the problem with a pure milestone build, use this milestone (e.g. if you've tested that a problem works with a pure 3.4M1 build, then use 3.4M1)
+
#: b) if you tested the problem with an integration build, use the next milestone (e.g. if you've tested that a problem works with an integration build after 3.4M1, then use 3.4M2)
+
# If you mark the bug as WONTFIX, INVALID, NOT_ECLIPSE (<b>[[#What_is_the_JDT.2FCore_bugs_life_cycle.3F|State 1]]</b> -> <b>[[#What_is_the_JDT.2FCore_bugs_life_cycle.3F|State 3]]</b>):
+
#: First, assign it to you.
+
#: Then, set the target with the next milestone (in this case, the target is simply used to identify that the bug has been closed during this specific period...)
+
# If you mark the bug as DUPLICATE (<b>[[#What_is_the_JDT.2FCore_bugs_life_cycle.3F|State 1]]</b> -> <b>[[#What_is_the_JDT.2FCore_bugs_life_cycle.3F|State 4]]</b>):
+
#: First, assign it to you.
+
#: Then,
+
#: a) if the original bug has not been resolved yet, don't set the milestone on the duplicate (it will be set when the original bug target is set)
+
#: b) if the original bug has been resolved:
+
#:: - use the same milestone on the duplicate as on the original bug
+
#:: - add the following formatted string to the Status Whiteboard: "To be verified for <next milestone or rollup>" (e.g. ''To be verified for 3.5M3'' or ''To be verified for 3.4.2'')
+
#:: <i>Note that the next milestone or rollup may be different than the target of the original bug.</i>
+
<i><u>Notes</u><br></i>
+
<i> - If a bug is backported to a maintenance stream, then see ''[[#What_should_I_do_to_backport_a_fix.3F|What should I do to backport a fix?]]'' question for more details</i><br>
+
<i> - As soon as you modify the target of a bug, then you have to go through all its duplicates if any and set these duplicates with the same milestone as the one used for the original bug.</i>
+
  
=== What comment should be used when fixing a bug? ===
+
=== What is the Platform/Workspace bugs life cycle? ===
When changing a bug to RESOLVED/FIXED a comment containing the following string should be use: "released for <target milestone | maintenance release>". E.g.
+
* Fixed and released for 3.4M2
+
* Released for 3.3.1
+
This string is used when querying the bugs to verify for a particular milestone.
+
  
=== The resolution LATER is deprecated. What should I use instead? ===
+
Roughly, NEW bugs are untriaged bugs. This means they are bugs that we have not yet reproduced, or we don't yet believe they are actually bugs. Once we can reproduce a bug, or have other evidence to believe a bug is real, it is marked ASSIGNED. Bugs ASSIGNED to the inbox are bugs that we believe are valid, but haven't had time to address (this is a good place to look if you're interested in making a contribution). Bugs assigned to a committer/contributor are bugs that person plans to fix. Bugs are marked FIXED if there was actually a code change committed to resolve the problem. If the bug is no longer reproducible but no code change was made to address it, it can be marked INVALID or WORKSFORME. We rarely use the VERIFIED state because the vast majority of fixes are verified through an additional automated test (and are therefore verified every time there's a build).
Bugs that we don't plan to fix used to be resolved as LATER. Since this resolution is deprecated, we shall now use the P5 priority.
+
  
=== The resolution REMIND is deprecated. What should I use instead?  ===
+
For details and queries, see [[Eclipse/Workspace/Bugs]].
Bugs that needed more information used to be resolved as REMIND. Since this resolution is deprecated, we shall now use the needinfo keyword.
+
  
=== What status/resolution should I use after marking a bug duplicate? ===
+
=== What bugs are currently opened against Platform/Workspace? ===
* If the original bug is marked RESOLVED/FIXED, leave it to RESOLVED/DUPLICATE
+
* If the original bug is marked VERIFIED/FIXED, add the following formatted string to the Status Whiteboard: To be verified for <next milestone>, e.g. To be verified for 3.4M6
+
  
=== When can I set a bug to VERIFIED? ===
+
* [https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced&classification=Eclipse&product=Platform&component=Compare&component=CVS&component=Resources&component=Runtime&component=Team&bug_status=UNCONFIRMED&bug_status=NEW&cmdtype=doit Untriaged bugs] (NEW or UNCONFIRMED state)
The bugs ''Resolution'' status is only set to VERIFIED during the verification process the week of the milestone delivery (see ''[[#How_do_I_verify_my_bugs.3F|How do I verify my bugs?]]'')
+
* [https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced&classification=Eclipse&product=Platform&component=Compare&component=CVS&component=Resources&component=Runtime&component=Team&bug_status=ASSIGNED&bug_status=REOPENED&emailassigned_to1=1&emailtype1=notregexp&email1=.*inbox%40eclipse.org&cmdtype=doit Assigned bugs] (ASSIGNED except to Inbox)
 +
* [https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced&classification=Eclipse&product=Platform&component=Compare&component=CVS&component=Resources&component=Runtime&component=Team&bug_status=ASSIGNED&bug_status=REOPENED&emailassigned_to1=1&emailtype1=regexp&email1=.*inbox%40eclipse.org&cmdtype=doit Deferred bugs] (ASSIGNED to Inbox)
  
== Release engineering ==
+
Q: ''The P5 prioritization for deferring stuff to the future seems orthogonal to this, I was not sure how to use it in the queries. I also wasn't sure whether Platform/Runtime component is for the Workspace team.''
  
=== What steps should I follow to make a build contribution? ===
+
=== What target milestone should be used? ===
# Ensure that you are in sync with the stream (HEAD, R3_x_maintenance, ...) you want to contribute to.
+
# Close the build notes using the JDT/Core tool (right click on the file, then JDT Core tools > Close build notes).
+
# Commit the build notes.
+
# Tag all JDT/Core projects (even those that haven't changed) with the current version (found in the build notes), eg. v_810
+
# If needed, check out org.eclipse.releng from the stream you want to contribute to.
+
# Edit org.eclipse.releng/maps/jdtcore.map:
+
## Change the contribution date
+
## Change all version numbers to the new one
+
# Commit org.eclipse.releng/maps/jdtcore.map
+
# Send a message to the jdt-core-dev mailing list saying that the contribution was made including the version number, e.g. a message with the following title: "Released v_810 for today's integration build" and no body is sufficient.
+
  
=== What is the milestone verification process? ===
+
A target milestone indicates a firm intention by a committer to fix a bug for a particular date. You should only set a milestone on bugs assigned to you, that you believe you can reasonably finish by that milestone. Of course this is not a guarantee, and milestones often end up slipping. Often for small bugs we only set the target milestone when marking the bug fixed.  No bug should be marked FIXED without a target milestone.
  
The verification of a milestone is made of two main phases:
+
=== What comment should be used when fixing a bug? ===
# bugs verification
+
Describe the fix that was made and the tests that were written. This is a useful place to record any tricky issues with the fix, since the bug report will be linked to the commit in Git, and a committer may come back to bugzilla years later to figure out the context for a change. You can also mention what stream the fix is in, although this can be inferred from the target milestone.
# build test usage
+
  
==== What is the bugs verification phase? ====
 
  
===== What are the bugs I have to verify? =====
 
<p>All bugs fixed in the milestone's stream must be verified the week of the milestone delivery.<br>
 
(''this is why setting the correct target for bugs is really important - see [[#What_target_milestone_should_be_used.3F|What target milestone should be used?]]'')</p>
 
<p>To avoid a bug verifying by several committers at the same time, the whole bugs list is split into several ones.
 
An email is sent to each verifier with the corresponding list of bugs to verify. </p>
 
<p>For example, the following bugzilla requests were used to follow the verification progress for milestone 3.4 M2:
 
:<u>all bugs to verify</u>: [https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced&classification=Eclipse&product=JDT&component=Core&target_milestone=3.3.1&target_milestone=3.4+M2&order=map_assigned_to.login_name%2Cbugs.bug_id&field0-0-0=bug_status&type0-0-0=notequals&value0-0-0=VERIFIED all bugs request]
 
:<u>bugs that Frederic must verify</u>: [https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced&classification=Eclipse&product=JDT&component=Core&target_milestone=3.3.1&target_milestone=3.4+M2&order=map_assigned_to.login_name%2Cbugs.bug_id&field0-0-0=bug_status&type0-0-0=notequals&value0-0-0=VERIFIED&field0-1-0=assigned_to&type0-1-0=regexp&value0-1-0=frederic verifier's bugs request]</p>
 
  
===== When do I have to verify my bugs? =====
 
<p>Usually this verification starts as soon as you get your bugzilla request and a warm-up build is available on [http://download.eclipse.org/eclipse/downloads Eclipse Project Downloads page].</p>
 
<p>''Note: The corresponding milestone stream is frozen until this verification is finished (see [[#When_can_I_consider_the_verification_finished.3F|When can I consider the verification finished?]])''</p>
 
  
===== How do I verify my bugs? =====
 
For each bug of your list:
 
# Verify that the resolution state is correct:
 
#* FIXED
 
#*: the problem described in the bug should no longer occur using the milestone build
 
#*: all duplicate bugs (if any) have to have the same target as this bug
 
#* DUPLICATE
 
#*: the problem described in the bug should no longer occur using the build <b>and</b> the bug is really a duplicate of the original
 
#* WORKSFORME
 
#*: the problem described in the bug does not occur using the milestone build
 
#* INVALID, NOT_ECLIPSE
 
#*: the reason why the bug is invalid has to be clearly explained and justified
 
#* WONTFIX
 
#*: the reason why the bug was not fixed has to be clearly explained
 
# Modify the bug according to the result of your verification:
 
#* if the verification is OK:
 
#** add a formatted comment to the bug: <b>"Verified for <''current verified milestone''> using <''build name''> build"</b>
 
#**: (''Note that for build name is not necessary when resolution state is INVALID, NOT_ECLIPSE or WONTFIX).
 
#** <u>only</u> if the target of the bug matches the verification process, set the bug ''Status'' to VERIFIED
 
#** reset the ''Status Whiteboard'' contents if it contains the formatted string ''To be verified for ...''
 
#* if the verification is KO:
 
#** reopen the bug with a comment if the described scenario is not fixed
 
#** open a new bug if a part of the problem is solved but there are still remaining issues using different scenarios
 
  
===== What if I my fix is not in the build used for the verification? =====
+
== Release engineering ==
<p>If your bug fix is not in the build used for the verification (typically if you commit the fix during or after
+
the verification day), you must coordinate with a verifier and tell him what build to expect the fix in.</p>
+
  
===== When can I consider the verification finished? =====
+
Releasing code to the integration builds is done using the Releng Tools plugin (org.eclipse.releng.tools). This plugin can be installed from the Eclipse project repository that is available in your install already (go to Help &gt; Install New Software). The release procedure is as follows:
<p>When all your bugs are verified, wait for the email sent to all team members and to the jdt-core-dev@eclipse.org list.
+
* Load all of the latest plugins and tests from HEAD
This mail describes the status of the verification and indicates which JDT/Core version is eligible for the milestone.
+
* Run the automated tests
You are also informed whether the corresponding stream is reopened for development or not.</p>
+
* Right-click the projects to release (including tests), and select Team &gt; Release
<p>Here's a sample of the email sent at then end of the 3.4M2 verification
+
* Follow through the release wizard. Make sure you check the box to generate build notes
:''Version v_813 of org.eclipse.jdt.core project should be the JDT/Core contribution for 3.4 M2 milestone...''
+
* Copy and paste the generated build notes into an email
:''So you can consider JDT/Core projects HEAD reopened for development :-)''
+
* Finish the release wizard
</p>
+
* Once complete, send the build notes email to the [https://dev.eclipse.org/mailman/listinfo/platform-core-dev platform-core-dev] mailing list.
  
===== What should I do if I need to contribute after the verification was finished? =====
+
== Misc ==
<p>Do NOT panic ;-)</p>
+
<p>The process depends whether the stream was modified since the last version or not:
+
* when no change was done in the stream:
+
*# send an email to all committers saying that you need to contribute again
+
*#:'''''Note: this freezes the milestone stream until the build input's email is sent on jdt-core-dev@eclipse.org'''''
+
*# release your fix
+
*# do a build input with version v_NNN+1 (see ''[[#What_steps_should_I_follow_to_make_a_build_contribution.3F|What steps should I follow to make a build contribution?]]'')
+
* but if some code was already released in the stream since the last version:
+
*# if not already done, create a branch which identifies the milestone, e.g. '''''zz3.4M2'''''
+
*# release the fix in this branch
+
*# do a build input with version v_NNN+1 (see ''[[#What_steps_should_I_follow_to_make_a_build_contribution.3F|What steps should I follow to make a build contribution?]]'')
+
*# backport the fix into the milestone stream
+
*# backport the version v_NNN+1 into the buildnotes_jdt-core.html and also into the messages.properties files
+
  
==== What is the build test usage? ====
+
=== How do I get the Core tools? ===
When the bugs verification is done and OK, all committers have to use the '''latest''' candidate build until the milestone is officially declared.
+
They should test it either as normal development usage or, if some more intensive testing is needed, as described in a specific test plan (e.g. http://www.eclipse.org/jdt/core/r3.3/test-3.3.1.php)
+
  
=== How do I deliver a patch for a maintenance stream? ===
+
The core tools bundles have some interesting tools for diagnosing problems and doing performance analysis on the resource tree, listeners, etc. The best way to get the core tools is to check them out from [http://git.eclipse.org/c/platform/eclipse.platform.resources.git/ eclipse.platform.resources.git] directly, and then build and install them. You need these bundles:
Note that you should contact Jerome first if you need to deliver a patch for a maintenance stream. In case Jerome is not available, here are the steps to follow:
+
# Increment the plugin version id by finding all text references to the previous version id in the org.eclipse.jdt.core project and replacing  them with the incremented version id.
+
# Add the following entry to the ''What's new'' section of the build notes:
+
#:<pre>&lt;li&gt;Plugin version ID got incremented to [plugin version id].&lt;/li&gt;</pre>
+
# Add a reference to the JDT/Core update area for the current stream. E.g. for a patch for 3.0.x, add the following entry to the ''What's new'' section of the build notes:
+
#:<pre>&lt;li&gt;Patch available at &lt;a href="http://www.eclipse.org/jdt/core/r3.0/main.html#updates"&gt;http://www.eclipse.org/jdt/core/r3.0/main.html#updates&lt;/a&gt;&lt;/li&gt;</pre>
+
#:Or for a patch for 3.3.x, add the following entry:
+
#:<pre>&lt;li&gt;Patch available at &lt;a href="http://www.eclipse.org/jdt/core/r3.3/index.php#UPDATES"&gt;http://www.eclipse.org/jdt/core/r3.3/index.php#UPDATES&lt;/a&gt;&lt;/li&gt;</pre>
+
# Close the build notes using the JDT/Core tool (right click on the file, then JDT Core tools > Close build notes).
+
# Add 'Posted on JDT/Core update area' after the date. E.g.
+
#:<pre>Eclipse SDK 3.0.3 - February 22, 2008 - Posted on JDT/Core update area</pre>
+
# Commit the build notes and the files modified by the plugin version id increment.
+
# Tag all JDT/Core projects (even those that haven't changed) with the current version (found in the build notes), eg. v_810
+
# Update the <code>/org.eclipse.releng/maps/jdtcore.map</code> file with the same tag and commit it to the maintenance branch so that the next official build will have the same level of fixes
+
# Run the <code>exportplugin.xml</code> script with the default target
+
# Copy the resulting jar (for 3.2.x or above) or the resulting zip to <code>/jdt-core-www/patches</code>
+
# Remove the previous jar/zip for the current stream
+
# Edit the <code>UPDATES</code> area of the <code>index.php</code> file (or <code>main.html</code> for 3.0.x or below) of the maintenance stream, and change:
+
## the reference to the jar
+
## the date
+
## the size of the jar (as it appears in the Properties of Windows Explorer)
+
## the plugin version id
+
## the CVS version tag
+
## the list of bugs that are addressed
+
## the build notes revision
+
# Commit the <code>index.php</code> file as well as the new jar addition and the old jar removal
+
  
== Misc ==
+
* org.eclipse.core.tools
 +
* org.eclipse.core.tools.resources
 +
* org.eclipse.core.resources.spysupport
  
=== How do I get the JDT/Core tools? ===
+
There is more information on what's in the core tools on the [http://www.eclipse.org/eclipse/platform-core/downloads.php core downloads page]. The downloads are out of date, but the information on what's in the tools is still relevant.
The JDT/Core tool can be obtained from this update site: http://www.eclipse.org/jdt/core/tools/jdtcoretools/update-site/ using Eclipse update manager.
+
 
 +
* Q: ''How do I run Performance tests?''
 +
* A: Best have the Performance tests run for you on the dedicated performance test machines - otherwise the risk is high that other processes interfere with your measurement. Performance tests are usually run every Tuesday on I-builds and every Saturday on N-builds. Your tests need to be hooked into the proper Performance test suite - check the '''test.xml''' file for your test bundle. In the case of resources, the suite is <code>org.eclipse.core.tests.resources.perf.AllTests</code>.
 +
** In order to be able and compare a new performance test against a baseline from the previous release, you'll need to commit and release into the respective previous release's performance baseline branch (for Eclipse 3.5.x, this is perf_35x).
  
 
=== An integration or maintenance build is red. Should I take it? ===
 
=== An integration or maintenance build is red. Should I take it? ===
 
A red build doesn't mean that it is not usable. It just means that some tests failed. The impact of failing tests is often negligeable. E.g. if the releng tests are failing, it just means that there is a problem in the Javadoc. So you should always take the latest integration or maintenance build, unless someone posted on the platform-releng-dev mailing list that it is not usable.
 
A red build doesn't mean that it is not usable. It just means that some tests failed. The impact of failing tests is often negligeable. E.g. if the releng tests are failing, it just means that there is a problem in the Javadoc. So you should always take the latest integration or maintenance build, unless someone posted on the platform-releng-dev mailing list that it is not usable.
  
=== What about contributions by non-committers? ===
+
* Q: ''How to review logs etc from nightly builds done by the Eclipse Releng team, in case a build is red due to my contribution?''
As of 20071121, the Eclipse project moved to an ever more on-demand IP process to take care of external contributions.
+
* A: Just follow the hyperlink for the build, click on the red "test results" and click on any red number related to your component. Scroll down to "Failure" to see the exception logged. Console output logs are available from the main tests page (clicking "test results" from the main download page), separated for each scenario and host run.
The Eclipse site has more detailed information about relevant IP processes, but the following quote from
+
Boris Bokowski (Boris_Bokowski@ca.ibm.com) on eclipse-dev provides a relevant checklist for committers contemplating
+
external code integration into Eclipse:
+
  
[We] would like to maintain our IP log as we go rather than doing it at the last minute.
+
=== What about contributions by non-committers? ===
For the IP log, we need to know about three things:
+
The Eclipse project uses the Eclipse Foundation's [[Development_Resources/Automatic_IP_Log | Automatic IP Log]] system. There are three categories of interesting content for the IP log:
  
(1)  "Small" contributions (patches) coming from non-committers. For this,
+
(1)  "Small" contributions (patches) coming from non-committers. For this, you must ensure the Author field of the Git commit is set to be the contributor. This will enable the Eclipse automatic IP log tool to record the contribution. For more details see [[Development_Resources/Contributing_via_Git]].
we ask you to use the keyword "contributed". Please remember to add this
+
keyword whenever you commit a patch from a non-committer.
+
  
 
(2)  "Large" contributions (code > 250 lines, new feature work) coming from
 
(2)  "Large" contributions (code > 250 lines, new feature work) coming from
Line 303: Line 169:
  
 
"Non-committer", in this context, is defined as: anyone who is not a
 
"Non-committer", in this context, is defined as: anyone who is not a
committer on the Eclipse project (Equinox, Platform, JDT, PDE) at the time
+
committer on the Eclipse project (Platform, JDT, PDE) at the time
 
they make the contribution.
 
they make the contribution.
  

Revision as of 08:39, 25 July 2013

Contents

Meta FAQ

Who is this FAQ for?

This FAQ is for the Platform workspace committers, and anyone who is willing to participate in the development of Platform workspace.

What is this FAQ about?

This FAQ is about the rules that Platform/Workspace committers follow when developing the Platform/Workspace component.

How do I contribute to this FAQ?

Simply edit this page. You will need to log in using your bugzilla username and password to gain access. If you don't have a Bugzilla account, you can create a new one.

What should I do after contributing to this FAQ?

For significant changes in development practice, you should send a message to platform-core-dev@eclipse.org with the diff url (e.g. http://wiki.eclipse.org/index.php?title=Eclipse/Workspace/Committer_FAQ&diff=50788&oldid=50780) so that every Platform/Workspace committer is aware of the change.

Coding

Where is the Platform/Workspace code?

All the Platform/Workspace code is in the following Eclipse Git repositories:


Q: Any interesting Team Project Sets, such as the old all-target.psf for the FTP/WebDAV stuff? What about other retired code? What about Wiki & Website contents under Platform/Workspace supervision?

How do I checkout code from Git?

Read the Git wiki page for instructions on using Git with Eclipse.

What branch should I use?

  • master: used for the development of the upcoming annual release.
  • R4_x_maintenance: used for the maintenance of a release. For example, R4_3_maintenance is used for the development of 4.3.x.

How should I format my code?

Each project has formatter options in the project-specific settings. So, just hit Ctrl+Shift+F. Javadoc comments are not formatted, but just ensure they have reasonable line breaks. See additional core conventions here. Class members are generally sorted alphabetically.

Q: What about doing a FindBugs run, would we do that privately without committing the FindBugs settings?

What should I do to backport a fix?

When a bug is fixed in HEAD, it is sometimes interesting (or necessary) to backport the fix to the maintenance branch. This is typically only done for critical bugs, since milestone builds undergo less testing and stability is the most important factor for the maintenance stream. The fix needs first to be modified in order to be applied on top of the maintenance branch's code. It may be easy or tricky depending on how the patch's code area has been touched in the branch.

  • Clone the bug, and mark the clone with the maintenance branch target milestone.
    • Q: Do we keep the cloned bug as bugzilla "depends on"? Do we attach a patch for the backport?
    • A: Yes, and yes.
  • Release the fix in the maintenance branch, and tag with the org.eclipse.releng project from the same maintenance branch
    • Q: Who is responsible for updating version numbers in the feature(s) containing a bundle which gets a new version due to a backport?

Contributing

Contributing a fix

There are several ways available to contribute a patch:

  • Via the Gerrit repositories: Resources Gerrit, Team Gerrit.
  • Forking the Git repositories, committing a fix, and requesting that a committer "pull" your change.
  • Attaching a patch in bugzilla. Use the "git format-patch" command to produce a properly formatted commit patch.

For more details see Development_Resources/Contributing_via_Git.

Note: All contributors must sign the Eclipse Contributor License Agreement.

Becoming a Committer

According to the Eclipse Project Charter, contributors who provide "frequent and valuable" contributions can have their status promoted to that of committer. Here are some things to look for when evaluating a contributor for commit rights

  • A strong track record of contributions that have been committed into our code base. Since it is difficult to evaluate the quality of a contribution on a bug that has not been committed, the focus is on evaluating the body of committed contributions. Size and complexity of contributions is more important than raw number of contributions. One major new feature is more interesting than a dozen fixed javadoc typos
  • Active participation in other aspects of the project - mailing list discussions, reporting, triaging, and evaluating incoming bugs, writing tests, documentation, etc.
  • Strong technical programming skill
  • Ability to negotiate and find consensus with other committers on changes

Committing to Git

What comment should I associate with a commit?

The comment of a commit should be of the form: <bug number and title> [optional comments]
Example: Bug 210770 Add IResource#HIDDEN and support for adding hidden projects.

  • Q: May it also be [210770] Add IResource#HIDDEN and support for adding hidden projects?
  • A: No, the releng tool to send E-Mail about released changes only understands the "Bug nnnn" syntax, which has the additional benefit of being available by direct copy-and-paste from the respective Bugzilla headline.
  • Q: What if two bugs are associated with the same commit?

What else should I do when I commit a change?

When you commit a change, you should:

  • Mark the corresponding bug fixed. Trivial changes in HEAD don't need a bug report.
  • Ensure the copyright statement is updated based on the source of the contribution. Mark the iplog+ flag in the bug report if applicable
  • Run the test suites for the corresponding project (not necessary for trivial changes)
  • Q: How do we do New&Noteworthy's?
  • A: 1 week before a milestone, an E-Mail is sent asking for new&noteworthy contributions. Committers who added significant changes in a milestone are requested to create a respective N&N item after coordinating with their component lead.

Can I release code during the milestone week?

  • Initial answer is: NO
  • The milestone stream has to stay clean until the milestone is declared. This enables us to fix a stop ship bug and contribute again without introducing any other changes.
  • Once our team has signed off on a milestone candidate, we can reopen the stream for development

Can I release code during the build input?

  • Again, the answer is: NO
  • The build input is prepared between 6-10 PM EST on Monday prior to the regular Tuesday integration build. Please avoid making contributions during this time.
  • If you release a change after this period, you need to perform a separate build contribution for your change.
    • Q: Huh? What is "perform a build contribution", is this equivalent to "release to the mapfile"?

Bugzilla

What is the Platform/Workspace bugs life cycle?

Roughly, NEW bugs are untriaged bugs. This means they are bugs that we have not yet reproduced, or we don't yet believe they are actually bugs. Once we can reproduce a bug, or have other evidence to believe a bug is real, it is marked ASSIGNED. Bugs ASSIGNED to the inbox are bugs that we believe are valid, but haven't had time to address (this is a good place to look if you're interested in making a contribution). Bugs assigned to a committer/contributor are bugs that person plans to fix. Bugs are marked FIXED if there was actually a code change committed to resolve the problem. If the bug is no longer reproducible but no code change was made to address it, it can be marked INVALID or WORKSFORME. We rarely use the VERIFIED state because the vast majority of fixes are verified through an additional automated test (and are therefore verified every time there's a build).

For details and queries, see Eclipse/Workspace/Bugs.

What bugs are currently opened against Platform/Workspace?

Q: The P5 prioritization for deferring stuff to the future seems orthogonal to this, I was not sure how to use it in the queries. I also wasn't sure whether Platform/Runtime component is for the Workspace team.

What target milestone should be used?

A target milestone indicates a firm intention by a committer to fix a bug for a particular date. You should only set a milestone on bugs assigned to you, that you believe you can reasonably finish by that milestone. Of course this is not a guarantee, and milestones often end up slipping. Often for small bugs we only set the target milestone when marking the bug fixed. No bug should be marked FIXED without a target milestone.

What comment should be used when fixing a bug?

Describe the fix that was made and the tests that were written. This is a useful place to record any tricky issues with the fix, since the bug report will be linked to the commit in Git, and a committer may come back to bugzilla years later to figure out the context for a change. You can also mention what stream the fix is in, although this can be inferred from the target milestone.



Release engineering

Releasing code to the integration builds is done using the Releng Tools plugin (org.eclipse.releng.tools). This plugin can be installed from the Eclipse project repository that is available in your install already (go to Help > Install New Software). The release procedure is as follows:

  • Load all of the latest plugins and tests from HEAD
  • Run the automated tests
  • Right-click the projects to release (including tests), and select Team > Release
  • Follow through the release wizard. Make sure you check the box to generate build notes
  • Copy and paste the generated build notes into an email
  • Finish the release wizard
  • Once complete, send the build notes email to the platform-core-dev mailing list.

Misc

How do I get the Core tools?

The core tools bundles have some interesting tools for diagnosing problems and doing performance analysis on the resource tree, listeners, etc. The best way to get the core tools is to check them out from eclipse.platform.resources.git directly, and then build and install them. You need these bundles:

  • org.eclipse.core.tools
  • org.eclipse.core.tools.resources
  • org.eclipse.core.resources.spysupport

There is more information on what's in the core tools on the core downloads page. The downloads are out of date, but the information on what's in the tools is still relevant.

  • Q: How do I run Performance tests?
  • A: Best have the Performance tests run for you on the dedicated performance test machines - otherwise the risk is high that other processes interfere with your measurement. Performance tests are usually run every Tuesday on I-builds and every Saturday on N-builds. Your tests need to be hooked into the proper Performance test suite - check the test.xml file for your test bundle. In the case of resources, the suite is org.eclipse.core.tests.resources.perf.AllTests.
    • In order to be able and compare a new performance test against a baseline from the previous release, you'll need to commit and release into the respective previous release's performance baseline branch (for Eclipse 3.5.x, this is perf_35x).

An integration or maintenance build is red. Should I take it?

A red build doesn't mean that it is not usable. It just means that some tests failed. The impact of failing tests is often negligeable. E.g. if the releng tests are failing, it just means that there is a problem in the Javadoc. So you should always take the latest integration or maintenance build, unless someone posted on the platform-releng-dev mailing list that it is not usable.

  • Q: How to review logs etc from nightly builds done by the Eclipse Releng team, in case a build is red due to my contribution?
  • A: Just follow the hyperlink for the build, click on the red "test results" and click on any red number related to your component. Scroll down to "Failure" to see the exception logged. Console output logs are available from the main tests page (clicking "test results" from the main download page), separated for each scenario and host run.

What about contributions by non-committers?

The Eclipse project uses the Eclipse Foundation's Automatic IP Log system. There are three categories of interesting content for the IP log:

(1) "Small" contributions (patches) coming from non-committers. For this, you must ensure the Author field of the Git commit is set to be the contributor. This will enable the Eclipse automatic IP log tool to record the contribution. For more details see Development_Resources/Contributing_via_Git.

(2) "Large" contributions (code > 250 lines, new feature work) coming from non-committers. For this, remember that it has to go through the proper IP review process with the Eclipse Foundation through IPZilla.

(3) Any new, updated (i.e. new versions being used), modified (i.e. we modify the code) or removed dependencies on third-party code, usually on bundles that reside in Orbit. This also has to go through the Eclipse Foundation IP review process.

"Non-committer", in this context, is defined as: anyone who is not a committer on the Eclipse project (Platform, JDT, PDE) at the time they make the contribution.

Links