Difference between revisions of "Tycho/Contributor Guide"

From Eclipsepedia

Jump to: navigation, search
(emphasise separation of commits for refactorings)
(Contributing the Patch)
(12 intermediate revisions by 3 users not shown)
Line 1: Line 1:
== How to contribute patches to Tycho ==
+
== Starting a Contribution ==
  
First, read [[Developing Tycho]] .
+
Before starting to develop an enhancement or fix for Tycho, it is important that you get in touch with the project. We track ideas for enhancements and bug reports in the [https://bugs.eclipse.org/bugs/query.cgi?format=specific;product=Tycho Eclipse Bugzilla], so this is a good place to present your ideas for a patch and to make sure it's going in the right direction.
 +
 
 +
If you want to do an enhancement but don't know where to start, you can also just ask on [mailto:tycho-dev@eclipse.org tycho-dev@eclipse.org].
 +
 
 +
== Developing Patches for Tycho ==
 +
 
 +
The technical basics (how to get the sources, how to import and build, etc.) are described here: [[Developing Tycho]] .
  
If you want to do an enhancement but don't know where to start or if it's going in the right direction, just ask on [mailto:tycho-dev@eclipse.org tycho-dev@eclipse.org] and we will help.
 
 
If the patch is not trivial, make sure you include a test case that reproduces the bug or proves that the enhancement works.
 
If the patch is not trivial, make sure you include a test case that reproduces the bug or proves that the enhancement works.
  
Line 16: Line 21:
 
=== Commit Message Guidelines ===
 
=== Commit Message Guidelines ===
  
* The first sentence should be a clear and concise description about the change
+
* Start with the bug number the change is related to; don't add "bug" or puctuation marks
* Enter a newline before providing a more detailed description about the change
+
* Also in the first line, provide a clear and concise description of the change
* When you fix a bug then report which bug you fix. The commit message should start with the bug number.
+
* Add one blank line, followed by more details about the change. This could include a motivation for the change and/or reasons why things were done in the particular way they are done in the change.
* When there are deeper reasons for doing things the way the commit does, then explain these as well. This all is for the reviewers and yourself: the context of the commit is completely clear.
+
* Add "Bug: <bug number>" in the footer.
 +
 
 +
See here for an [http://git.eclipse.org/c/tycho/org.eclipse.tycho.git/commit/?id=52ca41640484f108cae9fcaadb1c105e686dd985 example commit message]
  
See an [http://git.eclipse.org/c/tycho/org.eclipse.tycho.git/commit/?id=713962c047eb048223d711c62bdb418931172890 example commit message]
 
 
 
=== Commit Granularity ===
 
=== Commit Granularity ===
  
* Make small commits, as small as reasonable. This makes them easy to review.
+
* Make small commits, yet self-contained commits. This makes them easy to review.
 
* Do not mix concerns in commits: have a commit do a single thing. This makes them reviewable 'in isolation'. This is particularly important if you need to do refactorings to the existing code: Refactorings tend to lead to large diffs which are difficult to review. Therefore make sure to have separate commits for refactorings and for functional changes.
 
* Do not mix concerns in commits: have a commit do a single thing. This makes them reviewable 'in isolation'. This is particularly important if you need to do refactorings to the existing code: Refactorings tend to lead to large diffs which are difficult to review. Therefore make sure to have separate commits for refactorings and for functional changes.
* Split your work into multiple smaller pieces of work (when possible) and implement each of these pieces in a series of commits.
 
  
 +
== Contributing the Patch ==
  
=== Patch Format ===
+
=== Using Gerrit ===
  
We prefer git patches created with [http://schacon.github.com/git/user-manual.html#submitting-patches git format-patch] since they include a commit message and preserve author information. This will also give you the credit you deserve in the git history.
+
The [https://git.eclipse.org/r/#/q/project:tycho/org.eclipse.tycho+status:open,n,z Eclipse Gerrit] is the preferred way to propose patches to Tycho. Everyone with an Eclipse Bugzilla login can propose patches.
  
== Contributing the Patch ==
+
In order to propose a change to Tycho
 +
* Configure the repository URL <tt>https:</tt><tt>//git.eclipse.org/r/tycho/org.eclipse.tycho.git</tt> for the remote "origin"
 +
* Know your [https://git.eclipse.org/r/#/settings/http-password Gerrit HTTPS user name and password]
 +
* Push to the special code review branch "refs/for/master", e.g. with <tt>git push origin HEAD:refs/for/master</tt>
  
Open a [https://bugs.eclipse.org/bugs/enter_bug.cgi?product=Tycho&rep_platform=All&op_sys=All bug] and attach the patch. This is the only channel we can accept patches (until we may be able to use gerrit for accepting patches at some point in the future).
+
For more information on the Eclipse Gerrit instance (e.g. how to push via SSH), see here: [[Gerrit]].
  
You will have to include answers to the following questions:
+
Note that prototypes and other incomplete work should be pushed to the refs/for/master/POC branch so committers know the nature of the changed being pushed.
  
# Did you author 100% of the content you are contributing ?
+
=== Using Bugzilla ===
# Do you have the rights to donate the content to Eclipse ?
+
# Are you contributing the content under the EPL ?
+
  
For larger patches (>250 LoC) we will also have to create a contribution questionnaire with the Eclipse IP team.
+
Attach the patch(es) to the bug/enhancement in Bugzilla. The patch should be in the format produced by <tt>git format-patch</tt>, so that it is suitable for <tt>git am</tt>.
 +
 
 +
=== Legal Paperwork ===
 +
 
 +
With the contribution, you will have to include answers to the following questions (e.g. as comment in Gerrit or Bugzilla):
 +
 
 +
# Did you author 100% of the content you are contributing?
 +
# Who owns the copyright of the contributed content? (This is typically your employer.)
 +
# Is the contributed code licensed under the EPL? (You should answer this question by putting a [http://www.eclipse.org/legal/copyrightandlicensenotice.php copyright and license header] into every new java file.)
 +
# Do you have the right to contribute the content to Eclipse? (You need to confirm this with the copyright owner.)
 +
 
 +
With these questions answered, we will be able to accept small patches (<250 LoC) immediately. For larger patches, we will also have to create a contribution questionnaire for review by the Eclipse IP team, but this usually doesn't require additional actions from you.
  
 
In general, also see [[Development Resources#Users: Contributing To A Project]].
 
In general, also see [[Development Resources#Users: Contributing To A Project]].
 +
  
 
[[Category:Tycho|Contributor Guide]]
 
[[Category:Tycho|Contributor Guide]]

Revision as of 21:44, 9 December 2012

Contents

Starting a Contribution

Before starting to develop an enhancement or fix for Tycho, it is important that you get in touch with the project. We track ideas for enhancements and bug reports in the Eclipse Bugzilla, so this is a good place to present your ideas for a patch and to make sure it's going in the right direction.

If you want to do an enhancement but don't know where to start, you can also just ask on tycho-dev@eclipse.org.

Developing Patches for Tycho

The technical basics (how to get the sources, how to import and build, etc.) are described here: Developing Tycho .

If the patch is not trivial, make sure you include a test case that reproduces the bug or proves that the enhancement works.

Writing Tests

Tycho has two types of tests: unit tests (locally in each module) and a global integration test suite in module tycho-its.

Unit tests are preferred if possible because they are in general much faster and better targeted at the functionality under test. Integration tests generally invoke a forked maven build on a sample project (stored under projects/) and then do some assertions on the build output.

See an example for a unit test and an integration test.

Commit Message Guidelines

  • Start with the bug number the change is related to; don't add "bug" or puctuation marks
  • Also in the first line, provide a clear and concise description of the change
  • Add one blank line, followed by more details about the change. This could include a motivation for the change and/or reasons why things were done in the particular way they are done in the change.
  • Add "Bug: <bug number>" in the footer.

See here for an example commit message

Commit Granularity

  • Make small commits, yet self-contained commits. This makes them easy to review.
  • Do not mix concerns in commits: have a commit do a single thing. This makes them reviewable 'in isolation'. This is particularly important if you need to do refactorings to the existing code: Refactorings tend to lead to large diffs which are difficult to review. Therefore make sure to have separate commits for refactorings and for functional changes.

Contributing the Patch

Using Gerrit

The Eclipse Gerrit is the preferred way to propose patches to Tycho. Everyone with an Eclipse Bugzilla login can propose patches.

In order to propose a change to Tycho

  • Configure the repository URL https://git.eclipse.org/r/tycho/org.eclipse.tycho.git for the remote "origin"
  • Know your Gerrit HTTPS user name and password
  • Push to the special code review branch "refs/for/master", e.g. with git push origin HEAD:refs/for/master

For more information on the Eclipse Gerrit instance (e.g. how to push via SSH), see here: Gerrit.

Note that prototypes and other incomplete work should be pushed to the refs/for/master/POC branch so committers know the nature of the changed being pushed.

Using Bugzilla

Attach the patch(es) to the bug/enhancement in Bugzilla. The patch should be in the format produced by git format-patch, so that it is suitable for git am.

Legal Paperwork

With the contribution, you will have to include answers to the following questions (e.g. as comment in Gerrit or Bugzilla):

  1. Did you author 100% of the content you are contributing?
  2. Who owns the copyright of the contributed content? (This is typically your employer.)
  3. Is the contributed code licensed under the EPL? (You should answer this question by putting a copyright and license header into every new java file.)
  4. Do you have the right to contribute the content to Eclipse? (You need to confirm this with the copyright owner.)

With these questions answered, we will be able to accept small patches (<250 LoC) immediately. For larger patches, we will also have to create a contribution questionnaire for review by the Eclipse IP team, but this usually doesn't require additional actions from you.

In general, also see Development Resources#Users: Contributing To A Project.