Difference between revisions of "Mylyn/Contributor Reference"

From Eclipsepedia

Jump to: navigation, search
(Committers)
(Conventions)
Line 3: Line 3:
 
[http://www.eclipse.org/eclipse/development/index.php eclipse dev], [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.mylyn/?root=Tools_Project ViewVC], [http://dev.eclipse.org/viewcvs/index.cgi/www/mylyn/?root=Eclipse_Website ViewVC for Mylyn Web]
 
[http://www.eclipse.org/eclipse/development/index.php eclipse dev], [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.mylyn/?root=Tools_Project ViewVC], [http://dev.eclipse.org/viewcvs/index.cgi/www/mylyn/?root=Eclipse_Website ViewVC for Mylyn Web]
  
== Conventions ==
+
== Getting Started ==
 +
 
 +
For ideas on how to contribute see the following lists of bugs and comment on any that interest you, or send a message to mylyn-dev on ways that you would like to get involved:
 +
* '''[https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced&short_desc_type=allwordssubstr&short_desc=&product=Mylyn&long_desc_type=allwordssubstr&long_desc=&bug_file_loc_type=allwordssubstr&bug_file_loc=&status_whiteboard_type=allwordssubstr&status_whiteboard=&keywords_type=allwords&keywords=bugday&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&emailtype1=substring&email1=&emailtype2=notregexp&email2=&bugidtype=include&bug_id=&votes=&chfieldfrom=&chfieldto=Now&chfieldvalue=&cmdtype=doit&order=Reuse+same+sort+as+last+time&field0-0-0=noop&type0-0-0=noop&value0-0-0= bugday bugs]''': a short list of highly relevant bugs for getting started
 +
* '''[https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced&short_desc_type=allwordssubstr&short_desc=&product=Mylyn&long_desc_type=allwordssubstr&long_desc=&bug_file_loc_type=allwordssubstr&bug_file_loc=&status_whiteboard_type=allwordssubstr&status_whiteboard=&keywords_type=allwords&keywords=helpwanted&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&emailtype1=substring&email1=&emailtype2=notregexp&email2=&bugidtype=include&bug_id=&votes=&chfieldfrom=&chfieldto=Now&chfieldvalue=&cmdtype=doit&order=Reuse+same+sort+as+last+time&field0-0-0=noop&type0-0-0=noop&value0-0-0= helpwanted bugs]''': a longer list of all bugs targeted at community contributions
 +
 
 +
=== Conventions ===
  
 
All contributions to Mylyn need to be made using Mylyn since it links source changes to tasks and contexts, making open development and collaboration easier.  Using Mylyn ensures that:
 
All contributions to Mylyn need to be made using Mylyn since it links source changes to tasks and contexts, making open development and collaboration easier.  Using Mylyn ensures that:

Revision as of 23:32, 17 October 2007

See also: helpwanted bugs, discussion bugs, eclipse dev, ViewVC, ViewVC for Mylyn Web

Contents

Getting Started

For ideas on how to contribute see the following lists of bugs and comment on any that interest you, or send a message to mylyn-dev on ways that you would like to get involved:

  • bugday bugs: a short list of highly relevant bugs for getting started
  • helpwanted bugs: a longer list of all bugs targeted at community contributions

Conventions

All contributions to Mylyn need to be made using Mylyn since it links source changes to tasks and contexts, making open development and collaboration easier. Using Mylyn ensures that:

  • All Bugzilla reports have a corresponding task context, making them easy to reopen or pick up by you and by others.
  • All commits correspond to a single Bugzilla report, making it easy to navigate from changes to bugs.

Links

Workspace

The recommended way to work with Mylyn sources is by checking them out of CVS. Doing this makes it easy to try the latest changes and work with patches and ensures that you can easily browse the source code and documenation using Eclipse's facilities and avoids compilation problems such as PDE bug 157375.

Setup

Install Eclipse and get it configured for developing Java 5 applications.

  • Unless targeting a particular Eclipse release, download the latest Eclipse milestone release.
  • Associate J2SE-1.5 with your installed JRE via the Window -> Preferences -> Java -> Installed JREs -> Execution Environments. Note that to get rid of JRE association warnings you may need to download older JREs, e.g. from: http://java.sun.com/products/archive/

Checkout

The Mylyn CVS repository contains the following branches. Each can be checked via saving the linked .psf file locally, and then using File -> Import -> Team Project Set. Use username "anonymous" and an empty password. If you are only interested in parts of Mylyn, the additional projects can be deleted after the import. After the checkout you should have no errors or warnings from the Mylyn projects.

Note: these project sets specify anonymous pserver access. If that does not work for you see the CVS Howto.

Active branches:

  • HEAD: Mylyn 2.x stream for Eclipse 3.4 (latest milestone)
  • e_3_3_m_2_x: Mylyn 2.x stream for Eclipse 3.3 (branched projects updated with each release)

Maintenance branches: Not updated unless a severe defect is found, or a request is made with sufficient reason or patch.

  • e_3_2_m_2_0: Mylyn 2.0 stream for Eclipse 3.2
  • e_3_3_m_1_0: Mylyn 1.0 stream for Eclipse 3.3 (currently supports 3.3M4 only)
  • e_3_2_m_1_0: Mylyn 1.0 stream for Eclipse 3.2

End-of-life branches:

  • compatibility: required for building Mylyn 2.0, prevent org.eclipse.mylar plug-ins from loading
  • e_3_1: Mylyn 0.6 for Eclipse 3.1

Other:

  • Web site: for updating eclipse.org/mylyn
  • :pserver:dev.eclipse.org:/cvsroot/tools can be used for manual checkout

JUnit tests

Each component has it's own All<Component>Tests suite. If not familiar with running PDE JUnit tests, refer to the Eclipse Documentation.

  • Add a credentials.properties file to org.eclipse.mylyn.context.tests and put the following into it:
   user: <user>
   pass: <pass>
  • For <user> use "tests<at sign>mylyn.eclipse.org". For <pass> use "<project's name lowercase>test". If you have any trouble making this work email mylyn-dev@eclipse.org.
  • Add the following to the test configuration under Arguments -> VM Arguments: -enableassertions -Xmx384M

Test suites (in org.eclipse.mylar.tests):

  • AllTests: all of the automatic tests, should always pass, run as a JUnit Plug-in Test
  • AllStandaloneTests: do not require workbench, can run as JUnit Test, subset of AllTests
  • AllFragileWebTests: web connector tests, some templates may periodically fail

Manual tests

The manual tests can be found on the Mylyn Testing page.

  • Component owners are responsible for maintaining their respective manual tests and ensuring they are covered two days prior to release.

Trac Connector

Self-hosting

Self-hosting, also known as working bootstrapped (i.e. self-hosted) makes eating your own dog food easier and avoids having to update to dev builds.

The following is an example of how to set up a bootstrap workspace, using Eclipse 3.3 on Windows and a C:/Dev workspace directory as an example.

  • Create a new directory for your build workspace, e.g.: C:/Dev/build-e3.3
  • Launch Eclipse with this workspace, e.g.: C:\Apps\eclipse-3.3\eclipse.exe -data C:\Dev\build-3.3
  • Check out Mylyn from CVS into this workspace, see #Setup
  • Create a new Launch Configuration:
    • SelectRun -> Run... -> create a new Eclipse Application.
    • Call the application Mylyn Bootstrap.
    • On the Main tab, set the Location
      • You can use the existing workspace that you used Mylyn with previously
      • You can create a new workspace (e.g. C:/Dev/bootstrap)
  • Launching with this launch configuration will give you a second workbench with Mylyn. This workbench will be created based on the target platform (the workbench you're launching from) and the plugins in C:/Dev/build-3.3.
  • Do your development in the runtime workspace (C:/Dev/workspace).
  • Whenever your changes make it into HEAD that you would like to use, close your runtime workspace (C:/Dev/workspace), update from CVS in the build workspace (C:/Dev/build-3.3), and then re-launch your runtime workspace.

Notes:

  • The launching workspace will typically consume very little memory.
  • Working in bootstrap mode means you have the source code checked out at least twice, once to bootstrap Mylyn, and once to actually develop.
  • You must have two distinct workspaces, you can't bootstrap into the same workspace as you launch from.
  • It is possible to run in debug mode so that the changes apply to the workspace immediately after synch, but this can cause problems with the running workspace if classes change or go missing. This is because the hot-swap virtual machine can only change method bodies, not class definitions.

Contributors

Getting Started

  • Use Bugzilla for all of your communication. This helps committers track the contribution.
  • Before setting out to contribute to a bug report, post on the bug report describing your intention. This helps committers guide the contribution and avoids problems with patches going stale due to related work being done concurrently.
  • For contribution ideas see the list of helpwanted bugs to find one that interests you, file a new bug of your own, or email mylyn-dev for ideas.

Tips

Following these steps will help get your patches applied more quickly.

  1. Before implementing the functionality post a brief proposal of the implementation and UI changes/additions and get a committer's feedback.
  2. Post a patch to the core functionality with reasonable unit test coverage.
  3. After that's applied iterate on the UI proposal if needed and the post the patch to the UI.
  4. Note that the smaller you make patches and the more focused they are on individual and well-tested units of functionality the more quickly they will get applied.

Patches

Creating

  • Each patch should correspond to a single bug report, and a single patch should be made for each set of changes to be reviewed.
  • A task context should be attached to each patch to make applying and evolving it easier.
  • With few exceptions patches should be accompanied by a JUnit test, and in general unit tests are one of the most valuable and long-lived contributions. If you are having trouble writing a test (e.g. trickiness verifying what happens in the UI) comment on the corresponding bug report so that we can point you at similar test cases or consider extending the test harness if needed.
  • Minimize the amount of changes to existing code to make review easier.
  • Synchronize often to ensure you have the latest code. Once you start modifying resources, put the Synchronize view in Outgoing mode and press the Change Set button so that Mylar tracks the context for the patch.
  • Before creating a new JUnit test class class check the components test suite for similar test cases (e.g. AllTasklistTests).
  • Set the formatter by importing org.eclipse.mylyn/mylyn-settings-formatter.xml from the org.eclipse.mylyn project into Window -> Preferences -> Java -> Code Style -> Formatter. Format code using Eclipse's formatter (Ctrl+Shift+F) and ensure that no have been added.
  • Add an @author tag to each class that you create or make significant modification to, placed below any existing author tags and indicating the bug, e.g.: @author Rob Elves (bug 160315)
  • Ensure that there is no console output. For logging errors use MylarStatusHandler.

Submitting

  • Ensure there are no build errors, warnings, and that org.eclipse.mylar.tests.AllTests passes.
  • Do not include binary files such as GIF icons in the patch, they need to be attached separately.
  • Synchronize using Incoming mode and ensure that there are no conflicts, and merge them locally if there are.
  • Right click the task context change set (or the project containing the patch--patches should be made for a project, not a file), press Team -> Create Patch and select Save to clipboard.
  • In the Attachments section of the Task Editor select Attach File... and use Clipboard as the source. Check off the Patch and Attach Context checkboxes in this wizard page.
  • Add a description of issues addressed and comment on what testing was done to validate it (e.g. unit test coverage, manual tests performed). Also indicate any changes made to the existing UI in the comment (e.g. reordering of menu actions). Also indicate if patch is intended to resolve bug report or further work is required.

Writing Tests

Writing tests along with patches is key to ensuring that it is possible for committers to maintain the new functionality added by the patch. When writing tests look for the All<component>Tests class in the tests plug-in for that component, identify a test that is similar to the functionality that you are adding, and use that test as an example of how to add additional coverage. Tests can sometimes take longer to write then the change itself, but a committer will always be willing to assist you in designing the test or extending the mock test harness to make it easier to write.

The key things to ensure is that your test covers is the addition or change to the existing functionality. For API changes it is often sufficient to have the public method covered. When writing tests for UI components, the simplest way of testing will often involve a combination of unit and black-box testing, for example, relying on other parts of the Mylyn UI to be set up (e.g. the Task List view). Consider the case of adding functionality for pre-selecting a repository in the New Task dialog, writing a test can take the following form (refer to NewTaskWizardRepositorySelectionTest):

  • Create a mock repository
  • Add a task to the mock repository
  • Set the selection on the Task List (new functionality uses this selection)
  • Invoke the wizard and assert that the selection was set correctly on the viewer (wizard is a black box, all we care about is the contents of the viewer)
  • Dispose the wizard dialog, remove the mock repository and the mock task

When writing UI tests note that asynchrous updates, such as refresh, can make testing challenging. Note that several UI components have a method on them to set synchronous execution for the purpose of testing, and if such a method is lacking it can be added.

Graphics

If contributing a feature with icons or other graphics feel free to ask a committer to generate the graphic for you. If interested in contributing graphics you can find all of the source files (e.g. Photoshop) here: org.eclipse.mylyn/graphics/ui.

Committers

The Eclipse Charter explains how developers can gain commit rights.

Participation

Committers should:

  • Sign up for all of the project mailing lists.
  • Read the newsgroup regularly, and respond to posts in their area of expertise.
  • Respond to mylar-dev email in their area of expertise.
  • Watch and update all wiki pages related to components that they contribute to.

Communication

Mylar committers are required to follow these communication guidelines. Our philosophy is that the user is always right, even if it takes time to figure out how or why they are right. Our project thrives on the feedback of users, whether they are seasoned experts or newbies. Feedback defines how the tool should work, how it should be simplified, and how it should evolve.

  • All feedback contains information, and it is the responsibility of committers to turn that information into actions. This can mean improving the implementation, simplifying the workflow, clarifying the documentation, or noting a duplicate request. Making the actions we take clear helps communicate this philosophy to our growing user community and encourages high-quality feedback.
  • If users do not provide enough information or do not take the time to provide accurate information, they should be prompted to provide the necessary details. If they do not do so in a timely manner, the feedback is incomplete and can be resolved without taking action.
  • Always show respect to others in the community, whether they are making correct or incorrect assumptions about the tool or technology. When they are making incorrect assumptions it is because we have not done our job well enough, or because the platforms we build on are making it hard for us to do our job well enough. Identifying those cases is important so that we can provide feedback to those platforms and find work-arounds.
  • Never turn feedback or discussion away by flaming, being condescending, short, or insulting in any community communication forum. Forms of humor that work for face-to-face communication, such as sarcasm, should be avoided because they result in misinterpretation, especially when there is a language or cultural barrier. Use of emoticons is not a work-around.
  • Review public communication before sending. Things that are not meant to be intentionally disrespectful can come across that way. When reviewing try to shorten in order to show respect for your audience's time.

Bugzilla

  • Any user-reported bug should be resolved by one of: code improvements, documentation/FAQ improvements, or being marked a duplicate of another bug. All but the last require attaching a context.
  • Be judicious in marking bugs for LATER, because this typically communicates that the bug will never be resolved. Do this only if the bug does not fit in with the current scope of the project but is related to the mission. Otherwise mark P4/P5 and "helpwanted" to encourage a contribution that is not part of our current prioritization and plan.
  • When naming bugs, try to describe the use case or problem instead of the implementation unless there is no ambiguity in how the fix should be implemented. If the implementation approach helps with queries append it.
    • Bad: task list working set
    • Good: support nesting top level task list elements, e.g. via working sets

Severities:

Keywords:

  • helpwanted: bugs that are beyond the current priorities for the project. Note that some bugs marked for an upcoming milestone can be marked as helpwanted. This indicates that the project committers would like to see the bug solved for the milestone and will actively contribute to a solution, but that the bug is more likely to be fixed in a timely manner with the help of additional contributors.
  • bugday: these are a special category of helpwanted bugs that are intended to be mast accessible or rewarding for new contributors interested in helping the project to tackle. See the Bug Day FAQ for more information. In order to keep this list focused on the most relevant bugs it is capped at 24 and should be reviewed periodically.

Feature Maturity

Mylyn features vary in UI maturity and availibility of support. The following is a guideline for what it takes to move from experimentation through to maturity. (Note that this is partially based on the Eclipse project lifecycle and could converge further with that lifecycle if Mylyn were split into a separate incubation project or subprojects.)

Mature: packaged Eclipse downloads and available via main update site

  • UI quality: Eclipse SKD features have set a very high quality and UI consistency bar that needs to be met in order to make it possible to improve users' productivity with Eclipse.
  • UI simplicity: the Mylyn project's goal is to simplify and streamline the user experience. A simple and self-evident UI also helps ensure a manageable support burdeon on the component.
  • Availability of support: the feature must have an owner or organization with a long-term commitment to the quality of the feature and the ability to provide responsive support for feedback on that feature.
  • Responsiveness to feedback: the feature owner and other contributors must process and prioritize user feedback and respond to the highest priority needs in a timely manner (e.g. blockers and critical bugs need to be fixed within one release of being submitted, key enhancements help the feature evolve to meet users' needs).

Incubation: available via the Extras update site

  • High quality components that meet most but not all of the above criteria. To graduate, sufficient community feedback must be available on the quality and usability of the component (e.g. 100+ resolved bugs) and committers must vote to determine whether component meets the UI quality and simplicity guidelines.

Sandbox: available via the Extras update site

  • Unsupported components used for experimentation and not intended for daily use.
  • Community interest and contributions determine which experimental features move from the Sandbox into Incubation.

Applying Patches

  • Make sure to update mylyn-iplog.csv with an entry for each bug that is resolved by patch. Note that each patch should not contain more than 250 lines of code of unique and seprately usable functionality. For larger patches we need to invoke the IP Review process.
  • Contributors frequently write quick patches in order to get something working for them. It is the responsibility of the committer to either encourage the contributor to improve the modularity and test coverage of the patch or to do those themselves if this aligns with the projects' priorities. Failing to do so can reduce the overall quality of the code and failing to get sufficient test coverage reduces our ability to evolve the code.

Web site authoring

  • Create a new CVS location: :pserver:dev.eclipse.org:/cvsroot/org.eclipse
  • Check out www/mylar as a project
  • To push documentation from org.eclipse.mylar.doc to the web site use the targets in mylar/build.xml

Building a distribution

  • Using PDE Build support to create a Mylar distribution from HEAD, using a plain Eclipse 3.2
    • org.eclipse.mylar-feature/feature.xml -> Overview -> change version number to current date (e.g. 0.4.7.v20060125-0800)
      • On Plug-ins tab -> Versions... -> Force feature version into plug-in and fragment manifests
      • Repeat above for org.eclipse.mylar-bugzilla-feature.xml
    • org.eclipse.mylar-site/e3.2/site.xml
      • Delete old features (grayed out)
      • Add new mylar-bugzilla and mylar features
      • Hit Build All (if this fails restart Eclipse and try again)
  • To install, add the path of org.eclipse.mylar-site/e3.2/site.xml as a local update site
  • Bugzilla support can be built independently of the Mylar UI by checking out the following projects mylar.bugzilla.core, mylar.bugzilla.ui, mylar.tasklist, mylar.core

Merging and building the 3.1 branch:

  • Right-click the org.eclipse.mylar.java, mylar.ide, and mylar.xml project, Team -> Switch to Another Branch..., then Refresh the Branches and select e_3_1
  • The list of files that should not be overwritten is in: org.eclipse.mylar-site/merge.text

Deploying:

  • Instructions are in org.eclipse.mylar-site/release.txt

Sandbox

The sandbox is a set of CVS projects and feature contributors use for experimentation. These features are not intended to be used for daily development. Sandbox features include experimental connectors and bridges, experimental UI features, and developer tools. To use sandbox tools either check them out of CVS from the org.eclipse.mylyn/sandbox directory, or install them using the update site above. Please note that some Sandbox tools may have external dependencies, listed in a readme.txt file.

Update Site

 download.eclipse.org/tools/mylyn/update/weekly/experimental

Dev tools

  • Introspect Object (action): displays the class and other relevant information (e.g. degree-of-interest, task synchronization state) of any object visible in the workbench. Appears at the end of the context menu for any view that accepts an object contributions.
  • Interest Level Decorator: displays the floating point interest level of elements. Enable via Decorators preference page.

Experimental tools

The following experimental views can be opened via the Mylar Sandbox view category or accessed via the Mylar -> Sandbox preference page.

  • Active Task Swither Trim Widget: note that it cannot currently be disabled
  • Context Search: automatically finds and displays elements that are structurally related to landmarks in the active . These elements become part of the task context and have a predicted degree-of-interest.
  • Context Hierarchy: displays the Java hierarchy of all landmark elements.
  • Predicted interested for Java errors: potentially useful, but tends to overload the Package Explorer. If you find this useful for long-term use condiser commenting on bug 107542.

Tips and Tricks

User support

  • Every time that you find yourself formulating an answer to a bug report, email, or newsgroup post, if the answer is more than a sentence, consider updating the FAQ, User Guide, or Integrator Reference and pointing to the entry.
  • Every time that resolving a bug does not result in a code change that addresses the problem or clarifies the UI, update the FAQ or User Guide to make sure that users can self-diagnose the problem. This is particularly important for bugs marked INVALID or WORKSFORME.

Code

  • For error handling use MylarStatusHandler.
  • Use WorkbenchJob for running jobs that should only run when the workbench is active. Not doing this can cause errors on workbench shutdown (e.g. bug 178409).
  • When using String.toLowerCase(), use String.toLowerCase(Locale.ENGLISH) to ensure locale safety (see bug 168652).
  • Do not use @Override annotations on implementing methods, only on overriding methods. Doing so violates Java 5 (bug 173171).
  • Use DateFormat with extra caution. It is not thread-safe and should not be saved to fields in classes that can be used from multiple threads (UI, asynchonous execution, or jobs).
  • For the sake of multi-monitor setups, use getMonitor() instead of getDisplay() when you want to position a UI element on a specific coordinate of the screen.

Bugzilla

  • Query setup: If you are added to the cc list on a report that is not picked up by your usual queries it may go unnoticed. One trick is to create a query for ALL products except the product you usually work in (and hence have queries for) and set the cc field of the query to your id. Now you will be notified of anybody adding you to the cc of a product you don't usually monitor.

JDT

  • Including Platform plug-ins in search: Java search (Ctrl+H > Java Search) will include all plugins in your Plugin-in Dependencies. If you want to search other plugins as well, open the Plug-ins view, right click on the desired plugin(s) and choose 'Add to Java Search'. That plugin will now always be included in your java searches.

Debugging

  • Plug-ins fail to load: verify that plug-in dependencies are met via the Validate Plug-in Set button on the launch configuration Plug-ins tab.
  • Startup failure: If you get an IStartup failure message or a ClassNotFoundException on startup this is often the result of some step in the activation of the plug-in failing.
    • Attempt to find the earliest exception thrown within the in the plug-in's activation process. For example, this could occur in TasksUiPlugin.start() or TasksUiPlugin.<init>.
    • If the cause of the failure is not straightforward, the problem could be due to a class loading race condition. This can sometimes be verified by trying a different VM like IBM's or BEA's and checking if that resolves the problem. If this is the case, please file a bug.
  • Getting a thread dump:
    • Run Eclipse with the -debug option (or use java.exe instead javaw.exe on windows), then
      • On Windows: Hit a Ctrl-Break few times on the console window during that long synchronization to capture the thread dump
      • On Linux: Use Ctrl-\ on the console or send SIG_QUIT signal: kill -SIGQUIT pid
    • Use jps to find the PIDs of Java processes and jstack to show the stack trace of Java processes: jstack pid
      • Supported starting JDK 5 for UNIX / JDK 6 for Windows
    • See this Weblog on jstack
    • Also see Thread Dump and Concurrency Locks for more details.
  • Startup problems and deadlocks: for a diagnosis of a potential problem see diagnosis on https://bugs.eclipse.org/bugs/show_bug.cgi?id=177048#c3

Migrating Eclipse milestones

To migrate between Eclipse 3.3M4 and 3.3M5 (as of I20070205-1824):

  • Unzip two copies of it, one for bootstrapping and one for setting as your Target Platform in your bootstrap workspace. If you get two workspaces when you launch a test workspace, delete the "configuration" directory of the Target Platform. Note this bug may be fixed by

3.3M5 (bug 172975).

  • To synch you may need to delete the known_hosts file if CVS connections were failing (file path is in: Preferences -> Team -> CVS -> SSH2..).
  • After synching, if you get conflicts in the .settings folder after launching override them (happens because CVS version was updated, and your own was automatically migrated).
  • As usual, update your repository credentials in the Task Repositories view.
  • Note that you may need to re-create your launch configurations.