Difference between revisions of "Tycho/Contributor Guide"

From Eclipsepedia

Jump to: navigation, search
m
(emphasise separation of commits for refactorings)
Line 6: Line 6:
 
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.
  
== Writing Tests ==
+
=== Writing Tests ===
 
Tycho has two types of tests: unit tests (locally in each module) and a global integration test suite in module [http://git.eclipse.org/c/tycho/org.eclipse.tycho.git/tree/tycho-its tycho-its].
 
Tycho has two types of tests: unit tests (locally in each module) and a global integration test suite in module [http://git.eclipse.org/c/tycho/org.eclipse.tycho.git/tree/tycho-its tycho-its].
  
Line 14: Line 14:
 
See an example for a  [http://git.eclipse.org/c/tycho/org.eclipse.tycho.git/tree/tycho-core/src/test/java/org/eclipse/tycho/core/locking/FileLockServiceTest.java unit test] and an [http://git.eclipse.org/c/tycho/org.eclipse.tycho.git/tree/tycho-its/src/test/java/org/eclipse/tycho/test/featurePatch/external/EclipseRepoIncludingFeaturePatchTest.java integration test].
 
See an example for a  [http://git.eclipse.org/c/tycho/org.eclipse.tycho.git/tree/tycho-core/src/test/java/org/eclipse/tycho/core/locking/FileLockServiceTest.java unit test] and an [http://git.eclipse.org/c/tycho/org.eclipse.tycho.git/tree/tycho-its/src/test/java/org/eclipse/tycho/test/featurePatch/external/EclipseRepoIncludingFeaturePatchTest.java integration test].
  
== Commit Message Guidelines ==
+
=== Commit Message Guidelines ===
  
 
* The first sentence should be a clear and concise description about the change
 
* The first sentence should be a clear and concise description about the change
Line 23: Line 23:
 
See an [http://git.eclipse.org/c/tycho/org.eclipse.tycho.git/commit/?id=713962c047eb048223d711c62bdb418931172890 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, as small as reasonable. 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'.  
+
* 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.
 
* Split your work into multiple smaller pieces of work (when possible) and implement each of these pieces in a series of commits.
  
  
== Patch Format ==
+
=== Patch Format ===
  
 
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.
 
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.

Revision as of 10:14, 13 December 2011

Contents

How to contribute patches to Tycho

First, read 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 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.

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

  • The first sentence should be a clear and concise description about the change
  • Enter a newline before providing a more detailed description about the change
  • When you fix a bug then report which bug you fix. The commit message should start with the bug number.
  • 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.

See an example commit message

Commit Granularity

  • Make small commits, as small as reasonable. 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.
  • Split your work into multiple smaller pieces of work (when possible) and implement each of these pieces in a series of commits.


Patch Format

We prefer git patches created with 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.

Contributing the Patch

Open a 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).

You will have to include answers to the following questions:

  1. Did you author 100% of the content you are contributing ?
  2. Do you have the rights to donate the content to Eclipse ?
  3. 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.

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