Sequoyah Contributor Howto

You can help the Sequoyah Project by filing bugs and enhancement requests or answering questions on the newsgroup and mailing list. But of course you can also contribute code.

If there is a particular bug you are interested in fixing, then let us know on the mailing list. We can give you suggestions on how to proceed, and we can let you know if anyone else is currently working on that bug.

There is a weekly open conference call for contributors to Sequoyah Project, feel free to contact members of Sequoyah team to get the details.

You can also follow our RSS Feeds and Wiki updates.

Bugs

If you find a bug, log it. If you find a bug that you think is a duplicate, is not a bug, etc. feel free to comment saying so.

• 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 at least 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 svn, 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

You can also:

• See the Bug Process Page for bugzilla queries to find interesting bugs, and our general bug process (handling bugzilla states and priorities)

• When you check in a fix for a bugzilla entry, please include the bugzilla number in the commit message. Example: "[139207] Fix browsing into tar archives by framework".

• After committing a fix for bugzilla, set the entry FIXED. Do not set it closed until it has been tested and verified by somebody else.

Contributing Code

Whether you're wanting to fix a typo in javadoc or to implement the next big bang feature for Sequoyah you'll need to know a few things before you contribute code.

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

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.

Coding Conventions

We do not want to be too restrictive right now - especially do not rewrite existing code just to make it conform to some naming convention. Most of the Sequoyah code seems to follow proper coding style already. In the end, well want to produce code and APIs of Eclipse Quality. Therefore, we better strive for quality early. Which means, try to follow common accepted guidelines for writing new code

Some useful references are:

• The Eclipse Platform API Central
• The Eclipse Platform's Standards, Conventions and Guidelines

Some best practices are:

• Use "organize imports" (Ctrl-Shift-O) to clean up the imports.
• The copyright header goes before the package declaration, starting in the very first line. For new files, follow the pattern from other existent files in the project. For changed files, add a contribution comment in the copyright header with your name and affiliation, and a bug id.
• It is considered good practice to write code that does not have warnings. If possible, fix warnings existing whenever you see them, they can crop up due to compiler changes occassionally.
• Non-externalized strings are considered errors, do not ship non-externalized strings.
• Write/update Javadoc for all API you introduce/change. See Evolving Java-based APIs by Jim des Rivières to understand what it means to maintain an API.

Before You Check In

• Commit comments are required for all code commits, bugs should be logged to track work and the bug number and a description is then used in the commit comment to describe the change. For example when fixing a bug, use: "[bug_number] Bug description".
• Before committing changes, catch up to all changes made by others.
• Don't commit your changes if this will cause compile errors for others.

Creating a Patch

To contribute a patch, first be sure you have the latest version of the code from our repository at SVN. Implement your modifications and save the file(s). Right-click on the package you are editing, go to Team -> Create Patch and follow the wizard. Then, attach this file to the bug. Finally, commment in the bug entry what are your modifications.

Mailing List

We try to be prompt and responsive on the mailing list but there's always room for improvement. If you know the answer to a query feel free to respond.

Wiki

The wiki is open and can be edited by all. If you find a typo, a broken link, or anything that you view as a small issue feel free to fix it. If wanting to contribute a significant amount of information or create a new article we request that you log a bug so that we're aware of what you're contributing. This is so that we can ensure consistency structurally and in the message conveyed.