Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "JDT Core Committer FAQ"

(What should I do to backport a fix?)
(Misc)
Line 223: Line 223:
 
=== 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? ===
 +
As of 20071121, the Eclipse project moved to an ever more on-demand IP process to take care of external contributions.
 +
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.
 +
For the IP log, we need to know about three things:
 +
 +
(1)  "Small" contributions (patches) coming from non-committers. For this,
 +
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
 +
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 (Equinox, Platform, JDT, PDE) at the time
 +
they make the contribution.
  
 
==Links==
 
==Links==

Revision as of 03:23, 22 November 2007

Contents

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?

This FAQ is about the rules that JDT/Core committers follow when developing the JDT/Core 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?

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.

Coding

Where is the JDT/Core code?

All the JDT/Core code is in the Eclipse CVS repository. The JDT/Core projects are:

  • 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?

The following information must be used to create a CVS repository connection:

  • 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)
  • Password: <your password>
  • Host: dev.eclipse.org
  • Repository path: /cvsroot/eclipse
  • Use default port

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.4.
  • R3_x_maintenance: used for the maintenance of a release. For example, R3_3_maintenance is currently used for the development of 3.3.1.

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. If you are not sure, use the Eclipse [built-in] formatter profile which is very close to the JDT/Core team's formatting style.

What should I do to backport a fix?

When a bug is fixed for next milestone in HEAD stream, it is sometimes interesting (or necessary) to backport the fix in the maintenance stream. The fix needs first to be modified in order to be applied on top of the maintenance stream code. It may be easy or tricky depending on how the patch's code area has been touched in the branch.

When the fix is ready, you have to:

  1. Reopen the bug and set its target to the corresponding maintenance target (e.g. 3.3.1) (Note that this also must be done for all duplicate bugs)
  2. Release the fix in the maintenance stream (e.g. R3_3_maintenance branch)
  3. Set the bug as FIXED adding the corresponding comment (e.g. Released for 3.3.1)

Be careful when maintenance stream is frozen and the bug has not been verified yet: you cannot immediately reopen the bug and change its target otherwise it would miss the milestone verification process in HEAD (see What is the milestone verification process?). So, in this case, before proceeding the steps above, you first need to:

  1. Set the bug's Status Whiteboard to "target 3.x.y" (e.g. target 3.3.1)
  2. Wait for the stream thaw

Committing to CVS

How do I maintain the build notes?

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?

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?

Initial answer is: NO

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 verification process.

However, looking at milestone history, re-contributing seldom happened, so if this is really necessary and only for HEAD stream, code releases are allowed if the verification process has well finished and the stream reopened for development.

See also What should I do if I need to contribute after the verification was finished? question...

Can I release code during the build input?

Again, the answer is: NO

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.

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 safe 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!

How do I warn users after I changed the build state version or the index file version?

Changing the build state version org.eclipse.jdt.internal.core.builder.State#VERSION will cause a full build when the user restarts the workspace with the new version. As well changing the index file version org.eclipse.jdt.internal.core.index.DiskIndex#SIGNATURE 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:
<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>
  • If the index version is changed, you can add the following entry:
<li>Fix for <a href="http://bugs.eclipse.org/bugs/show_bug.cgi?id=?????">bug ?????</a> required the index version to be incremented. 
    Indexes will be automatically regenerated upon subsequent search queries (accounting for indexing notification in search progress 
    dialogs).
</li>

Bugzilla

What bugs are currently opened against JDT/Core?

Bugs opened and not resolved yet.

What target milestone should be used?

  1. If the bug is marked as WORKSFORME
    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)
  2. If the bug is marked as DUPLICATE,
    a) if the original bug has not been fixed yet, don't set the milestone on the duplicate (it will be set when rule 6 is applied)
    b) if the original bug has been verified, use either rule 1a. or rule 1b.
    c) if the original bug has been set to WONTFIX or INVALID, use next milestone (rule 3).
    d) if the original bug has been fixed in the maintenance stream but not verified yet: then you should set the target to same target than original bug
  3. If the bug is marked WONTFIX or INVALID, use the next milestone (in this case, the target is simply used to identify that the bug has been closed during this specific period...)
  4. If the bug is marked FIXED, use the next milestone (as we always do)
  5. If a bug is backported to a maintenance stream, then see What should I do to backport a fix? question for more details
  6. In all cases, go through the duplicates of the bug being resolved, and set these duplicates with the same milestone as the one used for the bug being resolved (Note that none of the duplicate bugs should have their target set)

