Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Handly/Committer FAQ
Notice: the information on this page might have been outdated.
Meta FAQ
Who is this FAQ for?
This FAQ is for the Eclipse Handly committers, and anyone who is willing to participate in the development of the Eclipse Handly project.
What is this FAQ about?
This FAQ is about the rules that Eclipse Handly committers follow when developing the project.
How do I contribute to this FAQ?
Simply edit this page. You will need to log in using your Eclipse account. If you don't have an Eclipse 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 handly-dev@eclipse.org with the diff url so that every Handly committer is aware of the change.
Coding
Where is the project code?
All of the project code is in the following Eclipse Git repository:
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 major or minor release.
- M.N.x: used for the maintenance of a release. For example, 1.0.x is used for the development of 1.0.1, 1.0.2, etc.
How do I set up a development workspace?
See the Handly Contributor Guide for instructions on setting up a workspace for Eclipse Handly development.
How should I format my code?
Import into your workspace the formatter profile from the project's repository: tools/formatter.xml. Then, just hit Ctrl+Shift+F. Javadoc comments are not formatted, but just ensure they have reasonable line breaks. See additional development conventions here. Please pay due attention to the required legal documentation, including the copyright and license notices.
Contributing
Contributing a patch
In general, there are several ways available for non-committers to contribute a patch:
- (Preferred) Via the Gerrit repository: Eclipse Handly Gerrit.
- Forking the Git repository, 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 Contributing via Git.
Note:
- All contributors must sign the Eclipse Contributor Agreement (ECA).
- Make sure that new files contain the required copyright and license notices.
- For each changed file update the copyright date and append the words "and others" after the initial copyright owner (if necessary), fill out this template and add it to the copyright header:
Your Name <email@example.com> - Bug Title - https://bugs.eclipse.org/BUG_NUMBER
Becoming a Committer
According to the Eclipse Development Process, 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
Merge or Rebase?
We use rebase as a team policy to keep the history flat and readable. Never rebase commits pushed to the project's public repository.
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 430177 - Handly Initial Contribution Initial code contribution for the Handly project.
Note: Contributions from non-project-committers must be properly signed-off. For more details, see Handling Git Contributions.
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).
Bugzilla
What is the project's 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 more details, see Bugzilla Use.
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.
Links
General
- Handly Contributor Guide
- Eclipse Development Resources
- Eclipse Development Process
- Eclipse Intellectual Property Due Diligence Process
- Legal Documentation Requirements