Eclipse/Workspace/Committer FAQ

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:

• eclipse.platform.resources.git (browse, stats, fork on OrionHub)

• eclipse.platform.team.git (browse, stats, fork on OrionHub)

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?

• Untriaged bugs (NEW or UNCONFIRMED state)
• Assigned bugs (ASSIGNED except to Inbox)
• Deferred bugs (ASSIGNED to Inbox)

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 > 1000 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.