What comment should be used when fixing a bug?

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?

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?

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?

  • If the original bug is marked RESOLVED/FIXED, leave it to RESOLVED/DUPLICATE
  • If the original bug is marked VERIFIED/FIXED, change it to VERIFIED/DUPLICATE

When can I set a bug to VERIFIED?

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?)

Release engineering

What steps should I follow to make a build contribution?

  1. Ensure that you are in sync with the stream (HEAD, R3_x_maintenance, ...) you want to contribute to.
  2. Close the build notes using the JDT/Core tool (right click on the file, then JDT Core tools > Close build notes).
  3. Commit the build notes.
  4. Tag all JDT/Core projects (even those that haven't changed) with the current version (found in the build notes), eg. v_810
  5. If needed, check out org.eclipse.releng from the stream you want to contribute to.
  6. Edit org.eclipse.releng/maps/jdtcore.map:
    1. Change the contribution date
    2. Change all version numbers to the new one
  7. Commit org.eclipse.releng/maps/jdtcore.map
  8. 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?

The verification of a milestone is made of two main phases:

  1. bugs verification
  2. build test usage

What is the bugs verification phase?

What are the bugs I have to verify?

All bugs fixed in the milestone's stream must be verified the week of the milestone delivery.
(this is why setting the correct target for bugs is really important - see What target milestone should be used?)

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.

For example, the following bugzilla requests were used to follow the verification progress for milestone 3.4 M2:

all bugs to verify: all bugs request
bugs that Frederic must verify: verifier's bugs request

When do I have to verify my bugs?

Usually this verification starts as soon as you get your bugzilla request and a warm-up build is available on Eclipse Project Downloads page.

Note: The corresponding milestone stream is frozen until this verification is finished (see When can I consider the verification finished?)

How do I verify my bugs?

For each bug of your list:

  1. 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 and the bug is really a duplicate of the original
    • WORKSFORME
      the problem described in the bug does not occur using the milestone build
    • INVALID
      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
  2. Modify the bug according to the result of your verification:
    • if the verification is OK:
      • add a formatted comment to the bug: Verified for <current verified milestone> using <build name> build.
      • set the bug Resolution to VERIFIED if the target matches the current verified milestone
      • set Status Whiteboard to the formatted string: Verified for <current verified milestone> if the bug's target matches another milestone
    • 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
When can I consider the verification finished?

When all your bugs are verified, wait for the email sent to all team members and to the jdt-core-dev@eclipse.org list. This mail describes the status of the verification and indicates which JDT/Core version is eligible for the milestone. You are also informed whether the corresponding stream is reopened for development or not.

Here's a sample of the email sent at then end of the 3.4M2 verification

Version v_813 of org.eclipse.jdt.core project should be the JDT/Core contribution for 3.4 M2 milestone...
So you can consider JDT/Core projects HEAD reopened for development :-)

What should I do if I need to contribute after the verification was finished?

Do NOT panic ;-)

The process depends whether the stream was modified since the last version or not:

  • when no change was done in the stream:
    1. 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
    2. release your fix
    3. do a build input with version v_NNN+1 (see What steps should I follow to make a build contribution?)
  • but if some code was already released in the stream since the last version:
    1. if not already done, create a branch which identifies the milestone, e.g. zz3.4M2
    2. release the fix in this branch
    3. do a build input with version v_NNN+1 (see What steps should I follow to make a build contribution?)
    4. backport the fix into the milestone stream
    5. 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?

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)

Misc

How do I get the JDT/Core tools?

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.

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.

What about contributions by non-committers?

As of 20071121, the Eclipse project moved to an ever more on-demand IP process to take care of external contributions. 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. For the IP log, we need to know about three things:

(1) "Small" contributions (patches) coming from non-committers. For this, 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 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 (Equinox, Platform, JDT, PDE) at the time they make the contribution.

Links

Back to the top