Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "Mylyn/Contributor Reference"

(Developers)
(JUnit Tests)
(230 intermediate revisions by 32 users not shown)
Line 1: Line 1:
[[Category:Mylyn]]  
+
See also: [https://bugs.eclipse.org/bugs/buglist.cgi?keywords=helpwanted;query_format=advanced;bug_status=UNCONFIRMED;bug_status=NEW;bug_status=ASSIGNED;bug_status=REOPENED;classification=Mylyn helpwanted bugs],
 +
[http://www.eclipse.org/eclipse/development/index.php eclipse dev], [http://git.eclipse.org/c/mylyn/ source repository], [http://dev.eclipse.org/viewcvs/index.cgi/www/mylyn/?root=Eclipse_Website website repository]
  
Also see: [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=&keywords_type=allwords&keywords=helpwanted&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&emailtype1=substring&email1=&emailtype2=substring&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]
+
== Project Structure ==
[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=&keywords_type=allwords&keywords=helpwanted&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&emailtype1=substring&email1=&emailtype2=substring&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= discussion bugs]
+
[http://www.eclipse.org/eclipse/development/index.php eclipse dev]
+
  
== Conventions ==
+
The Mylyn project is structured into sub-projects that address different areas of Application Life-cycle Management. Please see [[Mylyn/Charter]] for the top-level project charter.
  
All contributions to Mylar need to be made using Mylar since it links source changes to tasks and contexts, making open development and collaboration easier. Using Mylar ensures that:
+
Artifacts are published in a number of [[Mylyn/Repositories]]. The [http://eclipse.org/mylyn/downloads/ main repository] aggregates sub-projects that participate in Mylyn releases. The participating projects are listed in the [http://www.eclipse.org/projects/project-plan.php?projectid=mylyn project plan]. The main Mylyn update site features are mature components that are supported by the Mylyn project committers and may be distributed as part of the [http://www.eclipse.org/downloads/ Eclipse Downloads]. 
* 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.
+
Sub-projects are encouraged to provide a framework component and reference implementations called ''Connectors'' that extend Mylyn to different task management systems and focus the artifacts that you work with when you activate a task (formerly called ''Bridges'').
 +
 
 +
=== Feature Maturity ===
 +
 
 +
Mylyn features vary in UI maturity and availability 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 [http://www.eclipse.org/projects/dev_process/development_process.php#6_2_3_Incubation Eclipse project lifecycle] and could converge further with that lifecycle if Mylyn were split into a separate incubation project or sub-projects.)
 +
 
 +
'''Mature''': packaged Eclipse downloads and available via main update site
 +
 
 +
* UI quality: Eclipse SDK 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 burden 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 nightly 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 ''Incubation'' 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 Extras.
 +
 
 +
=== Creating New Components ===
 +
 
 +
Most sub-projects host a framework component and one or more reference implementations. When new code is brought into Mylyn it may be added as a sub-project, sub-sub-project or as a component of an existing project. The right organisational structure depends on the needs of the development community and the scope and process of the existing projects. Criteria that could qualify a component to be split out as a separate project:
 +
 
 +
* A component requires incubation status (e.g. for parallel IP) but the framework project has already matured.
 +
* The committer set of the component is not a subset of the committer set of the framework project.
 +
* A component wants to release more frequently than its framework project, i.e. it follows it's own project plan.
 +
* A component publishes its own APIs and its scope and community are significant that it requires its separate management structure such as a Bugzilla product, news group etc.
 +
 
 +
== Getting Started ==
 +
 
 +
The Mylyn project places a very high value on community contributions.  This document is intended to help those interested in contributing to Mylyn.  It communicates our conventions and discusses ways to get your contributions prioritized.
 +
 
 +
=== Individual Contributors ===
 +
 
 +
A significant portion of Mylyn contributions have been made by individuals wanting to make the tool or framework work better for them.  There are several ways that individuals can get involved with the project:
 +
 
 +
* '''Mentoring''': if you are an experienced user, you can support newcommers by providing feedback using the community channels
 +
** [http://www.eclipse.org/mylyn/community/ Mylyn Newsgroup].
 +
 
 +
* '''Casual contribution''': we have a large number of very valuable casual contributors who provide patches for their pet bugs, or enhancements that either they would find valuable or that they want to share with others.  If you are interested but don't know where to start look first through the short list of bugday bugs, and then through the longer helpwanted list.
 +
** '''[https://bugs.eclipse.org/bugs/buglist.cgi?keywords=bugday;query_format=advanced;keywords_type=allwords;bug_status=UNCONFIRMED;bug_status=NEW;bug_status=ASSIGNED;bug_status=REOPENED;classification=Mylyn bugday bugs]''': a short list of highly relevant bugs for getting started
 +
** '''[https://bugs.eclipse.org/bugs/buglist.cgi?keywords=helpwanted;query_format=advanced;keywords_type=allwords;bug_status=UNCONFIRMED;bug_status=NEW;bug_status=ASSIGNED;bug_status=REOPENED;classification=Mylyn helpwanted bugs]''': a longer list of all bugs targeted at community contributions
 +
 
 +
* '''Working towards commit rights''': The Eclipse and Mylyn development processes make it easy to make regular contributions without requiring commit rights, but frequent contributors may be interested in earning commit rights.  Commit rights come with a significant overhead of user support as well as the need to follow the project's priorities for contributions.  They require you to participate in the planning and of the project, and allow you influence the direction of the tool and framework.  If you are interested in becoming a committer we recommend letting one of the existing committers know so that they can mentor you and help build a trust relationship.  It can also help to identify a separable component of the project that you are interested in taking responsibility for, since Mylyn commit rights are assigned per-component.
 +
** [http://www.eclipse.org/legal/committerguidelines.php Committer Due Diligence Guidelines]
 +
** [http://www.eclipse.org/mylyn/community/ Mylyn Developer Mailing List]
 +
** [[Mylyn Meetings]] are held on a monthly conference call and open to all
 +
 
 +
=== Integrators and Vendors ===
 +
 
 +
Those building both closed and open source tools on top of Mylyn may be interested in evolving the Mylyn APIs to ensure that that the framework meets their needs.  We welcome such contributions just as we welcome individuals making improvements to the tool, since they help make Mylyn a better framework for all.  The Individual Contributor points above apply to integrators and vendors interested in contributing or earning commit rights.  In addition, the following tips may be of interest:
 +
 
 +
* List your extension on the [[Mylyn Extensions]] page and in the [http://marketplace.eclipse.org/ Eclipse marketplace].  This will help the Mylyn community become aware of the extension.
 +
 
 +
* If interested in exploring Mylyn integration, consider dialing into the our monthly call and adding an agenda item on the [[Mylyn Meetings]] page.
 +
 
 +
* Vendors are welcome, so make yourself known.  We recommend using your company name for Bugzilla email addresses.  If you have a product built on Mylyn and need a bug fixed, we recommend voting for it with that email address.  The Mylyn project prioritizes bugs according to how much overall benefit they will have to users, and as such commercial integrations are an important part of that prioritization.  If the bug does not fit with the project's priorities we will encourage you to provide a patch.
 +
 
 +
* Consider making a bug titled "support integration with <your tool>".  We use these bugs for discussing integration issues particular to a specific tool or technology and leave them open for ongoing API or UI discussion needs.
  
 
=== Links ===
 
=== Links ===
 +
 
* [[Development Conventions and Guidelines | Eclipse Code Conventions]]
 
* [[Development Conventions and Guidelines | Eclipse Code Conventions]]
 
* [[User Interface Guidelines | Eclipse User Interface Guidelines]]
 
* [[User Interface Guidelines | Eclipse User Interface Guidelines]]
 
* [[Eclipse Doc Style Guide | Documentation Style Guidelines]]
 
* [[Eclipse Doc Style Guide | Documentation Style Guidelines]]
 
* [http://en.wikipedia.org/wiki/Eat_one's_own_dog_food Eating your own dog food (Wikipedia)]
 
* [http://en.wikipedia.org/wiki/Eat_one's_own_dog_food Eating your own dog food (Wikipedia)]
 +
 +
== Contributors ==
 +
 +
=== Overall Process ===
 +
 +
The best way to get your contribution into the code base is to stick to this workflow:
 +
# '''Sign''' the [http://www.eclipse.org/legal/CLA.php CLA] by logging in at https://projects.eclipse.org/user/login/sso (You only need to do this once).
 +
# '''Install''' the [[#Contributor Tools|Tools]], including EGit, Mylyn Bugzilla, and Gerrit.
 +
# '''Setup''' your Eclipse [[#Setting Up|Environment]].
 +
# '''Find''' or file a [[#Working with Bugzilla|Bug]].
 +
# '''Write''' the [[#Developing Code|Code]].
 +
# '''Push''' a [[#Working with Reviews|Review]].
 +
 +
=== Contributor Tools ===
 +
 +
In this guide, we'll be sharing the basics of what you need to know to work with Bugzilla tasks, EGit changes and Gerrit reviews, along with recommendations about best practices for using these tools.
 +
 +
For more information on how to work with EGit and Gerrit Reviews, refer to the Eclipse help documentation. (At the time of this writing, some of those documents are a bit out of date. The tooling has improved signficantly and much of the workflow is much simpler now.) There are also a number of excellent tutorials (google "eclipse gerrit"), including [https://www.eclipse.org/community/eclipse_newsletter/2013/september/article4.php this one].
 +
 +
==== Using Mylyn ====
 +
 +
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 Reviews match up to a single Bugzilla report, making it easy to navigate from changes to bugs.
 +
 +
==== Installing ====
 +
 +
All the tools we need are conveniently available as part of many of the standard Eclipse distributions. You can also install the tools from their respective p2 repositories into any Eclipse instance using Install New Software from the Help menu. Using the repositories below will help ensure that you have the latest and greatest versions of each tool.
 +
 +
*EGit p2 repository - <code>http://download.eclipse.org/egit/updates</code>
 +
**Eclipse Git Team Provider
 +
**Task Focused Interface for Eclipse Git Team Provider
 +
*Mylyn p2 repository - <code>http://download.eclipse.org/mylyn/latest</code>
 +
**Mylyn Tasks Connector: Bugzilla
 +
**Mylyn Context Connector: Eclipse IDE
 +
**Mylyn Builds Connector: Hudson/Jenkins
 +
**Mylyn Reviews Connector: Gerrit
 +
**Mylyn Versions Connector: Git
 +
 +
=== Setting Up ===
 +
 +
 +
==== Register a Gerrit Account ====
 +
 +
To use the review server a few steps are required:
 +
 +
* Register an Eclipse.org account at [https://dev.eclipse.org/site_login/createaccount.php dev.eclipse.org]. The same account is used for [https://bugs.eclipse.org/bugs Bugzilla] and [https://git.eclipse.org/r Gerrit].
 +
* [https://git.eclipse.org/r/#settings,http-password Define a username].
 +
* [https://git.eclipse.org/r/#settings,ssh-keys Upload your public ssh-key] for authentication.
 +
 +
You are now ready to submit changes to Gerrit.
 +
 +
==== Connect to Bugzilla ====
 +
 +
All Eclipse projects use Bugzilla for issue tracking. Mylyn makes connecting to Bugzilla easy.
 +
 +
# Connect to the Eclipse Bugzilla Repository:
 +
## Click the "Add Task Repository" button in the Task Repositories View.
 +
## Select Bugzilla.
 +
## In the Server section, Select Eclipse.org from the drop down menu.
 +
## Add the credentials you created above and click "Finish".
 +
# Setup a query for your Reviews:
 +
## Right-Click in the Task List and select "New" -> "Query..."
 +
## Select the Repository you just created, click through to "Create Query using Form".
 +
##* To find bugs to work on, select some items in Product. For example "Mylyn Tasks".
 +
##* You could narrow this further, by selecting Components you are interested in or bugs with Status "New".
 +
##* Under "More Options", try adding the "helpwanted" keyword to find bugs that the Mylyn team has identified as good for contributors to tackle.
 +
 +
==== Connect to Gerrit and Git ====
 +
 +
This part is also easy, and the great thing is that you get the source code and reviews support from the same place.
 +
 +
# Connect to the Gerrit Repository:
 +
## Click the "Add Task Respository" button in the Task Repositories View.
 +
## Select Gerrit Code Review.
 +
## Enter the server address: https://git.eclipse.org/r
 +
## Add your credentials and validate.
 +
# Setup a query for your Reviews:
 +
## Create a New Query in the Task List using the repository and "My Changes".
 +
## There won't be anything there yet of course. To get an idea of what the reviews process looks like, try "Open Changes by Project" and search for a Mylyn project that interests you.
 +
## Or, try the new [https://www.eclipse.org/mylyn/new/new-3.11.html#gerrit Gerrit Dashboard]!
 +
# Import the source code:
 +
## Under File > Import select "Projects from Git" and select Gerrit from the list on the next page.
 +
## Select the repository you're interested in from the list of Git repositories hosted on the Eclipse.org Gerrit instance. If you want to contribute to Mylyn Tasks for example, select the mylyn/org.eclipse.mylyn.tasks repository.
 +
## The repository is automatically cloned and we can select all projects to import on the last page. (If an error is displayed that the SSH key is invalid or missing it needs to be generated first in the Eclipse preferences under General > Network Connections > SSH2 and uploaded to Gerrit. See [[#Register a Gerrit Account|above]])
 +
## Note that once all projects have been imported you can get rid of any API baseline errors by opening the Eclipse preferences and selecting the Plug-in Development > API Baselines page and setting Missing API baseline to Ignore.
 +
 +
=== Working with Bugzilla ===
 +
 +
==== Key Points ====
 +
 +
* For contribution ideas see [[#Individual_Contributors]] to find an enhancement or defect that interests you, file a new bug of your own, or email [https://dev.eclipse.org/mailman/listinfo/mylyn-dev mylyn-dev] for ideas. Often the best contributions come from people who have an "itch to scratch".
 +
* ''Before'' starting work:
 +
*# Comment on the corresponding bug, stating your interest and asking whether a committer or another contributor has any suggestions for the implementation approach.
 +
*# Propose a design, mentioning the key use cases, implementation, tests coverage, and UI changes or additions (if applicable). (You might skip this step if the required fix or proposed behaviour is clear.)
 +
*# Assign yourself to the bug.
 +
 +
==== Voting ====
 +
 +
Votes track the general interest in a particular bug.  Bugs with more votes are more likely to get fixed.  We encourage all in the community to vote for bugs, since it helps committers and contributors prioritize work.
 +
 +
=== Developing Code ===
 +
 +
==== Key Points ====
 +
 +
* Follow [[Development Conventions and Guidelines | Eclipse code conventions]].
 +
* Ensure you've provided complete unit test coverage.
 +
* Add an <tt>@author</tt> tag to each class that you create or make significant modification to, placed below any existing author tags, e.g.: <tt>@author Awesome J. Contributor</tt>
 +
* Small is good! More focused changes will be reviewed more quickly and have a much better chance of being merged without major changes. If the bug you're working on involves complex changes, consider breaking your changes up into bite-sized pieces rather then tackling the whole thing in one review.
 +
 +
==== Writing Tests ====
 +
 +
When writing tests look for the <code>All&lt;component&gt;Tests</code> class in the <code>tests</code> 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. Ensure that your test covers the addition or change to the existing functionality.  For API changes it is often sufficient to have the public method covered. 
 +
 +
Tests can sometimes take longer to write then the change itself! If you get stuck, ask a committer to assist you in designing tests appropriate to your case.
 +
 +
Working with mock test harnesses and UI can be especially challenging. Writing tests for UI components often involves a combination of unit and black-box testing. For example we might rely on other parts of the Mylyn UI (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 might take the following form (refer to <code>NewTaskWizardRepositorySelectionTest</code>):
 +
* 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 ''very'' 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: <code>mylyn/graphics/ui</code>.
 +
 +
=== Working with Reviews ===
 +
 +
The review process is the most important tool we use to ensure that Mylyn code is as high quality as possible. It can also be pretty intimidating for new contributors. But it shouldn't be. Think of it as an opportunity to gain from the experience of other developers. And to keep things in perspective, remember that many thousands of other developers might be made more happy by the change that you make -- or unhappy if it doesn't work correctly!
 +
 +
The best thing about the Gerrit based reviews process is that it means that all code gets reviewed in the same way, regardless of who wrote it. The only significant differences between contributors and committers are that only committers can approve commits (vote +2) and single contributions of over a 1,000 lines of code must go through extra IP process. (Another reason to keep those commits small.) So even if you never decide to become a Mylyn committer you can still make significant improvements to Mylyn!
 +
 +
==== Key Points ====
 +
 +
* Ensure that your commit message is formatted correctly and has all of the information needed.
 +
* Before pushing your commit:
 +
** Ensure the the code does what you say it does by testing it thoroughly.
 +
** Be your own first reviewer. Go over your commit before pushing it. Often a second (or third, or fourth) self-review of the code will reveal issues that you'd missed.
 +
* After pushing your commit:
 +
** Add a link to the review in a comment on the original bug.
 +
* After recieving feedback:
 +
** Don't take reviews personally. Even seasoned Mylyn committers should expect to see -1 and -2 reviews. If all of our code was perfect the first time, we'd never need reviews. It's helpful especially at first to see reviews as a learning process.
 +
** Do respond to ''every'' comment. If you disagree with a point, that's ok -- explain why you did things the way you did.
 +
** Be patient and prepared to iterate. While some simple changes might get committed in a day or two, complex changes requiring input from contributors might require refinement over a few weeks. The Gerrit tools make this process much less painful then before.
 +
* After recieving your first +2:
 +
** Give yourself a well-deserved high-five. You're now a Mylyn contributor!
 +
** Find another bug!
 +
 +
==== Committing Changes ====
 +
 +
# Right click and select Team > Commit on any changed project or resource to display the git commit dialog.
 +
# If you've activated the task, this will be populated with the following items, or you can enter them by hand:
 +
#* The bug ID and a summary.
 +
#* A "Task-Url:" entry active task allowing bugs to be traced to tasks.
 +
# Click the rightmost two buttons on the commit dialog and the remaining two required entries will be added for you:
 +
#* A Gerrit "Change-Id" entry. The entry is required for all changes pushed to Gerrit (to enable pushing new patch set versions to the same review)
 +
#* A "Signed-off-by" entry. The entry is required as it confirms that you are in compliance with the [http://www.eclipse.org/legal/CoO.php Certificate of Origin].
 +
# Edit the commit summary to describe the specific change you are making. This is not always the same as the bug summary. Your commit may only be addressing part of the issue. It is often helpful to other developers to add additional lines of description below the summary. Leave a one-line gap between the summary and further description.
 +
# Ensure that the Author and Committer dialog entries match your Eclipse credentials. Like this: <code>Awesome Contributor <awesome.contributor@awesome-company.com></code>
 +
# Click "Commit". You can do a "commit and push" directly, but at least until you gain some experience it's probably a good idea to double-check your commit before pushing it.
 +
#* Is everything that you expected to be there there?
 +
#* Does the commit message match the example below?
 +
 +
===== Example Commit Message =====
 +
 +
The following is the [https://bugs.eclipse.org/bugs/show_bug.cgi?id=420699 standard] commit message template which can be configured in Window -> Preferences -> Tasks -> Team:
 +
 +
<pre>
 +
${task.key}: ${task.description}
 +
 +
Task-Url: ${task.url}
 +
</pre>
 +
 +
Note that often you'll want to edit the task description.
 +
 +
Here's an example of what a review message should look like:
 +
 +
<pre>
 +
999895: Improve sorting in task view
 +
 +
* Replaced random with alphabetical sorting
 +
* Minor refactoring
 +
 +
Task-Url: https://bugs.eclipse.org/bugs/show_bug.cgi?id=999895
 +
Change-Id: Ieb8caf92cd87899b125b89beb077a1d4f579ff23
 +
Signed-off-by: Awesome Contributor <awesome.contributor@awesome-company.com>
 +
</pre>
 +
 +
The dialog should end up looking like this:
 +
 +
[[File:MylynContributorGuideGitCommit.png]]
 +
 +
==== Pushing Changes ====
 +
 +
After reviewing your submission, you can push it. There are many workflows that work well, but here's one relatively fool-proof approach:
 +
 +
# Pull or fetch to ensure that origin/master is as up to date as possible. This will help avoid future rebase trauma!
 +
# Rebase on top of origin/master.
 +
# Ensure that you are on the master branch. (If you're currently working on a topic branch, you could do this by checking out the master branch and then doing a hard reset to your topic. But make sure you've committed your changes first!)
 +
# Right click on any changed project or resource and select Team > Push to Upstream.
 +
# After pushing, you might want to create a seperate topic branch to help manage your change locally.
 +
 +
==== Subsequent Changes ====
 +
 +
Handling subsequent changes is easy, as long as you keep things simple and follow the recommendations below. Otherwise, you might end up doing a bit of juggling!
 +
 +
# After the initial commit, it is better ''not'' to rebase against master, unless you know there are signficant changes that have been committed in the meantime that you need to merge with. Rebasing within a review makes it more difficult to track changes between patch sets.
 +
# Select "Amend Previous Commit", the first button in the commit dialog toolbar. This will ensure that the change has exactly the information Gerrit is expecting, and means that you won't have to deal with annoyances like squashing commits later.
 +
# If you can't amend the commit, then ensure that the Change-Id: value matches whatever value is already there in the review. This is the only way that Gerrit associates your change with a particular review.
 +
# In either case, you can freely edit the commit message to reflect your evolving change.
 +
 +
If things didn't turn out correctly and you get a reject message or something else unexpected happens, don't despair. With Git there is always a way to clean up any kind of mess, though it can take a bit of perserverance to discover how. The key thing to keep in mind is that there can only be one commit per review. So if you have multiple commits related to a change, you need to "squash" them into one change with the appropriate commit id. Most contributors sooner or later becomes familiar with the magical command line incantation: <code>git rebase -i HEAD~2</code>. See the git documentation for details. Alternatively, EGit has a new "Git Interactive Rebase" view that lets you perform this magic with a visual tool.
 +
 +
If someone else makes a change to your review -- and don't be offended if they do! -- and you want to incorporate that change into your subsequent changes, or if you don'thave the topic branch for one of your own changes, just do this:
 +
 +
# Fetch the change (Patch Set) using the Gerrit task editor.
 +
# Checkout the master branch and reset it to the branch you've just checked out. (You may want to create a topic branch as well.)
 +
# Then you can just amend any subsequent changes exactly as above.
 +
 +
 +
== Committers ==
 +
 +
Contributors who have made frequent and valuable contributions to Mylyn can become committers. The [http://www.eclipse.org/projects/dev_process/Eclipse_Standard_TopLevel_Charter_v1.0.php Eclipse Charter] explains how.
 +
 +
=== 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 mylyn-dev email in their area of expertise.
 +
* Watch and update all wiki pages related to components that they contribute to.
 +
 +
=== Communication ===
 +
 +
Mylyn 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.
 +
 +
* Show respect to others in the community, whether they are making correct or incorrect assumptions about the tool or technology.  When someone makes 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 [http://en.wikipedia.org/wiki/Flame_war#Causes_of_flaming flaming], being condescending, short, or insulting in any community communication forum.  Forms of humor that work for face-to-face communication, such as sarcasm, are usually best avoided because they can result in misinterpretation, especially when there is a language or cultural barrier. 
 +
 +
'''Handling Inappropriate Communication'''
 +
 +
In the vast majority of cases, following the above guidelines has lead to the high quality communication that our user and contributor community has thrived on.  However, the openness of our communication channels has been abused in the past.  These scenarios are typically marked by overly opinionated, non-technical and insulting posts on bugs in and in other forums.  The communication may have technical elements or technical points, but the points are communicated in an overly opinionated way with a disregard for the opinions of others involved in the dialog.  If encountering such communication, make sure to read the [http://en.wikipedia.org/wiki/Flame_war Wikipedia Entry on Flaming], especially the "Causes of flaming" section.
 +
 +
Note that invoking the process listed below should be the exception, and not the rule.  Projects with like-minded committers can experience the [http://en.wikipedia.org/wiki/Groupthink Groupthink] bug, which is why high quality open communications channels are so important to helping the project evolve.  However, abuse undoes the openness that we strive for by making the channels intimidating or unfriendly to newcommers.  Follow these steps if you encounter such communication:
 +
* Make one or two attempts to steer the conversation back on a technical path. 
 +
* If that doesn't address the problem, enter the following text as the third comment:
 +
  Ignoring comment per: http://wiki.eclipse.org/index.php/Mylyn_Contributor_Reference#Communication
 +
* Avoid following up again.  Send the bug ID to the project lead who will assess the problem.
 +
 +
To comment on these guidelines please use {{bug|216157}}
  
 
=== Bugzilla ===
 
=== Bugzilla ===
Line 25: Line 344:
 
** Good: support nesting top level task list elements, e.g. via working sets
 
** Good: support nesting top level task list elements, e.g. via working sets
  
=== Feature Maturity ===
+
'''Severities'''
 +
* Use the Eclipse [https://bugs.eclipse.org/bugs/bug_status.html#bug_severity bug severity] with this exception: bugs marked as Trivial are enhancements, that can be easily implemented.
  
Mylyn features vary in UI maturity and availibility of supportThe 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.)
+
'''Keywords'''
 +
* <code>helpwanted</code>: bugs that are beyond the current priorities for the projectNote that some bugs marked for an upcoming milestone can be marked as <code>helpwanted</code>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.
  
'''Mature''': packaged Eclipse downloads and available via main update site
+
* <code>bugday</code>: these are a special category of <code>helpwanted</code> 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.
  
* 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.
+
* <code>contributed</code>: bugs that were resolved through a contribution from a non-committer.
  
* 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.
+
* <code>plan</code>: bugs that are part of the project plan (see below).
  
* 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.  
+
'''Tags'''
 +
The project uses the following tags in the summary of bugs on bugs.eclipse.org ({{bug|215853}}):
  
* 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).
+
[activity]      - bugs related to improving work flow
 +
[api]          - bugs that require API changes; every API change has a corresponding bug which is tagged that way
 +
[bridge]        - requests for structure bridges
 +
[connector]    - requests for connectors
 +
[context]      - bugs related to the context framework
 +
[discussion]    - discussion items
 +
[editor]        - bugs related to the Task Editor
 +
[e3.2][e3.3]    - bugs specific to a particular version of Eclipse
 +
[folding]      - bugs related to active folding
 +
[framework]    - bugs that address internal implementation details that do not require API changes
 +
[linux]        - bugs specific to Linux (Gtk)
 +
[m2.3.1]        - bugs that are fixed in a particular maintenance version of Mylyn
 +
[mac]          - bugs specific to Mac OS (Cocoa, Carbon)
 +
[multi monitor] - bugs related to multi monitor environments
 +
[new uex]      - new user experience
 +
[patch]        - bugs that have a patch attached that is pending for review or waiting to be applied;
 +
                  the tag is removed after the patch has been applied or if a review requested changes
 +
[performance]  - bugs that indicate severe performance problems
 +
[planning]      - requests for planning features
 +
[refactor]      - request for non-functional refactorings
 +
[regression]    - bugs that indicate regressions
 +
[sandbox]      - bugs that affect components in the sandbox
 +
[standalone]    - bug related to usage of Mylyn outside of the Eclipse environment
 +
[update]        - update manager and P2 related bugs
 +
[usage]        - usage monitoring related bugs
 +
[web connector] - bugs in the Web Templates connector
 +
[website]      - bugs related to the web page on eclipse.org/mylyn ''(use Doc component for that?)''
 +
[win]          - bugs specific to Windows (Win32, WPF)
 +
[workflow]      - requests for integration of task and repository workflow
 +
[working sets]  - bugs related to working set support
 +
[search]        - bugs related to desktop search (see {{bug|349351}})
  
'''Incubation''': available via the ''Extras'' update site
+
==== Triage ====
  
* 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.
+
The goal of bug triage to minimize the overhead for committers and to maintain a manageable backlog. Each (new) bug that is filed is processed as follows:
  
'''Sandbox''': available via the ''Extras'' update site
+
* Major bugs or regressions are marked ''P1''. If necessary the bug is escalated and scheduled for the current milestone.
 +
* Other bugs are marked ''P2''.
 +
* Enhancements requests that should be considered for a future release are generally marked ''P3''.
 +
* Other enhancement requests are marked ''P4'' and tagged as ''helpwanted '' if they can be resolved through a community contribution.
 +
* If a request is out of scope of the project it is marked ''P5'' or preferably closed. P5 bugs should not be marked helpwanted.
  
* Unsupported components used for experimentation and not intended for daily use.
+
The backlog consists of all tasks scheduled for <code>--</code> with a priority of P2 or higher. User stories are tagged with the plan keyword.
 +
 
 +
Bugs are assigned as following:
 +
 
 +
* mylyn-inbox@eclipse.org: New bugs are and bugs that need user input.
 +
* mylyn-triaged@eclipse.org: Bugs that have been responded to and severity and priority has been set.
 +
* other: The owner is committed to completing the task for the scheduled milestone or within a reasonable time frame in the future if the bug is scheduled for --.
 +
 
 +
==== Planning ====
 +
 
 +
The goal of planning is to schedule a list of bugs for the milestone that concludes the next release cycle. When the milestone is reached all bugs with a priority of P3 or higher are expected to be completed. It is important that planning takes existing resources into account to avoid over-committing. Predictable release deliverables will enable integrators to plan their own progress based on the Mylyn framework and aid the growth of the ecosystem.
 +
 
 +
Before every release planning is done by triaging the entire backlog. Bugs marked with the plan keyword become part of the official release plan. Planning bugs marked P1 are committed items, other bugs are proposed items. Half way through a release cycle the plan is reviewed and P1/P2 bugs in the backlog are reconsidered for the milestone to accommodate for regressions and major bugs that were submitted after initial planning.
 +
 
 +
==== Resolving ====
 +
 
 +
The list of bugs that are scheduled for a milestone serves as a log that documents changes to release artifacts. In order to preserve historical information captured by the change log bugs that have been resolved should not be moved to other milestones once a milestone has been released.
 +
 
 +
If a defect reoccurs or a bug requires further work a new bug should be created and linked to the resolved bug. It is recommended to add a comment on the resolved bug that points to new bug and describes the reason for its creation.
 +
 
 +
=== Git ===
 +
 
 +
Git repositories can be accessed in Eclipse via [http://eclipse.org/egit/ EGit]. Mylyn uses the following conventions for Git repositories:
 +
 
 +
* It is strongly recommended to rebase before pushing to keep the revision history flat as possible:
 +
 
 +
git pull --rebase
 +
 
 +
The [http://kernel.org/pub/software/scm/git/docs/git-config.html branch.autosetuprebase setting] automates that:
 +
 
 +
git config branch.autosetuprebase always
 +
 
 +
See also:
 +
* [http://wiki.eclipse.org/Platform-releng/Git_Workflows#Cross-referencing_between_bugzilla_and_git Git workflows for CVS users]
 +
 
 +
=== Hudson ===
 +
 
 +
Mylyn is built regularly by jobs running on the Eclipse.org Hudson server.
 +
 
 +
* [https://hudson.eclipse.org/hudson/user/spingel/my-views/view/Mylyn/ Mylyn Build Jobs]
 +
 
 +
'''Heartbeat Test Jobs'''
 +
 
 +
Each sub-project has its own build job triggered by Git activity that runs all tests for the sub-project.
 +
 
 +
* [https://hudson.eclipse.org/hudson/user/spingel/my-views/view/Mylyn%20Heartbeat/ Heartbeat Test Jobs]
 +
 
 +
'''Integration Test Jobs'''
 +
 
 +
Integration tests run against the [http://git.eclipse.org/c/mylyn/org.eclipse.mylyn.all.git/ Git integration build] repository that includes all sub-projects as submodules. Integration tests are triggered by the [https://hudson.eclipse.org/hudson/job/mylyn-release/ mylyn-release job].
 +
 
 +
* [https://hudson.eclipse.org/hudson/user/spingel/my-views/view/Mylyn%20Integration/ Integration Test Jobs]
 +
 
 +
mylyn-integration-e3.5      - Eclipse 3.5: All tests excluding repository tests
 +
mylyn-integration-e3.6      - Eclipse 3.6: All tests excluding repository tests
 +
mylyn-integration-e3.7      - Eclipse 3.7: All tests including repository tests against all supported versions
 +
 
 +
mylyn-integration-e4.1      - Eclipse 4.1: All tests including repository tests against all supported versions
 +
 
 +
mylyn-integration-standalone - Java 1.6  : Tests designed to work outside of an OSGi environment
 +
 
 +
The full suite of repository tests is only run on the most recent Eclipse platforms. Running the full suite is expensive and a Bugzilla or Trac specific test that fails on Eclipse 3.5 is very likely to also fail on Eclipse 3.7.
 +
 
 +
'''Release Jobs'''
 +
 
 +
Release and snapshot artifacts created by release jobs are published to download.eclipse.org.
 +
 
 +
* [https://hudson.eclipse.org/hudson/user/spingel/my-views/view/Mylyn%20Release/ Release Jobs]
 +
 
 +
mylyn-3.5.x-release  - e_3_7_m_3_5_x branch
 +
mylyn-3.6.x-release  - e_3_7_m_3_6_x branch
 +
mylyn-release        - master branch
 +
 
 +
=== Maven ===
 +
 
 +
The Mylyn build is based on Maven/Tycho. The minimum required Maven version is 3.0.
 +
 
 +
* The <code>org.eclipse.mylyn/org.eclipse.mylyn-parent</code> module specifies a parent pom with common settings. This pom is published to the [http://mirrors.ibiblio.org/pub/mirrors/eclipse/mylyn/maven/snapshots/ Mylyn Maven repository].
 +
* The <code>org.eclipse.mylyn/org.eclipse.mylyn-target</code> module specifies a target definitions. These are published to the [http://mirrors.ibiblio.org/pub/mirrors/eclipse/mylyn/maven/snapshots/ Mylyn Maven repository].
 +
 
 +
==== Builds ====
 +
 
 +
mvn package
 +
 
 +
To skip execution of tests use <code>-Dmaven.test.skip=true</code>
 +
 
 +
==== Tests ====
 +
 
 +
To run tests invoke the following command:
 +
 
 +
mvn integration-test
 +
 
 +
==== Releases ====
 +
 
 +
* Check out the org.eclipse.mylyn.all project.
 +
* Run <code>git submodule init</code> to initialize sub modules
 +
* Run <code>git submodule update</code> to update sub modules to the latest integration build
 +
* Run <code>mvn package</code> to build release artifacts.
 +
 
 +
The [[Mylyn/Release_Howto|Release Howto]] describes how to build and publish official Mylyn releases.
 +
 
 +
==== Profiles ====
 +
 
 +
The build defines profiles to build Mylyn against different targets. Profiles can be activated by passing <code>-P<profile></code> to mvn.
 +
 
 +
* <code>implicit-target</code> - build against nightly repositories, this is the default
 +
* <code>explicit-target</code> - build against a target definitions in <code>org.eclipse.mylyn/org.eclipse.mylyn-target</code>, needs to be activated through property <code>-Dexplicit-target</code>
 +
* <code>ganymede, galileo, indigo, juno, e4.1, e4.2 </code> - build against a specific Eclipse release (requires <code>-Dexplicit-target</code>)
 +
 
 +
==== Properties ====
 +
 
 +
Properties control certain aspects of the build such as execution of tests or optional analysis of source code. Properties can be set by passing <code>-D<property>=<value></code> to mvn. All properties are initialized to sensible default values and are optional.
 +
 
 +
* <code>tycho-version</code> - version of Tycho to use for building
 +
* <code>analysis.skip</code> - set to false to run code analysis (default: true)
 +
* <code>test.skip</code> - set to false to run tests (default: ${maven.test.skip})
 +
* <code>sign.skip</code> - set to false to run code signing (default: true)
 +
* <code>pack.skip</code> - set to false to run pack repositories (default: false)
 +
* <code>promote.skip</code> - set to false to copy artifacts to download location (default: true)
 +
 
 +
=== Code ===
 +
 
 +
Mylyn uses the Eclipse code conventions with these minor additions ({{bug|214179}}):
 +
 
 +
Tags: Mylyn uses the following tags in the code:
 +
* TODO: The following code needs to be reviewed.
 +
* TODO API: Indicates that a method or class needs to be reviewed.
 +
* TODO API x.y: This API is going to change for version x.y. Should include a description how it is going to change.
 +
* TODO e3.4: Make a change in the future specific to an Eclipse version.
 +
* XXX: The implementation uses a temporary work around that should be replaced by a proper solution in the future.
 +
* XXX SDK: The code uses internals of the Eclipse platform.
 +
* FIXME: Should only be used in very rare cases as a reminder that the marked code does not work as expected. Code marked as FIXME should not be distributed in a release.
 +
* FIXME REVIEW: Review the code before the next version is released
 +
 
 +
==== Creating new plug-ins and features ====
 +
 
 +
File a bug that describes the purpose of the new plug-ins and the proposed names. Then add an item to the monthly meeting agenda to discuss the request with other committers. Once consensus has been reached follow the steps below.
 +
 
 +
To retain consistency of layout and settings, new projects should always be created by copying an existing project rather than creating plug-in or feature projects from scratch.
 +
 
 +
Steps for creating a new plug-in or feature:
 +
 
 +
# Copy an existing project on disk, e.g. to create an org.eclipse.myconnector.core bundle do the equivalent of running <code>cp -a org.eclipse.mylyn.bugzilla.core org.eclipse.mylyn.myconnector.core</code>
 +
# Edit <code>pom.xml</code>, <code>.project</code> and <code>META-INF/MANIFEST</code> to reflect the new bundle id
 +
# List the new bundle as a module in the parent pom to include it in the build
 +
# Use Import Projects from the popup menu in the Git Repositories view to add the project to the workspace
 +
 
 +
For plug-ins these additional steps should be considered:
 +
 
 +
# Add bundle to feature
 +
# Add source bundle to SDK feature
 +
 
 +
For features these additional steps should be considered:
 +
 
 +
# Add feature to site
 +
 
 +
=== Contributions ===
 +
 
 +
Contributions are a key part of evolving Mylyn. All committers should encourage and prioritize contributions.
 +
 
 +
=== IP log ===
 +
 
 +
The IP log should always be kept up to date.
 +
 
 +
[http://eclipse.org/projects/ip_log.php?projectid=mylyn,mylyn.builds,mylyn.commons,mylyn.context,mylyn.docs,mylyn.reviews,mylyn.tasks,mylyn.versions Aggregated IP log]
 +
 
 +
Sub-project IP logs:
 +
 
 +
[http://eclipse.org/projects/ip_log.php?projectid=mylyn.builds Mylyn Builds]
 +
[http://eclipse.org/projects/ip_log.php?projectid=mylyn.commons Mylyn Commons]
 +
[http://eclipse.org/projects/ip_log.php?projectid=mylyn.context Mylyn Context]
 +
[http://eclipse.org/projects/ip_log.php?projectid=mylyn.docs Mylyn Docs]
 +
[http://eclipse.org/projects/ip_log.php?projectid=mylyn.reviews Mylyn Reviews]
 +
[http://eclipse.org/projects/ip_log.php?projectid=mylyn.tasks Mylyn Tasks]
 +
[http://eclipse.org/projects/ip_log.php?projectid=mylyn.versions Mylyn Versions]
 +
 
 +
==== Applying Patches ====
 +
 
 +
(''Note'': the section below is largely supplanted by the new Gerrit based review system, which takes care of many of these details including contributor IP approval.)
 +
 
 +
* Note that each patch should not contain more than 1000 added lines. 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.
 +
 
 +
When applying a patch follow these steps:
 +
 
 +
'''Git'''
 +
* Enter the name of the contributor as the author of the commit
 +
* Encourage the contributor to update the patch into state where it can be applied unaltered.
 +
* If you need to make addtional changes that are non-trivial (e.g., copyright header fixes) commit the unaltered patch first and then make another commit with your changes.
 +
** If absolutely necessary, a task-branch can be used to group commits and improve traceability otherwise commit messages should be sufficient to associate bugs with commits.
 +
* All files altered by a contributor must have a note in the copyright header and should have an @author tag if a change was significant.
 +
* If several authors have worked on a commit consider adding ''Co-authored-by'' headers to the commit message for each author.
 +
* Also see [[Development_Resources/Handling_Git_Contributions]] .
 +
 
 +
'''Bugzilla'''
 +
* Flag the the patch attachment as ''iplog+''.
 +
* Add the ''contributed'' keyword to the corresponding bug.
 +
 
 +
=== Web Site ===
 +
 
 +
* If you haven't done it already, [https://git.eclipse.org/r/#/settings/ssh-keys upload your SSH public keys to Gerrit] if you wish to use SSH
 +
* Clone <code>ssh://userid@git.eclipse.org:29418/www.eclipse.org/mylyn.git</code>, replacing <code>userid</code> with your id
 +
* You're ready to push your changes to the repo:
 +
** directly -- <code>git push origin master</code> (passing Gerrit review)
 +
** creating a review -- <code>git push origin HEAD:refs/for/master</code>, see [[Gerrit#Doing_Code_Reviews_with_Gerrit]]
  
* Community interest and contributions determine which experimental features move from the Sandbox into Incubation.
+
Note, you need to be a member of the <code>mylyn</code> group to push changes to the website.
  
 
== Workspace ==
 
== Workspace ==
  
The recommended way to work with Mylar 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 [https://bugs.eclipse.org/bugs/show_bug.cgi?id=157375 PDE bug 157375].
+
The recommended way to work with Mylyn sources is by checking them out of Git.  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.
 
    
 
    
 
=== Setup ===
 
=== Setup ===
Line 57: Line 617:
 
Install Eclipse and get it configured for developing Java 5 applications.
 
Install Eclipse and get it configured for developing Java 5 applications.
 
* Unless targeting a particular Eclipse release, download the latest [http://download.eclipse.org/eclipse/downloads/ Eclipse milestone release].   
 
* Unless targeting a particular Eclipse release, download the latest [http://download.eclipse.org/eclipse/downloads/ Eclipse milestone release].   
* Associate J2SE-1.5 with your installed JRE via the ''Window -> Preferences -> Java -> Installed JREs -> Execution Environments''.  
+
* 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/
 +
* To install additional JRE profiles or if you are unable to obtain a J2SE 1.5 installation install ''Add PDE/API Tools Environment Descriptions'' from the  Eclipse project repository that corresponds to your Eclipse environment, e.g. http://download.eclipse.org/eclipse/updates/3.7
  
 
=== Checkout ===
 
=== Checkout ===
  
The Mylar CVS repository contains the following branches. Each can be checked via saving the linked <code>.psf</code> 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 Mylar, the additional projects can be deleted after the import.  After the checkout you should have no errors or warnings from the Mylar projects.
+
The source code is hosted in Gerrit which is a code review system for Git. Each sub-project has a separate repository that is accessible through the git, ssh and https protocol. For anonymous access use git or https. Committers need to use ssh or https.
  
Note: these project sets specify anonymous <code>pserver</code> accessIf that does not work for you see the [[CVS Howto]].
+
[http://git.eclipse.org/c/mylyn/ Web access to the Git repositories]
 +
 
 +
'''Release Tags:''' Each release is tagged with <code>R_</code>.  For example, Mylyn 2.2.0 for Eclipse 3.4 is tagged as <code>R_2_2_0</code> and the branched Eclipse 3.3 plug-ins are tagged <code>R_2_2_0_e_3_2</code>.
 +
 
 +
==== Active branches ====
 +
 
 +
* Mylyn Releng:
 +
** <code>master</code> &nbsp;&nbsp; 3.x stream - '''git://git.eclipse.org/gitroot/mylyn/org.eclipse.mylyn.git''' &nbsp;&nbsp; [http://git.eclipse.org/c/mylyn/org.eclipse.mylyn.git/ Web]
 +
 
 +
* Mylyn Builds:
 +
** <code>master</code> &nbsp;&nbsp; 1.x stream - '''git://git.eclipse.org/gitroot/mylyn/org.eclipse.mylyn.builds.git''' &nbsp;&nbsp; [http://git.eclipse.org/c/mylyn/org.eclipse.mylyn.builds.git/ Web]
 +
* Mylyn Commons:
 +
** <code>master</code> &nbsp;&nbsp; 3.x stream - '''git://git.eclipse.org/gitroot/mylyn/org.eclipse.mylyn.commons.git''' &nbsp;&nbsp; [http://git.eclipse.org/c/mylyn/org.eclipse.mylyn.commons.git/ Web]
 +
* Mylyn Context:
 +
** <code>master</code> &nbsp;&nbsp; 3.x stream - '''git://git.eclipse.org/gitroot/mylyn/org.eclipse.mylyn.context.git''' &nbsp;&nbsp; [http://git.eclipse.org/c/mylyn/org.eclipse.mylyn.context.git/ Web]
 +
* Mylyn Context Model Focusing Tools (MFT):
 +
** <code>master</code> &nbsp;&nbsp; 0.9 stream - '''git://git.eclipse.org/gitroot/mylyn/org.eclipse.mylyn.context.mft.git''' &nbsp;&nbsp; [http://git.eclipse.org/c/mylyn/org.eclipse.mylyn.context.mft.git/ Web]
 +
* Mylyn Docs:
 +
** <code>master</code> &nbsp;&nbsp; 1.x stream - '''git://git.eclipse.org/gitroot/mylyn/org.eclipse.mylyn.docs.git''' &nbsp;&nbsp; [http://git.eclipse.org/c/mylyn/org.eclipse.mylyn.docs.git/ Web]
 +
* Mylyn Incubator:
 +
** <code>master</code> &nbsp;&nbsp; 3.x stream - '''git://git.eclipse.org/gitroot/mylyn/org.eclipse.mylyn.incubator.git''' &nbsp;&nbsp; [http://git.eclipse.org/c/mylyn/org.eclipse.mylyn.incubator.git/ Web]
 +
* Mylyn Reviews:
 +
** <code>master</code> &nbsp;&nbsp; 1.x stream - '''git://git.eclipse.org/gitroot/mylyn/org.eclipse.mylyn.reviews.git''' &nbsp;&nbsp; [http://git.eclipse.org/c/mylyn/org.eclipse.mylyn.reviews.git/ Web]
 +
* Mylyn Tasks:
 +
** <code>master</code> &nbsp;&nbsp; 3.x stream - '''git://git.eclipse.org/gitroot/mylyn/org.eclipse.mylyn.tasks.git''' &nbsp;&nbsp; [http://git.eclipse.org/c/mylyn/org.eclipse.mylyn.tasks.git/ Web]
 +
* Mylyn Versions:
 +
** <code>master</code> &nbsp;&nbsp; 1.x stream - '''git://git.eclipse.org/gitroot/mylyn/org.eclipse.mylyn.versions.git''' &nbsp;&nbsp; [http://git.eclipse.org/c/mylyn/org.eclipse.mylyn.versions.git/ Web]
 +
 
 +
Also see [http://wiki.eclipse.org/index.php/Mylyn/Integrator_Reference#Building_on_Mylyn policy for supported Eclipse versions]. Branched projects, if any, are updated with each release.
 +
 
 +
==== Maintenance Branches ====
 +
 
 +
Changes should be committed to master and cherry-picked onto maintenance branches to be included in service releases.
 +
 
 +
* <code>e_3_8_m_3_8_x</code> &nbsp; &nbsp; Mylyn 3.8.x stream (corresponds to Mylyn Docs 1.7.x)
 +
 
 +
==== End-of-life branches ====
 +
 
 +
* <code>e_3_8_m_3_7_x</code> &nbsp; &nbsp; Mylyn 3.7.x stream for Eclipse 3.8
 +
* <code>e_3_7_m_3_6_x</code> &nbsp; &nbsp; Mylyn 3.6.x stream for Eclipse 3.7
 +
* <code>e_3_7_m_3_5_x</code> &nbsp; &nbsp; Mylyn 3.5.x stream for Eclipse 3.7
 +
* <code>e_3_6_m_3_4_x</code> &nbsp; &nbsp; Mylyn 3.4.x stream for Eclipse 3.6
 +
* <code>e_3_6_m_3_3_x</code> &nbsp; &nbsp; Mylyn 3.3.x stream for Eclipse 3.6
 +
* <code>e_3_5_m_3_3_x</code> &nbsp; &nbsp;  Mylyn 3.3.x stream for Eclipse 3.5
 +
* <code>e_3_4_m_3_3_x</code> &nbsp; &nbsp; Mylyn 3.3.x stream for Eclipse 3.4
 +
* <code>e_3_5_m_3_2_x</code> &nbsp; &nbsp; Mylyn 3.2.x stream for Eclipse 3.5
 +
* <code>e_3_4_m_3_2_x</code> &nbsp; &nbsp; Mylyn 3.2.x stream for Eclipse 3.4
 +
* <code>e_3_3_m_3_2_x</code> &nbsp; &nbsp;  Mylyn 3.2.x stream for Eclipse 3.3
 +
* <code>e_3_4_m_3_1_x</code> &nbsp; &nbsp; Mylyn 3.1.x stream for Eclipse 3.4
 +
* <code>e_3_3_m_3_1_x</code> &nbsp; &nbsp;  Mylyn 3.1.x stream for Eclipse 3.3
 +
* <code>e_3_4_m_3_0_x</code> &nbsp; &nbsp; Mylyn 3.0.x stream for Eclipse 3.4
 +
* <code>e_3_3_m_3_0_x</code> &nbsp; &nbsp;  Mylyn 3.0.x stream for Eclipse 3.3
 +
* <code>e_3_4_m_2_x</code> &nbsp; &nbsp; Mylyn 2.x stream for Eclipse 3.4
 +
* <code>e_3_3_m_2_x</code> &nbsp; &nbsp;  Mylyn 2.x stream for Eclipse 3.3
 +
* <code>e_3_2_m_2_0</code> &nbsp; &nbsp;  Mylyn 2.0 stream for Eclipse 3.2
 +
* <code>e_3_3_m_1_0</code> &nbsp; &nbsp;  Mylyn 1.0 stream for Eclipse 3.3M4
 +
* <code>e_3_2_m_1_0</code> &nbsp; &nbsp;  Mylyn 1.0 stream for Eclipse 3.2
 +
* <code>e_3_1</code> &nbsp; &nbsp; Mylyn 0.6 for Eclipse 3.1
  
'''Active branches:'''
 
* [http://www.eclipse.org/mylyn/doc/dev/mylyn.psf <code>HEAD</code>]: Mylyn 2.0 stream for Eclipse 3.3 (latest 3.3 milestone)
 
* [http://www.eclipse.org/mylyn/doc/dev/mylyn-e_3_2_m_2_0.psf <code>e_3_2</code>]: Mylyn 2.0 stream for Eclipse 3.2 (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.
 
* [http://www.eclipse.org/mylyn/doc/dev/mylyn-e_3_3_m_1_0.psf <code>e_3_3_m_1_0</code>]: Mylyn 1.0 stream for Eclipse 3.3 (currently supports 3.3M4 only)
 
* [http://www.eclipse.org/mylyn/doc/dev/mylyn-e_3_2_m_1_0.psf <code>e_3_2_m_1_0</code>]: Mylyn 1.0 stream for Eclipse 3.2
 
'''End-of-life branches:'''
 
* [http://www.eclipse.org/mylyn/doc/dev/mylyn-compatibility.psf <code>compatibility</code>]: required for building Mylyn 2.0, prevent <code>org.eclipse.mylar</code> plug-ins from loading
 
* [http://www.eclipse.org/mylyn/doc/dev/mylyn-e_3_1.psf <code>e_3_1</code>]: Mylyn 0.6 for Eclipse 3.1
 
 
'''Other:'''
 
'''Other:'''
* [http://www.eclipse.org/mylyn/doc/dev/mylyn-web.psf Web site]: for updating eclipse.org/mylyn
+
* Web site &nbsp; &nbsp; for updating eclipse.org/mylyn [http://www.eclipse.org/mylyn/doc/dev/mylyn-web.psf PSF File]
 
* <code>:pserver:dev.eclipse.org:/cvsroot/tools</code> can be used for manual checkout
 
* <code>:pserver:dev.eclipse.org:/cvsroot/tools</code> can be used for manual checkout
  
=== JUnit tests ===
+
=== Target Environment ===
Each component has it's own All<Component>Tests suite.  If not familiar with running PDE JUnit tests, refer to the [http://help.eclipse.org/help32/index.jsp?topic=/org.eclipse.pde.doc.user/guide/tools/launchers/eclipse_main.htm Eclipse Documentation].
+
* Add a ''credentials.properties'' file to org.eclipse.mylar.context.tests and put the following into it:
+
    user: <user>
+
    pass: <pass>
+
* For <user> use "tests<at sign>mylar.eclipse.org".  For <pass> use "<project's name lowercase>test".  If you have any trouble making this work email mylar-dev@eclipse.org.
+
* Add the following to the test configuration under Arguments -> VM Arguments: -enableassertions -Xmx384M
+
Test suites (in <code>org.eclipse.mylar.tests</code>):
+
* '''<code>AllTests</code>''': all of the automatic tests, should always pass, run as a ''JUnit Plug-in Test''
+
* '''<code>AllStandaloneTests</code>''': do not require workbench, can run as ''JUnit Test'', subset of <code>AllTests</code>
+
* '''<code>AllFragileWebTests</code>''': web connector tests, some templates may periodically fail
+
  
=== Manual tests ===
+
Mylyn depends on a number of libraries from other Eclipse projects. The <code>org.eclipse.mylyn-target</code> project provides target environment definitions that specify all required dependencies. After following the steps under [[#Checkout|Checkout]] go to ''Window > Preferences'' and open the ''Target Platform'' page. Select one of the mylyn target definitions. Generally, ''mylyn-dev-base'' is the recommended choice.
  
The manual tests can be found on the '''[[Mylyn Testing]]''' page.
+
* mylyn-dev-base - Targets the lowest support Eclipse version. Includes sources and additional integration features for development.
* Component owners are responsible for maintaining their respective manual tests and ensuring they are covered two days prior to release.
+
* mylyn-dev-latest - Targets the highest support Eclipse version. Includes sources and additional integration features for development.
 +
* mylyn-e* - Target defintions used by the build. May only contain the minimal requirements excluding sources.
  
Trac Connector
+
=== API Baseline ===
* A Trac test repository that offers anonymous access through XML-RPC is available at http://mylar.eclipse.org/tractest. Feel free to create or modify any tickets.
+
  
=== Self-hosting ===
+
An API baseline for the latest releases is available from the [http://www.eclipse.org/mylyn/downloads/archive.php#baseline download archive]. Follow these instructions to configure the API baseline in your workspace:
Self-hosting, also known as working bootstrapped (i.e. self-hosted) makes [http://en.wikipedia.org/wiki/Eat_one's_own_dog_food 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 <tt>C:/Dev</tt> workspace directory as an example.
+
# Extract the Mylyn API baseline zip archive
 +
# Add the baseline under Windows > Preferences > Plug-in Development > API Baselines pointing to the extracted directory
  
* Create a new directory for your build workspace, e.g.: <tt>C:/Dev/build-e3.3</tt>
+
=== Markers ===
* Launch Eclipse with this workspace, e.g.: <tt>C:\Apps\eclipse-3.3\eclipse.exe -data C:\Dev\build-3.3</tt>
+
* Check out Mylar from CVS into this workspace, see [[#Setup]]
+
* Create a new Launch Configuration:
+
** Select''Run -> Run...'' -> create a new Eclipse Application.
+
** Call the application ''Mylar Bootstrap''.
+
** On the ''Main'' tab, set the ''Location''
+
*** You can use the existing workspace that you used Mylar with previously
+
*** You can create a new workspace (e.g. <tt>C:/Dev/bootstrap</tt>)
+
* Launching with this launch configuration will give you a second workbench with Mylar.  This workbench will be created based on the target platform (the workbench you're launching from) and the plugins in <tt>C:/Dev/build-3.3</tt>.
+
* Do your development in the runtime workspace (<tt>C:/Dev/workspace</tt>).
+
* Whenever your changes make it into HEAD that you would like to use, close your runtime workspace (<tt>C:/Dev/workspace</tt>), update from CVS in the build workspace (<tt>C:/Dev/build-3.3</tt>), and then re-launch your runtime workspace. 
+
  
Notes:
+
The general policy is that plug-ins should not have any errors or warning markers since these indicate potential problems or API insufficiencies. In practice, we do not have the capacity to address all warnings or the cost outweighs the benefit or warnings result out of intentional design decisions, e.g. usage of deprecated APIs for
* The launching workspace will typically consume very little memory.  
+
maintaining backwards compatibility.  
* Working in bootstrap mode means you have the source code checked out at least twice, once to bootstrap Mylar, 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 ==
+
To reduce the number of warnings we have established the following policies for usage of internal packages:
  
=== Getting Started ===
+
# Plug-ins are allowed to use internals within the boundaries of their component (e.g. o.e.m.bugzilla.ui may access internals of o.e.m.bugzilla.core). We have generally allowed that through x-friends relationships in plug-in manifests.
* Use Bugzilla for all of your communication. This helps committers track the contribution.
+
# It's generally okay to use provisional APIs. We have made these accessible through classpath filters: Project Properties > Java Build Path > Libraries > Plug-in Dependencies > Access rules. It's common that plug-ins have a rule to make org/eclipse/mylyn/internal/provisional/** accessible.
* 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.
+
# In cases where platform internals need to be accessed due to a lack of API it's okay to make the specific classes or packages accessible. These cases should be documented on {{bug|233055}}.
* For contribution ideas see the list of [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=&keywords_type=allwords&keywords=helpwanted&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&emailtype1=substring&email1=&emailtype2=substring&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] to find one that interests you, file a new bug of your own, or email mylyn-dev for ideas.
+
# Test plug-ins are allowed to use all internals.
  
=== Patches ===
+
Additionally, it is recommend to create custom filters in the workspace to hide remaining warnings that will not get addressed in the short time. Filter can be configured through the view menu of the Markers view.
  
'''Creating'''
+
=== JUnit Tests ===
* 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 <tt>org.eclipse.mylar/developer/mylar-settings-formatter.xml</tt> into <i>Window -> Preferences -> Java -> Code Style -> Formatter</i>.  Format code using Eclipse's formatter (Ctrl+Shift+F) and ensure that no  have been added.
+
* Add an <tt>@author</tt> tag to each class that you create or make significant modification to, placed below any existing author tags and indicating the bug, e.g.: <tt>@author Rob Elves (bug 160315)</tt>
+
* Ensure that there is no console output.  For logging errors use MylarStatusHandler.
+
  
'''Submitting'''
+
The ''bundle''.tests bundles (e.g. org.eclipse.mylyn.tasks.core.tests) are unit tests; the bundles are fragments to enable unit testing with package private access. The ''component''.tests bundles (e.g. org.eclipse.mylyn.tasks.tests) are integration tests that run against the API.
* 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 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).
+
  
== Committers ==
+
Each component has it's own All<Component>Tests suite.  If not familiar with running PDE JUnit tests, refer to the [http://help.eclipse.org/help32/index.jsp?topic=/org.eclipse.pde.doc.user/guide/tools/launchers/eclipse_main.htm Eclipse Documentation].
  
The [http://www.eclipse.org/projects/dev_process/Eclipse_Standard_TopLevel_Charter_v1.0.php Eclipse Charter] explains how developers can gain commit rights.
+
Tests that connect to repositories require a ''$HOME/.mylyn/credentials.properties'' file that specifies authentication information. The file needs to have the following content:
 +
user: <user>
 +
pass: <pass>
 +
* For <user> use ''tests@mylyn.eclipse.org''. For <pass> use ''mylyntest''. 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
  
=== Participation ===
+
Test suites in org.eclipse.mylyn.tests:
Committers should:
+
* '''<code>AllTests</code>''': all automatic tests, should always pass, run as a ''JUnit Plug-in Test''
* Sign up for all of the project mailing lists.
+
* '''<code>AllHeadlessStandaloneTests</code>''': do not require workbench, can run as ''JUnit Test'', subset of <code>AllTests</code>
* Read the newsgroup regularly, and respond to posts in their area of expertise.
+
* '''<code>AllConnectorTests</code>''': all automatic tests for repository connectors, requires network access
* Respond to mylar-dev email in their area of expertise.
+
* Watch and update all wiki pages related to components that they contribute to.
+
  
=== Communication ===
+
Test suites in org.eclipse.mylyn.tests.ui:
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. 
+
* '''<code>AllUiTests</code>''': all automatic SWTbot-based UI tests
  
* 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.
+
Test suites in org.eclipse.mylyn.tests.performance:
 +
* '''<code>AllPerformanceTests</code>''': all performance tests
  
* 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.
+
=== Manual tests ===
  
* 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.
+
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.
  
* Never turn feedback or discussion away by [http://en.wikipedia.org/wiki/Flame_war#Causes_of_flaming 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.
+
Trac Connector
 +
* A Trac test repository that offers anonymous access through XML-RPC is available at http://mylyn.eclipse.org/tractest. Feel free to create or modify any tickets.
  
* 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.
+
=== Self-hosting ===
  
=== Web site authoring ===
+
Self-hosting, also known as working bootstrapped (i.e. self-hosted) makes [http://en.wikipedia.org/wiki/Eat_one's_own_dog_food eating your own dog food] easier and avoids having to update to dev builds.
* 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 ===
+
The following is an example of how to set up a bootstrap workspace, work and runtime workspace. The result is an folder with the following three workspaces:
* Using PDE Build support to create a Mylar distribution from HEAD, using a plain Eclipse 3.2
+
* Mylyn-Bootstrap
** org.eclipse.mylar-feature/feature.xml -> Overview -> change version number to current date (e.g. 0.4.7.v20060125-0800)
+
* Mylyn-Work
*** On Plug-ins tab -> Versions... -> Force feature version into plug-in and fragment manifests
+
* Mylyn-Runtime
*** 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:
+
Please follow the steps:
* 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 ==
+
* Download and install Eclipse 3.7 or later
 +
* Start Eclipse and create an workspace called Mylyn-Bootstrap
 +
* Install dependencies using File > Import > Install Software Items from File: [http://eclipse.org/mylyn/doc/dev/mylyn-bootstrap.p2f mylyn-bootstrap.p2f]
 +
* Import projects using File > Import > Team Project Set: [http://eclipse.org/mylyn/doc/dev/mylyn-dependencies.psf mylyn-dependencies.psf]
 +
* Switch to the Git Repository Exploring Perspective and clone the Git repositories listed under [[Mylyn/Contributor_Reference#Checkout]]
 +
* Use Import Projects from the Git Repository Exploring Perspective to add the projects to your workspace
 +
* Create a new Launch Configuration:
 +
** Select ''Run -> Run...'' -> create a new Eclipse Application.
 +
** Call the application ''Mylyn Work''.
 +
** On the ''Main'' tab, set the ''Location''
 +
*** You can use an existing workspace
 +
*** You can create a new workspace (e.g. <tt>Mylyn-Work</tt>)
  
Update site: http://download.eclipse.org/technology/mylar/update-site/dev/sandbox
+
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 installed plugins. This workspace needs to be setup following the steps under [[#Setup]]:
  
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 <code>org.eclipse.mylar/sandbox</code> 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.
+
* [[#Checkout]]
 +
* [[#Target_Environment]]
 +
* [[#API_Baseline]]
 +
* [[#Markers]]
 +
* [[#JUnit_Tests]]
 +
 
 +
Do your development in the Mylyn-Work workspace. Whenever your changes make it into master that you would like to use, close your Mylyn-Work workspace, pull from Git in the Mylyn-Bootstrap workspace, and then re-launch your Mylyn-Work 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.
 +
=== Self-hosting for Luna (and newer)===
 +
Starting for Eclipse 4.4 (Luna) there is a new way how you can setup the bootstrap workspace, work and runtime workspace.
 +
Here a list of the needed actions.
 +
<br>1) download latest Eclipse version from [http://download.eclipse.org/eclipse/downloads/ Eclipse Downloads] (actual this is [http://download.eclipse.org/eclipse/downloads/drops4/S-4.4M3-201310302000/ Eclipse 4.4M3])
 +
<br>2) download the latest Mylyn Baseline from [http://www.eclipse.org/mylyn/downloads/archive.php Mylyn Downloads] (at the time of writing this is [http://www.eclipse.org/downloads/download.php?file=/mylyn/drops/3.10.0/v20131025-2037/mylyn-3.10.0.v20131025-2037.zip Mylyn 3.10])
 +
<br>3) start Eclipse and create workspace Mylyn-Bootstrap
 +
<br>4) install the "Eclipse Git Team Provider" and "Mylyn Review Connector: Gerrit".<br>You can do the install with one of the following Mylyn-Bootstrap_4.4.p2f or Mylyn-Bootstrap_4.4_Gerrit.p2f definition files if you have the folder org.eclipse.mylyn.commons/org.eclipse.mylyn.development already on your disk.
 +
<br>5) change Git Preference "Default repository folder" to ${workspace_loc}
 +
<br>6) Optional: Add https://git.eclipse.org/r as an Gerrit Code Review Task Repository. You should do this because some other steps are easier.
 +
<br>7) Switch to the Git Repository Exploring Perspective and Clone the org.eclipse.jdt.core Git Repository but only import the org.eclipse.jdt.annotation_v1 project.
 +
<br>&nbsp;&nbsp;&nbsp;&nbsp;we need this as long as we not use java 8.
 +
<br>8) Switch to the Git Repository Exploring Perspective and Clone the org.eclipse.mylyn.commons.git Git Repository.<br>If you not use Gerrit use ssh://XXX@git.eclipse.org/gitroot/mylyn/org.eclipse.mylyn.commons.git and change xxx to your userid<br>import the projects into your workspace
 +
<br>9) set "Plug-in Development" Preference "API Baselines to the downloaded Baseline folder
 +
<br>10) set the Target Platform to mylyn-bootstrap-e4.4
 +
<br>11) Now continue with adding the other Git repositories the same way you did in 6) and import the projects into workspace
 +
*git.eclipse.org/gitroot/mylyn/org.eclipse.mylyn.git
 +
*git.eclipse.org/gitroot/mylyn/org.eclipse.mylyn.context.git
 +
*git.eclipse.org/gitroot/mylyn/org.eclipse.mylyn.tasks.git
 +
*git.eclipse.org/gitroot/mylyn/org.eclipse.mylyn.builds.git
 +
*git.eclipse.org/gitroot/mylyn/org.eclipse.mylyn.docs.git
 +
*git.eclipse.org/gitroot/mylyn/org.eclipse.mylyn.reviews.git
 +
*git.eclipse.org/gitroot/mylyn/org.eclipse.mylyn.versions.git
 +
<br>12) delete the following projects from workspace (sorry did not know how to fix the errors)
 +
*org.eclipse.mylyn.builds.sample.ant
 +
*org.eclipse.mylyn.builds.sample.mvn
 +
*org.eclipse.mylyn.builds.sample.mvn.reactor
 +
*org.eclipse.mylyn.builds.sample.mvn.reactor.module1
 +
*org.eclipse.mylyn.builds.sample.mvn.reactor.module2
 +
*org.eclipse.mylyn.docs.epub.ant.core
 +
*org.eclipse.mylyn.docs.epub.tests
 +
*org.eclipse.mylyn.wikitext.core.maven
 +
*org.eclipse.mylyn.wikitext.help.ui
 +
*org.eclipse.mylyn.wikitext.help.sdk
 +
*org.eclipse.mylyn.subclipse.core
 +
*org.eclipse.mylyn.subclipse.ui
 +
<br>13) Only if you did not do step 6): If you needed to fetch reviews from gerrit change the .git/config file and add the remote "gerrit" keys (url,fetch,push)
 +
<br>14) Now finish the setup
 +
* "Import Preferences" (from  Java Package Explorer) {workspace}/org.eclipse.mylyn.commons/org.eclipse.mylyn.development/developer/markers.epf
 +
* Import the Java Code Formater from {workspace}/org.eclipse.mylyn.commons/org.eclipse.mylyn.development/developer/mylyn-settings-formatter.xml
 +
* Import the Java Code Templates from {workspace}/org.eclipse.mylyn.commons/org.eclipse.mylyn.development/developer/codetemplates.xml>br>you now can change the Name in the Header of the "New Java Files" if you are not at Tasktop (currently the workspace setting is only use in the connector-bugzilla-rest all other project use project specific settings)
 +
<br>15) launch Mylyn-Work  or Mylyn-Work-Mac
 +
<br>16) If you want to copy definitions for the Task Repositories and Task List entries Quit the new launch application and copy the following files from the previous workspace to the new created workspace. Directory is .metadata/.mylyn/
 +
*repositories.xml.zip
 +
*tasks.xml.zip
 +
relaunch Mylyn-Work  or Mylyn-Work-Mac
 +
<br>17) fix the userId and passwords from your Task Repositories
 +
<br>18) now repeat steps 5 - 14 but skip step 7) and use "Running Platform"  as target in step 10
 +
 
 +
== Incubator ==
 +
 
 +
The Mylyn Incubator is a set of projects and feature contributors use for experimentation.  These features are not intended to be used for daily development.  Incubator features include experimental connectors and bridges, experimental UI features, and developer tools.  To use Incubator tools either check them out of the version control, or install them using the Incubator update site.
  
 
=== Dev tools ===
 
=== Dev tools ===
Line 209: Line 843:
  
 
* '''Interest Level Decorator''': displays the floating point interest level of elements.  Enable via ''Decorators'' preference page.
 
* '''Interest Level Decorator''': displays the floating point interest level of elements.  Enable via ''Decorators'' preference page.
 +
 +
* '''Repository Spy''': displays the repositories with all their atrtributes in a separate view. Allows the deletion of selected properties.
 +
 +
* '''Properties View sources''': Shows properties of items selected in the Tasklist View or Task Repositories view in the standard Eclipse Properties View.
  
 
=== Experimental tools ===
 
=== Experimental tools ===
  
The following experimental views can be opened via the ''Mylar Sandbox'' view category or accessed via the ''Mylar -> Sandbox'' preference page.
+
The following experimental views can be opened via the ''Experimental'' view category or accessed via the ''Tasks -> Experimental'' preference page.
  
* '''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 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.
+
* '''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 [https://bugs.eclipse.org/bugs/show_bug.cgi?id=107542 bug 107542].
+
* '''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 [https://bugs.eclipse.org/bugs/show_bug.cgi?id=107542 bug 107542].
  
 
== Tips and Tricks ==
 
== Tips and Tricks ==
Line 229: Line 867:
 
=== Code ===
 
=== Code ===
  
* For error handling use <code>MylarStatusHandler</code>.
+
* For error handling use <code>StatusHandler</code> and pass an <code>IStatus</code> object.  Note that some of the other Mylyn code uses the convenience methods on <code>StatusHandler</code>, but we are phasing those out because they do not pass the plug-in ID that the exception originated from.
 
* Use <code>WorkbenchJob</code> for running jobs that should only run when the workbench is active.  Not doing this can cause errors on workbench shutdown (e.g. [https://bugs.eclipse.org/bugs/show_bug.cgi?id=178409 bug 178409)].
 
* Use <code>WorkbenchJob</code> for running jobs that should only run when the workbench is active.  Not doing this can cause errors on workbench shutdown (e.g. [https://bugs.eclipse.org/bugs/show_bug.cgi?id=178409 bug 178409)].
 
* When using <code>String.toLowerCase()</code>, use <code>String.toLowerCase(Locale.ENGLISH)</code> to ensure locale safety (see [https://bugs.eclipse.org/bugs/show_bug.cgi?id=168652 bug 168652]).
 
* When using <code>String.toLowerCase()</code>, use <code>String.toLowerCase(Locale.ENGLISH)</code> to ensure locale safety (see [https://bugs.eclipse.org/bugs/show_bug.cgi?id=168652 bug 168652]).
Line 235: Line 873:
 
* 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).
 
* 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 <code>getMonitor()</code> instead of <code>getDisplay()</code> when you want to position a UI element on a specific coordinate of the screen.
 
* For the sake of multi-monitor setups, use <code>getMonitor()</code> instead of <code>getDisplay()</code> when you want to position a UI element on a specific coordinate of the screen.
 +
* To improve the speed of decorators use setUseHashlookup(true) on all structured viewers.
  
 
=== Bugzilla ===
 
=== Bugzilla ===
Line 245: Line 884:
  
 
=== Debugging ===
 
=== Debugging ===
 +
 +
* '''Task List problems''': do not ask users to send or attach their Task List, since it can contain highly sensitive information.  If needed ask the user to create a new workspace and try to reproduce the problem there, ensuring that they have not included any user private or company private information, and have them send that.
  
 
* '''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.
 
* '''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.
Line 250: Line 891:
 
** Attempt to find the earliest exception thrown within the in the plug-in's activation process.  For example, this could occur in <code>TasksUiPlugin.start()</code> or <code>TasksUiPlugin.<init></code>.
 
** Attempt to find the earliest exception thrown within the in the plug-in's activation process.  For example, this could occur in <code>TasksUiPlugin.start()</code> or <code>TasksUiPlugin.<init></code>.
 
** 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.
 
** 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 -debug option (or use java.exe instead javaw.exe on windows), then hit a Ctrl-Break few times on the console window during that long synchronization to capture the thread dump (Ctrl-\ on Linux, or send SIG_QUIT signal). Also see: [http://weblogs.java.net/blog/mandychung/archive/2005/11/thread_dump_and_1.html Thread Dump and Concurrency Locks]
+
* '''Getting a thread dump''' (when Eclipse hangs):   
 +
** On Windows use the tool found at [http://www.adaptj.com/root/main/download the adaptj home page]:
 +
*** Follow the link and select button "Launch" and run the applet
 +
*** Select menu Process > Thread Dump
 +
*** In the combo box "Process ID" select the Java VM and click OK
 +
** Or, run Eclipse with the <code>-debug</code> option (or use <code>java.exe</code> instead <code>javaw.exe</code> on windows), then
 +
*** On Windows: Hit a <code>Ctrl-Break</code> few times on the console window during that long synchronization to capture the thread dump
 +
** Or, on Linux: Use <code>Ctrl-\</code> on the console or send SIG_QUIT signal: <code>kill -SIGQUIT ''pid''</code>
 +
** Or, with jconsole (requires 1.5 jdk, works on any OS):
 +
*** Launch <tt>eclipse -vmargs -Dcom.sun.management.jmxremote</tt>
 +
*** Launch the JDK's jconsole tool. You can attach to the Java Process and copy&paste the thread dump.
 +
** Use <code>[http://java.sun.com/j2se/1.5.0/docs/tooldocs/share/jps.html jps]</code> to find the PIDs of Java processes and <code>[http://java.sun.com/j2se/1.5.0/docs/tooldocs/share/jstack.html jstack]</code> to show the stack trace of Java processes: <code>jstack ''pid''</code>
 +
*** Supported starting JDK 5 for UNIX / JDK 6 for Windows
 +
** See this [http://blogs.sun.com/alanb/entry/jstack Weblog on jstack]
 +
** Also see [http://weblogs.java.net/blog/mandychung/archive/2005/11/thread_dump_and_1.html 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
 
* '''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 ===
+
[[Category:Mylyn]][[Category:How to Contribute]]
 
+
To migrate between Eclipse 3.3M4 and 3.3M5 (as of I20070205-1824):
+
 
+
* Get latest milestone or integration build: http://download.eclipse.org/eclipse/downloads/
+
 
+
* 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 ([https://bugs.eclipse.org/bugs/show_bug.cgi?id=172975 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.
+

Revision as of 12:47, 7 May 2015

See also: helpwanted bugs, eclipse dev, source repository, website repository

Project Structure

The Mylyn project is structured into sub-projects that address different areas of Application Life-cycle Management. Please see Mylyn/Charter for the top-level project charter.

Artifacts are published in a number of Mylyn/Repositories. The main repository aggregates sub-projects that participate in Mylyn releases. The participating projects are listed in the project plan. The main Mylyn update site features are mature components that are supported by the Mylyn project committers and may be distributed as part of the Eclipse Downloads.

Sub-projects are encouraged to provide a framework component and reference implementations called Connectors that extend Mylyn to different task management systems and focus the artifacts that you work with when you activate a task (formerly called Bridges).

Feature Maturity

Mylyn features vary in UI maturity and availability 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 sub-projects.)

Mature: packaged Eclipse downloads and available via main update site

  • UI quality: Eclipse SDK 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 burden 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 nightly 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 Incubation 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 Extras.

Creating New Components

Most sub-projects host a framework component and one or more reference implementations. When new code is brought into Mylyn it may be added as a sub-project, sub-sub-project or as a component of an existing project. The right organisational structure depends on the needs of the development community and the scope and process of the existing projects. Criteria that could qualify a component to be split out as a separate project:

  • A component requires incubation status (e.g. for parallel IP) but the framework project has already matured.
  • The committer set of the component is not a subset of the committer set of the framework project.
  • A component wants to release more frequently than its framework project, i.e. it follows it's own project plan.
  • A component publishes its own APIs and its scope and community are significant that it requires its separate management structure such as a Bugzilla product, news group etc.

Getting Started

The Mylyn project places a very high value on community contributions. This document is intended to help those interested in contributing to Mylyn. It communicates our conventions and discusses ways to get your contributions prioritized.

Individual Contributors

A significant portion of Mylyn contributions have been made by individuals wanting to make the tool or framework work better for them. There are several ways that individuals can get involved with the project:

  • Mentoring: if you are an experienced user, you can support newcommers by providing feedback using the community channels
  • Casual contribution: we have a large number of very valuable casual contributors who provide patches for their pet bugs, or enhancements that either they would find valuable or that they want to share with others. If you are interested but don't know where to start look first through the short list of bugday bugs, and then through the longer helpwanted list.
    • bugday bugs: a short list of highly relevant bugs for getting started
    • helpwanted bugs: a longer list of all bugs targeted at community contributions
  • Working towards commit rights: The Eclipse and Mylyn development processes make it easy to make regular contributions without requiring commit rights, but frequent contributors may be interested in earning commit rights. Commit rights come with a significant overhead of user support as well as the need to follow the project's priorities for contributions. They require you to participate in the planning and of the project, and allow you influence the direction of the tool and framework. If you are interested in becoming a committer we recommend letting one of the existing committers know so that they can mentor you and help build a trust relationship. It can also help to identify a separable component of the project that you are interested in taking responsibility for, since Mylyn commit rights are assigned per-component.

Integrators and Vendors

Those building both closed and open source tools on top of Mylyn may be interested in evolving the Mylyn APIs to ensure that that the framework meets their needs. We welcome such contributions just as we welcome individuals making improvements to the tool, since they help make Mylyn a better framework for all. The Individual Contributor points above apply to integrators and vendors interested in contributing or earning commit rights. In addition, the following tips may be of interest:

  • If interested in exploring Mylyn integration, consider dialing into the our monthly call and adding an agenda item on the Mylyn Meetings page.
  • Vendors are welcome, so make yourself known. We recommend using your company name for Bugzilla email addresses. If you have a product built on Mylyn and need a bug fixed, we recommend voting for it with that email address. The Mylyn project prioritizes bugs according to how much overall benefit they will have to users, and as such commercial integrations are an important part of that prioritization. If the bug does not fit with the project's priorities we will encourage you to provide a patch.
  • Consider making a bug titled "support integration with <your tool>". We use these bugs for discussing integration issues particular to a specific tool or technology and leave them open for ongoing API or UI discussion needs.

Links

Contributors

Overall Process

The best way to get your contribution into the code base is to stick to this workflow:

  1. Sign the CLA by logging in at https://projects.eclipse.org/user/login/sso (You only need to do this once).
  2. Install the Tools, including EGit, Mylyn Bugzilla, and Gerrit.
  3. Setup your Eclipse Environment.
  4. Find or file a Bug.
  5. Write the Code.
  6. Push a Review.

Contributor Tools

In this guide, we'll be sharing the basics of what you need to know to work with Bugzilla tasks, EGit changes and Gerrit reviews, along with recommendations about best practices for using these tools.

For more information on how to work with EGit and Gerrit Reviews, refer to the Eclipse help documentation. (At the time of this writing, some of those documents are a bit out of date. The tooling has improved signficantly and much of the workflow is much simpler now.) There are also a number of excellent tutorials (google "eclipse gerrit"), including this one.

Using Mylyn

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 Reviews match up to a single Bugzilla report, making it easy to navigate from changes to bugs.

Installing

All the tools we need are conveniently available as part of many of the standard Eclipse distributions. You can also install the tools from their respective p2 repositories into any Eclipse instance using Install New Software from the Help menu. Using the repositories below will help ensure that you have the latest and greatest versions of each tool.

Setting Up

Register a Gerrit Account

To use the review server a few steps are required:

You are now ready to submit changes to Gerrit.

Connect to Bugzilla

All Eclipse projects use Bugzilla for issue tracking. Mylyn makes connecting to Bugzilla easy.

  1. Connect to the Eclipse Bugzilla Repository:
    1. Click the "Add Task Repository" button in the Task Repositories View.
    2. Select Bugzilla.
    3. In the Server section, Select Eclipse.org from the drop down menu.
    4. Add the credentials you created above and click "Finish".
  2. Setup a query for your Reviews:
    1. Right-Click in the Task List and select "New" -> "Query..."
    2. Select the Repository you just created, click through to "Create Query using Form".
      • To find bugs to work on, select some items in Product. For example "Mylyn Tasks".
      • You could narrow this further, by selecting Components you are interested in or bugs with Status "New".
      • Under "More Options", try adding the "helpwanted" keyword to find bugs that the Mylyn team has identified as good for contributors to tackle.

Connect to Gerrit and Git

This part is also easy, and the great thing is that you get the source code and reviews support from the same place.

  1. Connect to the Gerrit Repository:
    1. Click the "Add Task Respository" button in the Task Repositories View.
    2. Select Gerrit Code Review.
    3. Enter the server address: https://git.eclipse.org/r
    4. Add your credentials and validate.
  2. Setup a query for your Reviews:
    1. Create a New Query in the Task List using the repository and "My Changes".
    2. There won't be anything there yet of course. To get an idea of what the reviews process looks like, try "Open Changes by Project" and search for a Mylyn project that interests you.
    3. Or, try the new Gerrit Dashboard!
  3. Import the source code:
    1. Under File > Import select "Projects from Git" and select Gerrit from the list on the next page.
    2. Select the repository you're interested in from the list of Git repositories hosted on the Eclipse.org Gerrit instance. If you want to contribute to Mylyn Tasks for example, select the mylyn/org.eclipse.mylyn.tasks repository.
    3. The repository is automatically cloned and we can select all projects to import on the last page. (If an error is displayed that the SSH key is invalid or missing it needs to be generated first in the Eclipse preferences under General > Network Connections > SSH2 and uploaded to Gerrit. See above)
    4. Note that once all projects have been imported you can get rid of any API baseline errors by opening the Eclipse preferences and selecting the Plug-in Development > API Baselines page and setting Missing API baseline to Ignore.

Working with Bugzilla

Key Points

  • For contribution ideas see #Individual_Contributors to find an enhancement or defect that interests you, file a new bug of your own, or email mylyn-dev for ideas. Often the best contributions come from people who have an "itch to scratch".
  • Before starting work:
    1. Comment on the corresponding bug, stating your interest and asking whether a committer or another contributor has any suggestions for the implementation approach.
    2. Propose a design, mentioning the key use cases, implementation, tests coverage, and UI changes or additions (if applicable). (You might skip this step if the required fix or proposed behaviour is clear.)
    3. Assign yourself to the bug.

Voting

Votes track the general interest in a particular bug. Bugs with more votes are more likely to get fixed. We encourage all in the community to vote for bugs, since it helps committers and contributors prioritize work.

Developing Code

Key Points

  • Follow Eclipse code conventions.
  • Ensure you've provided complete unit test coverage.
  • Add an @author tag to each class that you create or make significant modification to, placed below any existing author tags, e.g.: @author Awesome J. Contributor
  • Small is good! More focused changes will be reviewed more quickly and have a much better chance of being merged without major changes. If the bug you're working on involves complex changes, consider breaking your changes up into bite-sized pieces rather then tackling the whole thing in one review.

Writing Tests

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. Ensure that your test covers the addition or change to the existing functionality. For API changes it is often sufficient to have the public method covered.

Tests can sometimes take longer to write then the change itself! If you get stuck, ask a committer to assist you in designing tests appropriate to your case.

Working with mock test harnesses and UI can be especially challenging. Writing tests for UI components often involves a combination of unit and black-box testing. For example we might rely on other parts of the Mylyn UI (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 might 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 very 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: mylyn/graphics/ui.

Working with Reviews

The review process is the most important tool we use to ensure that Mylyn code is as high quality as possible. It can also be pretty intimidating for new contributors. But it shouldn't be. Think of it as an opportunity to gain from the experience of other developers. And to keep things in perspective, remember that many thousands of other developers might be made more happy by the change that you make -- or unhappy if it doesn't work correctly!

The best thing about the Gerrit based reviews process is that it means that all code gets reviewed in the same way, regardless of who wrote it. The only significant differences between contributors and committers are that only committers can approve commits (vote +2) and single contributions of over a 1,000 lines of code must go through extra IP process. (Another reason to keep those commits small.) So even if you never decide to become a Mylyn committer you can still make significant improvements to Mylyn!

Key Points

  • Ensure that your commit message is formatted correctly and has all of the information needed.
  • Before pushing your commit:
    • Ensure the the code does what you say it does by testing it thoroughly.
    • Be your own first reviewer. Go over your commit before pushing it. Often a second (or third, or fourth) self-review of the code will reveal issues that you'd missed.
  • After pushing your commit:
    • Add a link to the review in a comment on the original bug.
  • After recieving feedback:
    • Don't take reviews personally. Even seasoned Mylyn committers should expect to see -1 and -2 reviews. If all of our code was perfect the first time, we'd never need reviews. It's helpful especially at first to see reviews as a learning process.
    • Do respond to every comment. If you disagree with a point, that's ok -- explain why you did things the way you did.
    • Be patient and prepared to iterate. While some simple changes might get committed in a day or two, complex changes requiring input from contributors might require refinement over a few weeks. The Gerrit tools make this process much less painful then before.
  • After recieving your first +2:
    • Give yourself a well-deserved high-five. You're now a Mylyn contributor!
    • Find another bug!

Committing Changes

  1. Right click and select Team > Commit on any changed project or resource to display the git commit dialog.
  2. If you've activated the task, this will be populated with the following items, or you can enter them by hand:
    • The bug ID and a summary.
    • A "Task-Url:" entry active task allowing bugs to be traced to tasks.
  3. Click the rightmost two buttons on the commit dialog and the remaining two required entries will be added for you:
    • A Gerrit "Change-Id" entry. The entry is required for all changes pushed to Gerrit (to enable pushing new patch set versions to the same review)
    • A "Signed-off-by" entry. The entry is required as it confirms that you are in compliance with the Certificate of Origin.
  4. Edit the commit summary to describe the specific change you are making. This is not always the same as the bug summary. Your commit may only be addressing part of the issue. It is often helpful to other developers to add additional lines of description below the summary. Leave a one-line gap between the summary and further description.
  5. Ensure that the Author and Committer dialog entries match your Eclipse credentials. Like this: Awesome Contributor <awesome.contributor@awesome-company.com>
  6. Click "Commit". You can do a "commit and push" directly, but at least until you gain some experience it's probably a good idea to double-check your commit before pushing it.
    • Is everything that you expected to be there there?
    • Does the commit message match the example below?
Example Commit Message

The following is the standard commit message template which can be configured in Window -> Preferences -> Tasks -> Team:

${task.key}: ${task.description} 

Task-Url: ${task.url}

Note that often you'll want to edit the task description.

Here's an example of what a review message should look like:

999895: Improve sorting in task view

* Replaced random with alphabetical sorting
* Minor refactoring

Task-Url: https://bugs.eclipse.org/bugs/show_bug.cgi?id=999895
Change-Id: Ieb8caf92cd87899b125b89beb077a1d4f579ff23
Signed-off-by: Awesome Contributor <awesome.contributor@awesome-company.com>

The dialog should end up looking like this:

MylynContributorGuideGitCommit.png

Pushing Changes

After reviewing your submission, you can push it. There are many workflows that work well, but here's one relatively fool-proof approach:

  1. Pull or fetch to ensure that origin/master is as up to date as possible. This will help avoid future rebase trauma!
  2. Rebase on top of origin/master.
  3. Ensure that you are on the master branch. (If you're currently working on a topic branch, you could do this by checking out the master branch and then doing a hard reset to your topic. But make sure you've committed your changes first!)
  4. Right click on any changed project or resource and select Team > Push to Upstream.
  5. After pushing, you might want to create a seperate topic branch to help manage your change locally.

Subsequent Changes

Handling subsequent changes is easy, as long as you keep things simple and follow the recommendations below. Otherwise, you might end up doing a bit of juggling!

  1. After the initial commit, it is better not to rebase against master, unless you know there are signficant changes that have been committed in the meantime that you need to merge with. Rebasing within a review makes it more difficult to track changes between patch sets.
  2. Select "Amend Previous Commit", the first button in the commit dialog toolbar. This will ensure that the change has exactly the information Gerrit is expecting, and means that you won't have to deal with annoyances like squashing commits later.
  3. If you can't amend the commit, then ensure that the Change-Id: value matches whatever value is already there in the review. This is the only way that Gerrit associates your change with a particular review.
  4. In either case, you can freely edit the commit message to reflect your evolving change.

If things didn't turn out correctly and you get a reject message or something else unexpected happens, don't despair. With Git there is always a way to clean up any kind of mess, though it can take a bit of perserverance to discover how. The key thing to keep in mind is that there can only be one commit per review. So if you have multiple commits related to a change, you need to "squash" them into one change with the appropriate commit id. Most contributors sooner or later becomes familiar with the magical command line incantation: git rebase -i HEAD~2. See the git documentation for details. Alternatively, EGit has a new "Git Interactive Rebase" view that lets you perform this magic with a visual tool.

If someone else makes a change to your review -- and don't be offended if they do! -- and you want to incorporate that change into your subsequent changes, or if you don'thave the topic branch for one of your own changes, just do this:

  1. Fetch the change (Patch Set) using the Gerrit task editor.
  2. Checkout the master branch and reset it to the branch you've just checked out. (You may want to create a topic branch as well.)
  3. Then you can just amend any subsequent changes exactly as above.


Committers

Contributors who have made frequent and valuable contributions to Mylyn can become committers. The Eclipse Charter explains how.

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 mylyn-dev email in their area of expertise.
  • Watch and update all wiki pages related to components that they contribute to.

Communication

Mylyn 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.
  • Show respect to others in the community, whether they are making correct or incorrect assumptions about the tool or technology. When someone makes 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, are usually best avoided because they can result in misinterpretation, especially when there is a language or cultural barrier.

Handling Inappropriate Communication

In the vast majority of cases, following the above guidelines has lead to the high quality communication that our user and contributor community has thrived on. However, the openness of our communication channels has been abused in the past. These scenarios are typically marked by overly opinionated, non-technical and insulting posts on bugs in and in other forums. The communication may have technical elements or technical points, but the points are communicated in an overly opinionated way with a disregard for the opinions of others involved in the dialog. If encountering such communication, make sure to read the Wikipedia Entry on Flaming, especially the "Causes of flaming" section.

Note that invoking the process listed below should be the exception, and not the rule. Projects with like-minded committers can experience the Groupthink bug, which is why high quality open communications channels are so important to helping the project evolve. However, abuse undoes the openness that we strive for by making the channels intimidating or unfriendly to newcommers. Follow these steps if you encounter such communication:

  • Make one or two attempts to steer the conversation back on a technical path.
  • If that doesn't address the problem, enter the following text as the third comment:
 Ignoring comment per: http://wiki.eclipse.org/index.php/Mylyn_Contributor_Reference#Communication
  • Avoid following up again. Send the bug ID to the project lead who will assess the problem.

To comment on these guidelines please use bug 216157

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

  • Use the Eclipse bug severity with this exception: bugs marked as Trivial are enhancements, that can be easily implemented.

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.
  • contributed: bugs that were resolved through a contribution from a non-committer.
  • plan: bugs that are part of the project plan (see below).

Tags The project uses the following tags in the summary of bugs on bugs.eclipse.org (bug 215853):

[activity]      - bugs related to improving work flow
[api]           - bugs that require API changes; every API change has a corresponding bug which is tagged that way
[bridge]        - requests for structure bridges
[connector]     - requests for connectors
[context]       - bugs related to the context framework
[discussion]    - discussion items
[editor]        - bugs related to the Task Editor
[e3.2][e3.3]    - bugs specific to a particular version of Eclipse
[folding]       - bugs related to active folding
[framework]     - bugs that address internal implementation details that do not require API changes
[linux]         - bugs specific to Linux (Gtk)
[m2.3.1]        - bugs that are fixed in a particular maintenance version of Mylyn
[mac]           - bugs specific to Mac OS (Cocoa, Carbon)
[multi monitor] - bugs related to multi monitor environments
[new uex]       - new user experience
[patch]         - bugs that have a patch attached that is pending for review or waiting to be applied; 
                  the tag is removed after the patch has been applied or if a review requested changes
[performance]   - bugs that indicate severe performance problems
[planning]      - requests for planning features
[refactor]      - request for non-functional refactorings
[regression]    - bugs that indicate regressions
[sandbox]       - bugs that affect components in the sandbox
[standalone]    - bug related to usage of Mylyn outside of the Eclipse environment
[update]        - update manager and P2 related bugs
[usage]         - usage monitoring related bugs
[web connector] - bugs in the Web Templates connector
[website]       - bugs related to the web page on eclipse.org/mylyn (use Doc component for that?)
[win]           - bugs specific to Windows (Win32, WPF) 
[workflow]      - requests for integration of task and repository workflow
[working sets]  - bugs related to working set support
[search]        - bugs related to desktop search (see bug 349351)

Triage

The goal of bug triage to minimize the overhead for committers and to maintain a manageable backlog. Each (new) bug that is filed is processed as follows:

  • Major bugs or regressions are marked P1. If necessary the bug is escalated and scheduled for the current milestone.
  • Other bugs are marked P2.
  • Enhancements requests that should be considered for a future release are generally marked P3.
  • Other enhancement requests are marked P4 and tagged as helpwanted if they can be resolved through a community contribution.
  • If a request is out of scope of the project it is marked P5 or preferably closed. P5 bugs should not be marked helpwanted.

The backlog consists of all tasks scheduled for -- with a priority of P2 or higher. User stories are tagged with the plan keyword.

Bugs are assigned as following:

  • mylyn-inbox@eclipse.org: New bugs are and bugs that need user input.
  • mylyn-triaged@eclipse.org: Bugs that have been responded to and severity and priority has been set.
  • other: The owner is committed to completing the task for the scheduled milestone or within a reasonable time frame in the future if the bug is scheduled for --.

Planning

The goal of planning is to schedule a list of bugs for the milestone that concludes the next release cycle. When the milestone is reached all bugs with a priority of P3 or higher are expected to be completed. It is important that planning takes existing resources into account to avoid over-committing. Predictable release deliverables will enable integrators to plan their own progress based on the Mylyn framework and aid the growth of the ecosystem.

Before every release planning is done by triaging the entire backlog. Bugs marked with the plan keyword become part of the official release plan. Planning bugs marked P1 are committed items, other bugs are proposed items. Half way through a release cycle the plan is reviewed and P1/P2 bugs in the backlog are reconsidered for the milestone to accommodate for regressions and major bugs that were submitted after initial planning.

Resolving

The list of bugs that are scheduled for a milestone serves as a log that documents changes to release artifacts. In order to preserve historical information captured by the change log bugs that have been resolved should not be moved to other milestones once a milestone has been released.

If a defect reoccurs or a bug requires further work a new bug should be created and linked to the resolved bug. It is recommended to add a comment on the resolved bug that points to new bug and describes the reason for its creation.

Git

Git repositories can be accessed in Eclipse via EGit. Mylyn uses the following conventions for Git repositories:

  • It is strongly recommended to rebase before pushing to keep the revision history flat as possible:
git pull --rebase

The branch.autosetuprebase setting automates that:

git config branch.autosetuprebase always

See also:

Hudson

Mylyn is built regularly by jobs running on the Eclipse.org Hudson server.

Heartbeat Test Jobs

Each sub-project has its own build job triggered by Git activity that runs all tests for the sub-project.

Integration Test Jobs

Integration tests run against the Git integration build repository that includes all sub-projects as submodules. Integration tests are triggered by the mylyn-release job.

mylyn-integration-e3.5       - Eclipse 3.5: All tests excluding repository tests
mylyn-integration-e3.6       - Eclipse 3.6: All tests excluding repository tests
mylyn-integration-e3.7       - Eclipse 3.7: All tests including repository tests against all supported versions
mylyn-integration-e4.1       - Eclipse 4.1: All tests including repository tests against all supported versions
mylyn-integration-standalone - Java 1.6   : Tests designed to work outside of an OSGi environment

The full suite of repository tests is only run on the most recent Eclipse platforms. Running the full suite is expensive and a Bugzilla or Trac specific test that fails on Eclipse 3.5 is very likely to also fail on Eclipse 3.7.

Release Jobs

Release and snapshot artifacts created by release jobs are published to download.eclipse.org.

mylyn-3.5.x-release  - e_3_7_m_3_5_x branch
mylyn-3.6.x-release  - e_3_7_m_3_6_x branch
mylyn-release        - master branch

Maven

The Mylyn build is based on Maven/Tycho. The minimum required Maven version is 3.0.

  • The org.eclipse.mylyn/org.eclipse.mylyn-parent module specifies a parent pom with common settings. This pom is published to the Mylyn Maven repository.
  • The org.eclipse.mylyn/org.eclipse.mylyn-target module specifies a target definitions. These are published to the Mylyn Maven repository.

Builds

mvn package

To skip execution of tests use -Dmaven.test.skip=true

Tests

To run tests invoke the following command:

mvn integration-test

Releases

  • Check out the org.eclipse.mylyn.all project.
  • Run git submodule init to initialize sub modules
  • Run git submodule update to update sub modules to the latest integration build
  • Run mvn package to build release artifacts.

The Release Howto describes how to build and publish official Mylyn releases.

Profiles

The build defines profiles to build Mylyn against different targets. Profiles can be activated by passing -P<profile> to mvn.

  • implicit-target - build against nightly repositories, this is the default
  • explicit-target - build against a target definitions in org.eclipse.mylyn/org.eclipse.mylyn-target, needs to be activated through property -Dexplicit-target
  • ganymede, galileo, indigo, juno, e4.1, e4.2 - build against a specific Eclipse release (requires -Dexplicit-target)

Properties

Properties control certain aspects of the build such as execution of tests or optional analysis of source code. Properties can be set by passing -D<property>=<value> to mvn. All properties are initialized to sensible default values and are optional.

  • tycho-version - version of Tycho to use for building
  • analysis.skip - set to false to run code analysis (default: true)
  • test.skip - set to false to run tests (default: ${maven.test.skip})
  • sign.skip - set to false to run code signing (default: true)
  • pack.skip - set to false to run pack repositories (default: false)
  • promote.skip - set to false to copy artifacts to download location (default: true)

Code

Mylyn uses the Eclipse code conventions with these minor additions (bug 214179):

Tags: Mylyn uses the following tags in the code:

  • TODO: The following code needs to be reviewed.
  • TODO API: Indicates that a method or class needs to be reviewed.
  • TODO API x.y: This API is going to change for version x.y. Should include a description how it is going to change.
  • TODO e3.4: Make a change in the future specific to an Eclipse version.
  • XXX: The implementation uses a temporary work around that should be replaced by a proper solution in the future.
  • XXX SDK: The code uses internals of the Eclipse platform.
  • FIXME: Should only be used in very rare cases as a reminder that the marked code does not work as expected. Code marked as FIXME should not be distributed in a release.
  • FIXME REVIEW: Review the code before the next version is released

Creating new plug-ins and features

File a bug that describes the purpose of the new plug-ins and the proposed names. Then add an item to the monthly meeting agenda to discuss the request with other committers. Once consensus has been reached follow the steps below.

To retain consistency of layout and settings, new projects should always be created by copying an existing project rather than creating plug-in or feature projects from scratch.

Steps for creating a new plug-in or feature:

  1. Copy an existing project on disk, e.g. to create an org.eclipse.myconnector.core bundle do the equivalent of running cp -a org.eclipse.mylyn.bugzilla.core org.eclipse.mylyn.myconnector.core
  2. Edit pom.xml, .project and META-INF/MANIFEST to reflect the new bundle id
  3. List the new bundle as a module in the parent pom to include it in the build
  4. Use Import Projects from the popup menu in the Git Repositories view to add the project to the workspace

For plug-ins these additional steps should be considered:

  1. Add bundle to feature
  2. Add source bundle to SDK feature

For features these additional steps should be considered:

  1. Add feature to site

Contributions

Contributions are a key part of evolving Mylyn. All committers should encourage and prioritize contributions.

IP log

The IP log should always be kept up to date.

Aggregated IP log

Sub-project IP logs:

Mylyn Builds Mylyn Commons Mylyn Context Mylyn Docs Mylyn Reviews Mylyn Tasks Mylyn Versions

Applying Patches

(Note: the section below is largely supplanted by the new Gerrit based review system, which takes care of many of these details including contributor IP approval.)

  • Note that each patch should not contain more than 1000 added lines. 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.

When applying a patch follow these steps:

Git

  • Enter the name of the contributor as the author of the commit
  • Encourage the contributor to update the patch into state where it can be applied unaltered.
  • If you need to make addtional changes that are non-trivial (e.g., copyright header fixes) commit the unaltered patch first and then make another commit with your changes.
    • If absolutely necessary, a task-branch can be used to group commits and improve traceability otherwise commit messages should be sufficient to associate bugs with commits.
  • All files altered by a contributor must have a note in the copyright header and should have an @author tag if a change was significant.
  • If several authors have worked on a commit consider adding Co-authored-by headers to the commit message for each author.
  • Also see Development_Resources/Handling_Git_Contributions .

Bugzilla

  • Flag the the patch attachment as iplog+.
  • Add the contributed keyword to the corresponding bug.

Web Site

Note, you need to be a member of the mylyn group to push changes to the website.

Workspace

The recommended way to work with Mylyn sources is by checking them out of Git. 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.

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/
  • To install additional JRE profiles or if you are unable to obtain a J2SE 1.5 installation install Add PDE/API Tools Environment Descriptions from the Eclipse project repository that corresponds to your Eclipse environment, e.g. http://download.eclipse.org/eclipse/updates/3.7

Checkout

The source code is hosted in Gerrit which is a code review system for Git. Each sub-project has a separate repository that is accessible through the git, ssh and https protocol. For anonymous access use git or https. Committers need to use ssh or https.

Web access to the Git repositories

Release Tags: Each release is tagged with R_. For example, Mylyn 2.2.0 for Eclipse 3.4 is tagged as R_2_2_0 and the branched Eclipse 3.3 plug-ins are tagged R_2_2_0_e_3_2.

Active branches

Also see policy for supported Eclipse versions. Branched projects, if any, are updated with each release.

Maintenance Branches

Changes should be committed to master and cherry-picked onto maintenance branches to be included in service releases.

  • e_3_8_m_3_8_x     Mylyn 3.8.x stream (corresponds to Mylyn Docs 1.7.x)

End-of-life branches

  • e_3_8_m_3_7_x     Mylyn 3.7.x stream for Eclipse 3.8
  • e_3_7_m_3_6_x     Mylyn 3.6.x stream for Eclipse 3.7
  • e_3_7_m_3_5_x     Mylyn 3.5.x stream for Eclipse 3.7
  • e_3_6_m_3_4_x     Mylyn 3.4.x stream for Eclipse 3.6
  • e_3_6_m_3_3_x     Mylyn 3.3.x stream for Eclipse 3.6
  • e_3_5_m_3_3_x     Mylyn 3.3.x stream for Eclipse 3.5
  • e_3_4_m_3_3_x     Mylyn 3.3.x stream for Eclipse 3.4
  • e_3_5_m_3_2_x     Mylyn 3.2.x stream for Eclipse 3.5
  • e_3_4_m_3_2_x     Mylyn 3.2.x stream for Eclipse 3.4
  • e_3_3_m_3_2_x     Mylyn 3.2.x stream for Eclipse 3.3
  • e_3_4_m_3_1_x     Mylyn 3.1.x stream for Eclipse 3.4
  • e_3_3_m_3_1_x     Mylyn 3.1.x stream for Eclipse 3.3
  • e_3_4_m_3_0_x     Mylyn 3.0.x stream for Eclipse 3.4
  • e_3_3_m_3_0_x     Mylyn 3.0.x stream for Eclipse 3.3
  • e_3_4_m_2_x     Mylyn 2.x stream for Eclipse 3.4
  • e_3_3_m_2_x     Mylyn 2.x stream for Eclipse 3.3
  • 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.3M4
  • e_3_2_m_1_0     Mylyn 1.0 stream for Eclipse 3.2
  • e_3_1     Mylyn 0.6 for Eclipse 3.1

Other:

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

Target Environment

Mylyn depends on a number of libraries from other Eclipse projects. The org.eclipse.mylyn-target project provides target environment definitions that specify all required dependencies. After following the steps under Checkout go to Window > Preferences and open the Target Platform page. Select one of the mylyn target definitions. Generally, mylyn-dev-base is the recommended choice.

  • mylyn-dev-base - Targets the lowest support Eclipse version. Includes sources and additional integration features for development.
  • mylyn-dev-latest - Targets the highest support Eclipse version. Includes sources and additional integration features for development.
  • mylyn-e* - Target defintions used by the build. May only contain the minimal requirements excluding sources.

API Baseline

An API baseline for the latest releases is available from the download archive. Follow these instructions to configure the API baseline in your workspace:

  1. Extract the Mylyn API baseline zip archive
  2. Add the baseline under Windows > Preferences > Plug-in Development > API Baselines pointing to the extracted directory

Markers

The general policy is that plug-ins should not have any errors or warning markers since these indicate potential problems or API insufficiencies. In practice, we do not have the capacity to address all warnings or the cost outweighs the benefit or warnings result out of intentional design decisions, e.g. usage of deprecated APIs for maintaining backwards compatibility.

To reduce the number of warnings we have established the following policies for usage of internal packages:

  1. Plug-ins are allowed to use internals within the boundaries of their component (e.g. o.e.m.bugzilla.ui may access internals of o.e.m.bugzilla.core). We have generally allowed that through x-friends relationships in plug-in manifests.
  2. It's generally okay to use provisional APIs. We have made these accessible through classpath filters: Project Properties > Java Build Path > Libraries > Plug-in Dependencies > Access rules. It's common that plug-ins have a rule to make org/eclipse/mylyn/internal/provisional/** accessible.
  3. In cases where platform internals need to be accessed due to a lack of API it's okay to make the specific classes or packages accessible. These cases should be documented on bug 233055.
  4. Test plug-ins are allowed to use all internals.

Additionally, it is recommend to create custom filters in the workspace to hide remaining warnings that will not get addressed in the short time. Filter can be configured through the view menu of the Markers view.

JUnit Tests

The bundle.tests bundles (e.g. org.eclipse.mylyn.tasks.core.tests) are unit tests; the bundles are fragments to enable unit testing with package private access. The component.tests bundles (e.g. org.eclipse.mylyn.tasks.tests) are integration tests that run against the API.

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

Tests that connect to repositories require a $HOME/.mylyn/credentials.properties file that specifies authentication information. The file needs to have the following content:

user: <user>
pass: <pass>
  • For <user> use tests@mylyn.eclipse.org. For <pass> use mylyntest. 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.mylyn.tests:

  • AllTests: all automatic tests, should always pass, run as a JUnit Plug-in Test
  • AllHeadlessStandaloneTests: do not require workbench, can run as JUnit Test, subset of AllTests
  • AllConnectorTests: all automatic tests for repository connectors, requires network access

Test suites in org.eclipse.mylyn.tests.ui:

  • AllUiTests: all automatic SWTbot-based UI tests

Test suites in org.eclipse.mylyn.tests.performance:

  • AllPerformanceTests: all performance tests

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, work and runtime workspace. The result is an folder with the following three workspaces:

  • Mylyn-Bootstrap
  • Mylyn-Work
  • Mylyn-Runtime

Please follow the steps:

  • Download and install Eclipse 3.7 or later
  • Start Eclipse and create an workspace called Mylyn-Bootstrap
  • Install dependencies using File > Import > Install Software Items from File: mylyn-bootstrap.p2f
  • Import projects using File > Import > Team Project Set: mylyn-dependencies.psf
  • Switch to the Git Repository Exploring Perspective and clone the Git repositories listed under Mylyn/Contributor_Reference#Checkout
  • Use Import Projects from the Git Repository Exploring Perspective to add the projects to your workspace
  • Create a new Launch Configuration:
    • Select Run -> Run... -> create a new Eclipse Application.
    • Call the application Mylyn Work.
    • On the Main tab, set the Location
      • You can use an existing workspace
      • You can create a new workspace (e.g. Mylyn-Work)

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 installed plugins. This workspace needs to be setup following the steps under #Setup:

Do your development in the Mylyn-Work workspace. Whenever your changes make it into master that you would like to use, close your Mylyn-Work workspace, pull from Git in the Mylyn-Bootstrap workspace, and then re-launch your Mylyn-Work 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.

Self-hosting for Luna (and newer)

Starting for Eclipse 4.4 (Luna) there is a new way how you can setup the bootstrap workspace, work and runtime workspace. Here a list of the needed actions.
1) download latest Eclipse version from Eclipse Downloads (actual this is Eclipse 4.4M3)
2) download the latest Mylyn Baseline from Mylyn Downloads (at the time of writing this is Mylyn 3.10)
3) start Eclipse and create workspace Mylyn-Bootstrap
4) install the "Eclipse Git Team Provider" and "Mylyn Review Connector: Gerrit".
You can do the install with one of the following Mylyn-Bootstrap_4.4.p2f or Mylyn-Bootstrap_4.4_Gerrit.p2f definition files if you have the folder org.eclipse.mylyn.commons/org.eclipse.mylyn.development already on your disk.
5) change Git Preference "Default repository folder" to ${workspace_loc}
6) Optional: Add https://git.eclipse.org/r as an Gerrit Code Review Task Repository. You should do this because some other steps are easier.
7) Switch to the Git Repository Exploring Perspective and Clone the org.eclipse.jdt.core Git Repository but only import the org.eclipse.jdt.annotation_v1 project.
    we need this as long as we not use java 8.
8) Switch to the Git Repository Exploring Perspective and Clone the org.eclipse.mylyn.commons.git Git Repository.
If you not use Gerrit use ssh://XXX@git.eclipse.org/gitroot/mylyn/org.eclipse.mylyn.commons.git and change xxx to your userid
import the projects into your workspace
9) set "Plug-in Development" Preference "API Baselines to the downloaded Baseline folder
10) set the Target Platform to mylyn-bootstrap-e4.4
11) Now continue with adding the other Git repositories the same way you did in 6) and import the projects into workspace

  • git.eclipse.org/gitroot/mylyn/org.eclipse.mylyn.git
  • git.eclipse.org/gitroot/mylyn/org.eclipse.mylyn.context.git
  • git.eclipse.org/gitroot/mylyn/org.eclipse.mylyn.tasks.git
  • git.eclipse.org/gitroot/mylyn/org.eclipse.mylyn.builds.git
  • git.eclipse.org/gitroot/mylyn/org.eclipse.mylyn.docs.git
  • git.eclipse.org/gitroot/mylyn/org.eclipse.mylyn.reviews.git
  • git.eclipse.org/gitroot/mylyn/org.eclipse.mylyn.versions.git


12) delete the following projects from workspace (sorry did not know how to fix the errors)

  • org.eclipse.mylyn.builds.sample.ant
  • org.eclipse.mylyn.builds.sample.mvn
  • org.eclipse.mylyn.builds.sample.mvn.reactor
  • org.eclipse.mylyn.builds.sample.mvn.reactor.module1
  • org.eclipse.mylyn.builds.sample.mvn.reactor.module2
  • org.eclipse.mylyn.docs.epub.ant.core
  • org.eclipse.mylyn.docs.epub.tests
  • org.eclipse.mylyn.wikitext.core.maven
  • org.eclipse.mylyn.wikitext.help.ui
  • org.eclipse.mylyn.wikitext.help.sdk
  • org.eclipse.mylyn.subclipse.core
  • org.eclipse.mylyn.subclipse.ui


13) Only if you did not do step 6): If you needed to fetch reviews from gerrit change the .git/config file and add the remote "gerrit" keys (url,fetch,push)
14) Now finish the setup

  • "Import Preferences" (from Java Package Explorer) {workspace}/org.eclipse.mylyn.commons/org.eclipse.mylyn.development/developer/markers.epf
  • Import the Java Code Formater from {workspace}/org.eclipse.mylyn.commons/org.eclipse.mylyn.development/developer/mylyn-settings-formatter.xml
  • Import the Java Code Templates from {workspace}/org.eclipse.mylyn.commons/org.eclipse.mylyn.development/developer/codetemplates.xml>br>you now can change the Name in the Header of the "New Java Files" if you are not at Tasktop (currently the workspace setting is only use in the connector-bugzilla-rest all other project use project specific settings)


15) launch Mylyn-Work or Mylyn-Work-Mac
16) If you want to copy definitions for the Task Repositories and Task List entries Quit the new launch application and copy the following files from the previous workspace to the new created workspace. Directory is .metadata/.mylyn/

  • repositories.xml.zip
  • tasks.xml.zip

relaunch Mylyn-Work or Mylyn-Work-Mac
17) fix the userId and passwords from your Task Repositories
18) now repeat steps 5 - 14 but skip step 7) and use "Running Platform" as target in step 10

Incubator

The Mylyn Incubator is a set of projects and feature contributors use for experimentation. These features are not intended to be used for daily development. Incubator features include experimental connectors and bridges, experimental UI features, and developer tools. To use Incubator tools either check them out of the version control, or install them using the Incubator update site.

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.
  • Repository Spy: displays the repositories with all their atrtributes in a separate view. Allows the deletion of selected properties.
  • Properties View sources: Shows properties of items selected in the Tasklist View or Task Repositories view in the standard Eclipse Properties View.

Experimental tools

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

  • 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 StatusHandler and pass an IStatus object. Note that some of the other Mylyn code uses the convenience methods on StatusHandler, but we are phasing those out because they do not pass the plug-in ID that the exception originated from.
  • 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.
  • To improve the speed of decorators use setUseHashlookup(true) on all structured viewers.

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

  • Task List problems: do not ask users to send or attach their Task List, since it can contain highly sensitive information. If needed ask the user to create a new workspace and try to reproduce the problem there, ensuring that they have not included any user private or company private information, and have them send that.
  • 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 (when Eclipse hangs):
    • On Windows use the tool found at the adaptj home page:
      • Follow the link and select button "Launch" and run the applet
      • Select menu Process > Thread Dump
      • In the combo box "Process ID" select the Java VM and click OK
    • Or, 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
    • Or, on Linux: Use Ctrl-\ on the console or send SIG_QUIT signal: kill -SIGQUIT pid
    • Or, with jconsole (requires 1.5 jdk, works on any OS):
      • Launch eclipse -vmargs -Dcom.sun.management.jmxremote
      • Launch the JDK's jconsole tool. You can attach to the Java Process and copy&paste the thread dump.
    • 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

Back to the top