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.
Difference between revisions of "Tycho/Contributor Guide"
< Tycho
(Add to "How to Contribute" category) |
(update commit message guidelines to refelct the "Bug: <number>" prefix) |
||
| (5 intermediate revisions by 2 users not shown) | |||
| Line 3: | Line 3: | ||
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. | 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 | + | If you want to do a contribution but don't know where to start, you should to check the [https://bugs.eclipse.org/bugs/buglist.cgi?classification=Technology&product=Tycho&keywords=helpwanted&resolution=--- open bugs tagged with keyword "helpwanted"]. These are bugs with moderate complexity and estimated effort. In case of questions related to a contribution, you can also just ask on [mailto:tycho-dev@eclipse.org tycho-dev@eclipse.org]. |
== Developing Patches for Tycho == | == Developing Patches for Tycho == | ||
| Line 9: | Line 9: | ||
The technical basics (how to get the sources, how to import and build, etc.) are described here: [[Developing Tycho]] . | The technical basics (how to get the sources, how to import and build, etc.) are described here: [[Developing Tycho]] . | ||
| − | Unless the patch is really trivial, make sure you include at least one test case that reproduces the bug or proves that the enhancement works | + | Unless the patch is really trivial, make sure you include at least one test case that reproduces the bug or proves that the enhancement works. |
| − | + | ||
| − | + | ||
=== Writing Tests === | === Writing Tests === | ||
| Line 17: | Line 15: | ||
Unit tests are preferred if possible because they are in general much faster and better targeted at the functionality under test. | 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 | + | Integration tests generally invoke a forked Maven build on a sample project (stored under [http://git.eclipse.org/c/tycho/org.eclipse.tycho.git/tree/tycho-its/projects projects/]) and then do some assertions on the build results. |
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]. | ||
| Line 23: | Line 21: | ||
=== Commit Message Guidelines === | === Commit Message Guidelines === | ||
| − | * Start with the bug number the change is related to; | + | * Start with "Bug: <number>" stating the bug number the change is related to; this will enable the eclipse genie bot to automatically cross-link bug and gerrit proposal |
* Also in the first line, provide a clear and concise description of the change | * 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 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 "Signed-off-by: <your_email_adress>" in the footer (see "Legal Paperwork" below). | * Add "Signed-off-by: <your_email_adress>" in the footer (see "Legal Paperwork" below). | ||
| − | See | + | See an [http://git.eclipse.org/c/tycho/org.eclipse.tycho.git/commit/?id=309fbd05d46510671218ef2863885b48a12d8451 example commit message] |
=== Commit Granularity === | === Commit Granularity === | ||
| Line 41: | Line 38: | ||
Before your contribution can be accepted by the project, you need to create and | Before your contribution can be accepted by the project, you need to create and | ||
| − | electronically sign the Eclipse Foundation Contributor License Agreement (CLA) and sign | + | [[Development Resources/Contributing via Git#Eclipse_Foundation_Contributor_License_Agreement | electronically sign the Eclipse Foundation Contributor License Agreement (CLA)]] and sign |
off on the Eclipse Foundation Certificate of Origin. | off on the Eclipse Foundation Certificate of Origin. | ||
| Line 48: | Line 45: | ||
In general, also see [[Development Resources#Users: Contributing To A Project]]. | In general, also see [[Development Resources#Users: Contributing To A Project]]. | ||
| − | === | + | === Pushing to Gerrit === |
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. | 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. | ||
In order to propose a change to Tycho | In order to propose a change to Tycho | ||
| − | * Configure the repository URL <tt>https:</tt><tt>//git.eclipse.org/r/tycho/org.eclipse.tycho | + | * Configure the repository URL <tt>https:</tt><tt>//git.eclipse.org/r/tycho/org.eclipse.tycho</tt> for the remote "origin" |
* Know your [https://git.eclipse.org/r/#/settings/http-password Gerrit HTTPS user name and password] | * 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> | * Push to the special code review branch "refs/for/master", e.g. with <tt>git push origin HEAD:refs/for/master</tt> | ||
| Line 59: | Line 56: | ||
For more information on the Eclipse Gerrit instance (e.g. how to push via SSH), see here: [[Gerrit]]. | 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 | + | Note that prototypes and other incomplete work should be clearly marked as such e.g. by adding "POC" or "WIP" in the commit message, by commenting in Gerrit, or by pushing to the refs/for/master/POC topic branch. This avoids that committers spend time on reviewing incomplete changes. |
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
[[Category:Tycho|Contributor Guide]] | [[Category:Tycho|Contributor Guide]] | ||
[[Category:How to Contribute]] | [[Category:How to Contribute]] | ||
Revision as of 06:53, 10 December 2015
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 a contribution but don't know where to start, you should to check the open bugs tagged with keyword "helpwanted". These are bugs with moderate complexity and estimated effort. In case of questions related to a contribution, 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 .
Unless the patch is really trivial, make sure you include at least one 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 results.
See an example for a unit test and an integration test.
Commit Message Guidelines
- Start with "Bug: <number>" stating the bug number the change is related to; this will enable the eclipse genie bot to automatically cross-link bug and gerrit proposal
- 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 "Signed-off-by: <your_email_adress>" in the footer (see "Legal Paperwork" below).
See 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
Legal Paperwork
Before your contribution can be accepted by the project, you need to create and electronically sign the Eclipse Foundation Contributor License Agreement (CLA) and sign off on the Eclipse Foundation Certificate of Origin.
Follow the instructions on Development_Resources/Handling Git Contributions
In general, also see Development Resources#Users: Contributing To A Project.
Pushing to 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 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 clearly marked as such e.g. by adding "POC" or "WIP" in the commit message, by commenting in Gerrit, or by pushing to the refs/for/master/POC topic branch. This avoids that committers spend time on reviewing incomplete changes.