TmL Committer Howto

While we do not want to get too process-heavy, there are a few simple things that will make all our lives easier. Here are a few "howto..." cookbook-style instructions for performing typical committer tasks.

If you need any background information regarding these instructions, look at the committer guidelines.

How do I...

Properly check my code before checkin

  • Ensure that you have Compiler Warnings switched on as recommended. For every file that you modify, please ensure that it compiles without warnings before you check it in.
  • Keep the Code Ownership Page up-to-date on the Wiki.

Format my checkin comment

There are tools available which build a MySQL database of all CVS checkins and allow searching it, or even associate checkins with bugzilla bugs in order to generate release notes: for example see the EMF Search CVS and EMF Release Notes.

At the TmL project, we'll want to make use of these tools as soon as possible. In order to associate cvs checkins with bugzilla, these tools need the bug id properly formatted in the checkin comment. Multiple formats are supported, but this is the preferred one (see also bug 164719 and this e-mail):

  • All checkin comments should be formatted like this:
        [123456] fixing ugly images
        [123456] apply patch from Ewa Matejska for remotecdt-over-dstore

    Where the number [123456] references a bugzilla number, of course. Checkins that fix multiple bugs should have the various bug numbers listed on a separate line of the checkin comment each.

Work with bugs and fixes

  • See the Bug Process Page for bugzilla queries to find interesting bugs, and our general bug process (handling bugzilla states and priorities)
  • Test your fix once to verify that it actually works - if this is not too difficult. You may also place a note on the bugzilla report, asking the original submitter to verify.
  • Ideally, write a JUnit test to make sure the bug will not creep in again (may not always be applicable).
  • Commit your fix, adding the bugzilla number to the commit message. Example:
    • [139207] fix browsing into tar archives by dstore
  • Set the bugzilla report FIXED and verify that the bugzilla Target Milestone reflects the version that your fix is about to go into. The bugzilla comment along with the state change should include some help that allows a reader to understand what was done. Some good examples:
    • Fixed by correcting id in files.ui/plugin.xml
    • Fixed in SystemViewPart and other *ViewPart files by using common action handler
    The comment in bugzilla should be short enough so that it is not much effort creating it. But long enough to help a later reader find the corresponding change in cvs, and/or get some idea what the problem actually was and what was done about it:
    • In case a single file was changed, a reference to the filename is sufficient
    • In case multiple files were changed, the most dominant file is often sufficient
    • In case lots of files were changed, the plugin or the component is fine

Apply a patch from an external contributor

  • Ensure that the patch is on bugzilla. If not, ask the contributor to create a bugzilla entry. This is requird even for patches from co-workers in your own company!
  • Contact the contributor and ask the following (see the Eclipse Legal Poster):
    • If this is the first time the contributor makes a contribution: Contact information for IP records - Name, Company, E-Mail, Office address, Office phone.
    • Did you write the contribution yourself?
    • Did you reference any 3rd party material?
    • If yes, under what terms (license) did you receive this material?
    • Are you authorized by your employer to make the contribution?
    In the typical case (no IP problems expected), the contributor should put a message like the following on the bugzilla report that holds his/her patch:

    Legal Message: I, {name}, declare that I developed attached code from scratch, without referencing any 3rd party materials except material licensed under the EPL. {I am authorized by my employer to make this contribution under the EPL.}

  • Apply the patch in a test workspace, and review the code for any obvious traces of copyright breaches, blasphemy or "bad words". It makes sense to have a separate workspace for applying patches only, such that your current work on other things is not affected negatively.
  • Collaborate with the contributor (i.e. exchange e-mails) until the patch satisfies your needs. Doing so educates our contributors, keeps the process transparent, and takes work off committers:
    • Patch works on HEAD (if not: ask contributor to re-base and re-submit the patch)
    • Contributor''s name added to the Copyright section of all modified files
    • Coding style appropriate
      • .
  • If the contribution is more than 250 lines of code and the contributor is not from your own company, or there is any uncertainty about licening and purity of IP and copyrights: fill out a Contribution Questionnaire (available from the committer tools)
  • Once IP due diligence is completed: Apply the patch and commit it. Do not make local modifications between applying and committing, in order to keep the process transparent. Put the bugzilla number on the commit message.
  • Add a line describing the contribution to the tml-log.csv Project Log, see below.
  • Add the keyword contributed to the bugzilla report that the patch came from. Verify that the bugzilla Target Milestone reflects the version that your fix is about to go into, then set the bugzilla report to FIXED.

Edit the TmL Project Log (tml-log.csv)

  • The Project Log is required as per the Eclipse Project Log Guidelines. It records every non-committer-contribution (including legacy code contributions). Please keep it up-to-date.
  • For counting lines of code see the section below.
  • Commit the changed tml-log.csv file.

Count lines of code in a contribution

  • For Eclipse IP review bookkeeping, we need to count lines of code in contribution, INCLUDING xml files, documentation, readmes, property files and so on. Most known code counters do not fulfill these needs. The simple shellscripts below count all lines of all text files except empty lines.
  • We optionally also suppress lines that only contain whitespace, empty comments or {} charactes. This is in order to account for different coding styles, which might prefer to have the { characters on a separate line or not.
    • '

Add some legacy code to the project

  • Obtain PMC Member Approval: Write an e-mail to dsdp-pmc@eclipse.org, describing the intended contribution. Give the PMC an idea of how large the contribution is, what it is good for (cryptography?), and if there are any other licenses than the EPL involved.
  • PMC Member Approval should be returned by E-Mail.
  • Create a Bugzilla Entry holding the contribution in a form that is suitable for checkin. A ZIP archive of all the files/projects affected is fine.
  • Fill in a Contribution Questionnaire (available from the committer tools) and wait for EMO approval.
  • Once approved, check in the contribution. Dont forget to add the bugzilla number on the commit message. Commit the code verbatim as from the bug entry first, and make any necessary modifications later.
  • If project(s) were added, update the *.psf Project Set Files (see below).
  • Add a line describing the contribution to the tml-log.csv Project Log, see above.

Add a plugin or other project to the workspace

  • Commit your modifications.
  • Send an E-mail to dsdp-tml-dev, informing everybody that team project sets have been updated with your new plugins.

Find missing or incorrect Copyright notices in my code and fix them