Jump to: navigation, search

Difference between revisions of "How to contribute"

Line 1: Line 1:
Becoming a new committer.
+
This page is a starting point for where to begin when wanting to contribute to a project.
  
Things that will be on this page
 
  
* map of functionality to projects
+
 
* Information about the  
+
= The Short Story =
* links to project-specific "getting started" developer docs
+
Taken from [http://www.wikihow.com/Contribute-to-Open-Source  How to Contribute to Open Source]:
** [[TM_and_RSE_FAQ#Working on TM / RSE]]
+
 
* links to bugzilla queries for easy fix bugs
+
# Pick a project from the [http://www.eclipse.org/projects/ Eclipse Projects List] which sounds interesting to you.
** [[BugDay/FAQ]]
+
# Look for a place to contribute. This means not only programming, but also documentation, theme design, art work, architectural design, and even blogging about it or presenting the project on your local [http://wiki.eclipse.org/Eclipse_DemoCamp Eclipse DemoCamp].
* The general contribution process
+
# Join the project's [http://eclipse.org/forums/ forum] and [http://www.eclipse.org/mail/ mailing lists].
** [[TM and RSE FAQ#How do I submit a fix for a bug?]]
+
# Respect and maintain discussions.
** [[TM and RSE FAQ#How do I submit a contribution beyond a simple bug fix?]]
+
# Encourage contributions. Even if you are not a committer, telling others that you like the idea helps a lot to identify a community.
* getting started with tests
+
# Start small by reporting and fixing bugs.
 +
# Submitting small patches containing bug fixes.
 +
# Take lead on larger features.
 +
# Respond and send feedback, for instance, about new features or ideas presented on the lists.
 +
# If you really want to help but don't have the experience or the know-how, become a [http://www.eclipse.org/donate/ Friend of Eclipse]!
 +
 
 +
 
 +
= The Longer Story =
 +
 
 +
== Bug Reporting ==
 +
If you find a bug, log it.  See the FAQ entry [[../FAQ#How_do_I_report_a_bug.3F|"How to Report a Bug"]], and a description of how a [http://borisoneclipse.blogspot.com/2005/10/great-bug-report.html great bug report] looks like. You may also study  [http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.134.72&rep=rep1&type=pdf Quality of Bug Reports in Eclipse] to learn that "good bug reports" tend to be fixed faster :)
 +
Also, if you find a bug that you think is a duplicate, is not a bug, etc. feel free to comment saying so. 
 +
 
 +
If wanting to track (any) bug changes there are a few ways:
 +
* Via email.  If you want to receive email when a bug is logged you can watch special "*-Inbox" users like "Platform-UI-Inbox@eclipse.org" user. You will receive email anytime a new bug is logged to this user or an update is made while assigned to this user.  To set this up see Preferences -> Email Preferences -> User Watching.  This will email you , for example, for all incoming Platform UI bugs; Such users exist for various projects. Ask on the developer mailing lists for details if interested.
 +
* Via news-feeds.  You can convert any query in Bugzilla to a feed that will update when a matched bug changes. To convert a search to a feed perform a search and select "Feed" at the bottom of the search results.
 +
 
 +
== Contributing Code==
 +
Whether you're wanting to fix a typo in javadoc or to implement the next whiz bang feature you'll need to know a few things before you contribute code. The basic life-cycle, however, is almost always identical to all projects:
 +
 
 +
# Check out the sources.
 +
# Make your changes.
 +
# Create or update the tests to cover your changes.
 +
# Create a patch.
 +
# Submit the patch to Bugzilla.
 +
 
 +
There might be some small differences between projects, but's thats the way it works in general. If you feel uncertain, feel free to send a mail to the project's forum or mailing list at any time. Some more details on each of these steps:
 +
 
 +
=== Checking out the Sources ===
 +
Each project has one or more repositories containing the sources of the project. You need to check out the project homepages to learn about the exact location.
 +
 
 +
=== Building from Sources ===
 +
Most projects have some kind of a build tool running to build the plug-ins from scratch like PDE Build, Buckminster, or Maven Tycho. Look out for various build system witnesses (like pom.xml files) or search the project's wiki pages to learn how to build the bundles from scratch and to execute the test cases. If you don't find any information yet - send a mail to the developer mailing lists of the project. If you find that existin documentation on building from sources is outdated feel invited to update corresponding build instructions. Most of the time this information is found on some wiki pages which welcome your contributions.
 +
 
 +
=== Creating a Patch===
 +
Creating and contributing a patch is no sorcery. Depending on the project's version control system creating a patch is just a one-line no-brainer like ''git format-patch origin''. Then all needed to do is to create a bug report in the [https://bugs.eclipse.org/bugs/ Eclipse Bugzilla] on the right product and component and attach this patch with a brief description what's in. No worries, if you don't find the right component at first... maybe it's a good solution to send a mail to the forum or mailing list before announcing your patch and ask where to put it.
 +
 
 +
Note, there is no need to send the patch directly to the mailing list unless being asked for. Contributions of this kind always have to be submitted using Bugzilla to guarantee IP Cleanliness. You may check out the [http://www.eclipse.org/legal/committerguidelines.php committer guidelines] which may also explain how and why it works like it works.
 +
 
 +
=== Unit Testing===
 +
Testing is imperative to the health of the project.  Each project has a significant amount of tests (hopefully).  If you are contributing a fix or writing an enhancement, it is a requirement that tests are written.  If you don't write them a committer will have to and that could slow down the contribution process
 +
 
 +
And: If you want to make a good impression, write tests.  This goes for any project, of course. :)
 +
 
 +
=== Coding Conventions ===
 +
As with all projects, there are common coding conventions you should take care of those of the Eclipse Platform's [http://dev.eclipse.org/conventions.html Standards, Conventions and Guidelines] but each project may impose their own. Just look on the project's committer resources and - if none found or too vague - ask for clarification and hints at the developer's mailing list.
 +
 
 +
=== Before You Create the Patch ===
 +
 
 +
* Commit comments are required for all code commits. Bugs should be logged to track work and the bug number and a description is then used in the commit comment to describe the change. For example when fixing a bug, use exactly: "Fixed bug xxx: <title of bug>".  The "bug xxxx" part is really important as this is what is used to relate the bugs to the build submissions, so it must be formatted exactly that way (uppercase or lowercase bug should work). 
 +
* Before sending a patch, catch up to all changes made by others, and then run the tests.
 +
* Don't create patches if this will cause compile errors for others.
 +
* Ensure that every new file added by you has an appropriate license header!
 +
 
 +
== Forums  ==
 +
Forums are driven by participation. If you have a question send it to the forum. If you know the answer to someone else's question (or your own), send it to the forum. Just feel free to respond. When asking a question, spent some  time on asking  [http://www.catb.org/~esr/faqs/smart-questions.html questions the smart way]. If you spent a considerable amount of time in asking it just becomes more likely that others understand your need and answer your questions appropriately. As with bug reports, the more specific your request is the more likely there will be an answer (but unfortunately there is no guarantee).
 +
 
 +
== Wiki==
 +
The Eclipse wiki is open and can be edited by all.  If you find a typo, a broken link, or anything that you view as a small issue feel free to fix it.
 +
Some projects also use the Wiki to create and maintain user manuals which are integrated into the Eclipse Help System during build. If you want to contribute a significant amount of information or create a new article jump in and contribute. However, most projects would like to be get informed before you start doing some work, and thus,  may request you to discuss your proposal on the mailing list/ forum or to [[../FAQ#How_do_I_report_a_bug.3F|log a bug]] so that they are aware of what you're contributing.  This way project committers can ensure consistency structurally and in the message conveyed.
 +
 
 +
== Spread the Word ==
 +
Some projects at Eclipse are well known to outside world, others aren't. It's always great to see people speaking about these projects and providing feedback. Thus, feel free to blog about the projects you like! You may even consider presenting the project on your local Eclipse DemoCamp events or Java User Groups etc.
 +
 
  
 
[[Category:How_to_Contribute]]
 
[[Category:How_to_Contribute]]

Revision as of 00:24, 20 May 2011

This page is a starting point for where to begin when wanting to contribute to a project.


The Short Story

Taken from How to Contribute to Open Source:

  1. Pick a project from the Eclipse Projects List which sounds interesting to you.
  2. Look for a place to contribute. This means not only programming, but also documentation, theme design, art work, architectural design, and even blogging about it or presenting the project on your local Eclipse DemoCamp.
  3. Join the project's forum and mailing lists.
  4. Respect and maintain discussions.
  5. Encourage contributions. Even if you are not a committer, telling others that you like the idea helps a lot to identify a community.
  6. Start small by reporting and fixing bugs.
  7. Submitting small patches containing bug fixes.
  8. Take lead on larger features.
  9. Respond and send feedback, for instance, about new features or ideas presented on the lists.
  10. If you really want to help but don't have the experience or the know-how, become a Friend of Eclipse!


The Longer Story

Bug Reporting

If you find a bug, log it. See the FAQ entry [[../FAQ#How_do_I_report_a_bug.3F|"How to Report a Bug"]], and a description of how a great bug report looks like. You may also study Quality of Bug Reports in Eclipse to learn that "good bug reports" tend to be fixed faster :) Also, if you find a bug that you think is a duplicate, is not a bug, etc. feel free to comment saying so.

If wanting to track (any) bug changes there are a few ways:

  • Via email. If you want to receive email when a bug is logged you can watch special "*-Inbox" users like "Platform-UI-Inbox@eclipse.org" user. You will receive email anytime a new bug is logged to this user or an update is made while assigned to this user. To set this up see Preferences -> Email Preferences -> User Watching. This will email you , for example, for all incoming Platform UI bugs; Such users exist for various projects. Ask on the developer mailing lists for details if interested.
  • Via news-feeds. You can convert any query in Bugzilla to a feed that will update when a matched bug changes. To convert a search to a feed perform a search and select "Feed" at the bottom of the search results.

Contributing Code

Whether you're wanting to fix a typo in javadoc or to implement the next whiz bang feature you'll need to know a few things before you contribute code. The basic life-cycle, however, is almost always identical to all projects:

  1. Check out the sources.
  2. Make your changes.
  3. Create or update the tests to cover your changes.
  4. Create a patch.
  5. Submit the patch to Bugzilla.

There might be some small differences between projects, but's thats the way it works in general. If you feel uncertain, feel free to send a mail to the project's forum or mailing list at any time. Some more details on each of these steps:

Checking out the Sources

Each project has one or more repositories containing the sources of the project. You need to check out the project homepages to learn about the exact location.

Building from Sources

Most projects have some kind of a build tool running to build the plug-ins from scratch like PDE Build, Buckminster, or Maven Tycho. Look out for various build system witnesses (like pom.xml files) or search the project's wiki pages to learn how to build the bundles from scratch and to execute the test cases. If you don't find any information yet - send a mail to the developer mailing lists of the project. If you find that existin documentation on building from sources is outdated feel invited to update corresponding build instructions. Most of the time this information is found on some wiki pages which welcome your contributions.

Creating a Patch

Creating and contributing a patch is no sorcery. Depending on the project's version control system creating a patch is just a one-line no-brainer like git format-patch origin. Then all needed to do is to create a bug report in the Eclipse Bugzilla on the right product and component and attach this patch with a brief description what's in. No worries, if you don't find the right component at first... maybe it's a good solution to send a mail to the forum or mailing list before announcing your patch and ask where to put it.

Note, there is no need to send the patch directly to the mailing list unless being asked for. Contributions of this kind always have to be submitted using Bugzilla to guarantee IP Cleanliness. You may check out the committer guidelines which may also explain how and why it works like it works.

Unit Testing

Testing is imperative to the health of the project. Each project has a significant amount of tests (hopefully). If you are contributing a fix or writing an enhancement, it is a requirement that tests are written. If you don't write them a committer will have to and that could slow down the contribution process.

And: If you want to make a good impression, write tests. This goes for any project, of course. :)

Coding Conventions

As with all projects, there are common coding conventions you should take care of those of the Eclipse Platform's Standards, Conventions and Guidelines but each project may impose their own. Just look on the project's committer resources and - if none found or too vague - ask for clarification and hints at the developer's mailing list.

Before You Create the Patch

  • Commit comments are required for all code commits. Bugs should be logged to track work and the bug number and a description is then used in the commit comment to describe the change. For example when fixing a bug, use exactly: "Fixed bug xxx: <title of bug>". The "bug xxxx" part is really important as this is what is used to relate the bugs to the build submissions, so it must be formatted exactly that way (uppercase or lowercase bug should work).
  • Before sending a patch, catch up to all changes made by others, and then run the tests.
  • Don't create patches if this will cause compile errors for others.
  • Ensure that every new file added by you has an appropriate license header!

Forums

Forums are driven by participation. If you have a question send it to the forum. If you know the answer to someone else's question (or your own), send it to the forum. Just feel free to respond. When asking a question, spent some time on asking questions the smart way. If you spent a considerable amount of time in asking it just becomes more likely that others understand your need and answer your questions appropriately. As with bug reports, the more specific your request is the more likely there will be an answer (but unfortunately there is no guarantee).

Wiki

The Eclipse wiki is open and can be edited by all. If you find a typo, a broken link, or anything that you view as a small issue feel free to fix it. Some projects also use the Wiki to create and maintain user manuals which are integrated into the Eclipse Help System during build. If you want to contribute a significant amount of information or create a new article jump in and contribute. However, most projects would like to be get informed before you start doing some work, and thus, may request you to discuss your proposal on the mailing list/ forum or to [[../FAQ#How_do_I_report_a_bug.3F|log a bug]] so that they are aware of what you're contributing. This way project committers can ensure consistency structurally and in the message conveyed.

Spread the Word

Some projects at Eclipse are well known to outside world, others aren't. It's always great to see people speaking about these projects and providing feedback. Thus, feel free to blog about the projects you like! You may even consider presenting the project on your local Eclipse DemoCamp events or Java User Groups etc.