Jump to: navigation, search

Difference between revisions of "SWTBot/Contributing"

m (Provide a contribution using Gerrit)
 
(16 intermediate revisions by 2 users not shown)
Line 15: Line 15:
 
It's advised that you use the following plugins in Eclipse:
 
It's advised that you use the following plugins in Eclipse:
 
* EGit
 
* EGit
* FindBugs
+
* FindBugs (with a high "Minimum rank to report" set in ''Window > Preferences > Java > Findbugs'')
* Configure JDT in "pedantic" mode (make all violations send a warning, ignore nothing)
+
* Configure JDT in "pedantic" mode: from ''Window > Preferences > Java > Compiler > Errors/Warning'' make all violations send a warning, ignore nothing.
 
* EclEmma is useful to analyze Coverage Reports
 
* EclEmma is useful to analyze Coverage Reports
 
* ... Any other tool that makes you write better code faster ...
 
* ... Any other tool that makes you write better code faster ...
  
=== Target Platform ===
+
=== Target Platforms ===
  
You can find a ready-to-use target platform for development in the ''devtools/target-platforms'' folder. This target-platform is recommended since it contains all SWTBot dependencies. Beware, this target-platform is not used at build time, so you may experiment some differences. In such case, please report them as a bug. Enable it by opening it in IDE with the target definition editor, and click ''Set As Target Platform''.
+
You can find some ready-to-use target platforms for development in the ''devtools/target-platforms'' folder. Each target-platform basically target a version of the Eclipse release train. It's recommended to use one of these target-platform since it contains all SWTBot dependencie. These target-platforms are also used at build time, so your dependencies in IDE will be consistent with dependencies during build. Enable the selected target-platform by opening it in IDE with the target definition editor, and click ''Set As Target Platform''.
 +
 
 +
In case something is not working well, please report them as a bug.
  
 
== Building SWTBot ==
 
== Building SWTBot ==
Line 30: Line 32:
 
# That's all!
 
# That's all!
  
NOTE: default build performs against Eclipse Indigo. You can test and build against Juno instead by activatin the "juno" profile: <tt>mvn clean install -P juno</tt>
+
NOTE: default build performs against Eclipse Indigo. You can test and build against Juno instead by activatin the "juno" profile: <tt>mvn clean verify -P juno</tt>, and for Kepler, run <tt>mvn clean verify -P kepler</tt>.
  
 
== Continuous integration ==
 
== Continuous integration ==
  
Continuous integrations build for swtbot are available here:
+
Continuous integrations jobs for SWTBot are available here https://hudson.eclipse.org/swtbot . Here is a quick description of available jobs:
* https://hudson.eclipse.org/hudson/job/swtbot-tycho/
+
* ''swtbot-tycho'' is the main CI job. It builds and run tests against an Eclipse Indigo platform and publishes output p2 repository to http://download.eclipse.org/technology/swtbot/snapshots
* https://hudson.eclipse.org/hudson/job/swtbot-tycho-e4.2/
+
* ''swtbot-tycho-e4.2'' compiles and runs tests against the last release of Eclipse 4.x branch. It guarantees compatibility with a wide range of Eclipse versions
 
+
* ''swtbot-gerrit'' compiles and runs tests against any Gerrit contribution, and then add a vote to the contribution: +1 if everything is fine, -1 in case of a compile error, build error, or failed test
A view also exists, it contains also older build configurations: https://hudson.eclipse.org/hudson/view/SWTBot/
+
* ''SWTBot-Sonar'' runs (weekly) build and tests against last commit of master branch and generates Sonar reports. See [[#Sonar]]
 +
* Other ''swtbot-*'' are legacy jobs, prior to usage of Maven (2.0.5 and older).
  
 
== Sonar ==
 
== Sonar ==
Line 44: Line 47:
 
Sonar is used in order to track Code Quality:
 
Sonar is used in order to track Code Quality:
 
* https://dev.eclipse.org/sonar/dashboard/index/1
 
* https://dev.eclipse.org/sonar/dashboard/index/1
* contains results of dedicated build https://hudson.eclipse.org/sandbox/job/SWTBot-Sonar/
+
* contains results of dedicated build https://hudson.eclipse.org/swtbot/job/SWTBot-Sonar/
  
 
== Submit a contribution ==
 
== Submit a contribution ==
Line 54: Line 57:
 
* [http://www.eclipsezone.com/eclipse/forums/t99339.html Getting started with Eclipse plug-ins: contributing to Eclipse]
 
* [http://www.eclipsezone.com/eclipse/forums/t99339.html Getting started with Eclipse plug-ins: contributing to Eclipse]
 
* [http://www.eclipse.org/articles/article.php?file=Article-How-to-Fix-a-Bug-in-Eclipse/index.html How to Fix a Bug in Eclipse]
 
* [http://www.eclipse.org/articles/article.php?file=Article-How-to-Fix-a-Bug-in-Eclipse/index.html How to Fix a Bug in Eclipse]
 +
 +
=== Report a bug or suggest an enhancement ===
 +
 +
Just create a ticket here: https://bugs.eclipse.org/bugs/enter_bug.cgi?product=SWTBot
  
 
=== Contributions list ===
 
=== Contributions list ===
Line 67: Line 74:
 
=== Provide a contribution using Gerrit ===
 
=== Provide a contribution using Gerrit ===
  
# First, read '''carefully''' this documents: [[Gerrit]] to set up commit hooks and other things. We recommand using the [[Gerrit#Using_Gerrit_with_EGit: | EGit-Gerrit connector]].
+
# First, make sure you have agreed and signed the [http://www.eclipse.org/legal/clafaq.php Eclipse Contribution CLA].
 +
# Then find out the repository URL. It should be something like 'ssh://username@git.eclipse.org:29418/swtbot/org.eclipse.swtbot.git'. In case you're unsure of the Gerrt repo URL, you can find it at https://git.eclipse.org/r/#/admin/projects/swtbot/org.eclipse.swtbot , once you're logged in.
 +
# Then, read '''carefully''' this documents: [[Gerrit]] to set up commit hooks, learn about Change-Ids and other things.
 +
 
 +
We recommand using the [[Gerrit#Using_Gerrit_with_EGit | EGit-Gerrit connector]]. Make sure that the options ''Add Signed-off by'' and ''Compute Change-Id for Gerrit Code-Review'' are selected in the commit dialog. After the push, the next dialog should show you the log message, which includes the Gerrit review URL.
 +
 
 
In case you work without EGit Gerrit connector:
 
In case you work without EGit Gerrit connector:
 
# Make your change locally, and ''git commit'' them in your local repo. Commit message must contain Bug Number.
 
# Make your change locally, and ''git commit'' them in your local repo. Commit message must contain Bug Number.
# when you're ready, ''git push'' your change to Gerrit using the following command: <tt>git push ssh://username@git.eclipse.org:29418/swtbot/org.eclipse.swtbot.git HEAD:refs/for/master</tt>
+
# When you're ready, ''git push'' your change to Gerrit using the following command: <tt>git push ssh://username@git.eclipse.org:29418/swtbot/org.eclipse.swtbot.git HEAD:refs/for/master</tt> or
# After the push, log tells you about a URL which tracks the contribution
+
<source lang="bash">
 +
$ git remote add gerrit
 +
$ git push gerrit HEAD:refs/for/master
 +
</source>
 +
# After the push, log tells you about a URL which tracks the  
 +
 
 
In any case
 
In any case
# Share this URL on the bug you're working on.
+
# Share the URL of the review on the bug you're working on.
 +
 
 +
 
 +
If you want to push an improved version of the patch, just amend your commit, make sure it has the same Change-Id as the original one, and push it again to refs/for/master. This will create another version of your patch, on the same Gerrit review.
  
 
=== Provide a patch (Deprecated in favor of Gerrit) ===
 
=== Provide a patch (Deprecated in favor of Gerrit) ===
Line 91: Line 111:
 
* A Gerrit contribution is automatically merged when all "acceptance flags" (Verification, review, IP) are OK.
 
* A Gerrit contribution is automatically merged when all "acceptance flags" (Verification, review, IP) are OK.
  
== Editing website ==
+
== Contribute changes to website ==
  
 
Website can also be edited using Git and Gerrit process mentioned about for sources:
 
Website can also be edited using Git and Gerrit process mentioned about for sources:
Line 97: Line 117:
  
 
[[Category:Draft Documentation]]
 
[[Category:Draft Documentation]]
 +
 +
== Release process ==
 +
 +
# Make sure upcoming release is listed in http://projects.eclipse.org/projects/technology.swtbot/releases
 +
# Announce wish to release on swtbot-dev mailing-list, and wait for approval of committers
 +
# Run all builds on Hudson (swtbot-tycho, swtbot-tycho-e42, swtbot-sonar).
 +
# Keep the build and Tag then with the version of the release using Hudson UI.
 +
# Tag source
 +
<source lang="bash">
 +
$ git fetch eclipse master
 +
$ git checkout FETCH_HEAD
 +
$ git tag 2.1.1 -m "SWTBot 2.1.1 release"
 +
$ git push gerrit 2.1.1
 +
</source>
 +
# Once all CI builds are done, go on build.eclipse.org, copy make the release available
 +
<source lang="bash">
 +
$ ssh mistria@build.eclipse.org
 +
$ cd download/technology/swtbot
 +
$ cp snapshots releases/2.1.1
 +
$ rm -r releases/latest
 +
$ cp releases/2.1.1 releases/latest
 +
</source>
 +
# Change all pom.xml, MANIFEST.MF and feature.xml to use the version of next release, git commit and push
 +
# Change bugzilla milestones (from portal.eclipse.org) to create a new release (2.1.1) and a new milestone (2.1.2)
 +
# Update wiki pages [[../#Update Sites]] and [[../Releases]]
 +
# If necessary, update [https://marketplace.eclipse.org/content/swtbot SWTBot marketplace entry]. Since it's referencing the ''releases/latest'' URL, no change should be required.
 +
# Announce release on swtbot-dev mailing-list and SWTBot forum
 +
<pre>
 +
Hi all,
 +
 +
We're happy to announce you the release of SWTBot 2.2.0.
 +
Main changes are:
 +
* Introduction of UI to assist in usage of test Recorder (cf http://wiki.eclipse.org/SWTBot/Recorder#I.27m_using_an_IDE_to_write_test )
 +
* Branding
 +
* Introduction of a drag'n'drop APO
 +
The full list of changes can be found here: https://bugs.eclipse.org/bugs/buglist.cgi?list_id=6242414&classification=Technology&query_format=advanced&target_milestone=2.2.0&product=SWTBot
 +
Git tag can be found here: http://git.eclipse.org/c/swtbot/org.eclipse.swtbot.git/tag/?id=2.2.0
 +
And release p2 repository can be found here http://download.eclipse.org/technology/swtbot/releases/2.2.0 (and http://download.eclipse.org/technology/swtbot/releases/latest ).
 +
 +
Big thanks to everyone who contributed to this release in any way.
 +
Very big thanks to the people who contributed code in this release: Rohi Agrawal, Michal Borek, Marcel Hoetter, Mickael Istria, Kristine Jetzke, Jan Koehnlein, Ingo Mohr, Frank Schuerer, Robin Stocke, Rastislav Wagner.
 +
 +
Enjoy!
 +
</pre>
 +
# From http://portal.eclipse.org, update Bugzilla to add the released version as a "Version" and the next version as a "milestone".

Latest revision as of 09:13, 14 November 2014


SWTBot
Website
Update Sites
Community
Mailing List
Forums/Newsgroups
IRC
Contribute
Open Bugzilla tickets
Open Gerrit reviews
Browse Source
Continuous Integration


Getting the source

You can use a git mirror of that repository:

git clone git://git.eclipse.org/gitroot/swtbot/org.eclipse.swtbot.git

You can also browse the repository using a web interface or even by monitoring the mirror of the repository on GitHub.

To contribute changes to the website, use this git repo: https://git.eclipse.org/c/www.eclipse.org/swtbot.git

IDE tips

Recommended Eclipse plugins

It's advised that you use the following plugins in Eclipse:

  • EGit
  • FindBugs (with a high "Minimum rank to report" set in Window > Preferences > Java > Findbugs)
  • Configure JDT in "pedantic" mode: from Window > Preferences > Java > Compiler > Errors/Warning make all violations send a warning, ignore nothing.
  • EclEmma is useful to analyze Coverage Reports
  • ... Any other tool that makes you write better code faster ...

Target Platforms

You can find some ready-to-use target platforms for development in the devtools/target-platforms folder. Each target-platform basically target a version of the Eclipse release train. It's recommended to use one of these target-platform since it contains all SWTBot dependencie. These target-platforms are also used at build time, so your dependencies in IDE will be consistent with dependencies during build. Enable the selected target-platform by opening it in IDE with the target definition editor, and click Set As Target Platform.

In case something is not working well, please report them as a bug.

Building SWTBot

  1. First Get the sources, as explained a few lines above.
  2. then mvn clean verify
  3. That's all!

NOTE: default build performs against Eclipse Indigo. You can test and build against Juno instead by activatin the "juno" profile: mvn clean verify -P juno, and for Kepler, run mvn clean verify -P kepler.

Continuous integration

Continuous integrations jobs for SWTBot are available here https://hudson.eclipse.org/swtbot . Here is a quick description of available jobs:

  • swtbot-tycho is the main CI job. It builds and run tests against an Eclipse Indigo platform and publishes output p2 repository to http://download.eclipse.org/technology/swtbot/snapshots
  • swtbot-tycho-e4.2 compiles and runs tests against the last release of Eclipse 4.x branch. It guarantees compatibility with a wide range of Eclipse versions
  • swtbot-gerrit compiles and runs tests against any Gerrit contribution, and then add a vote to the contribution: +1 if everything is fine, -1 in case of a compile error, build error, or failed test
  • SWTBot-Sonar runs (weekly) build and tests against last commit of master branch and generates Sonar reports. See #Sonar
  • Other swtbot-* are legacy jobs, prior to usage of Maven (2.0.5 and older).

Sonar

Sonar is used in order to track Code Quality:

Submit a contribution

Generalities

Patches and contributions are always welcome! There are many general articles about contributing to Eclipse projects:

Report a bug or suggest an enhancement

Just create a ticket here: https://bugs.eclipse.org/bugs/enter_bug.cgi?product=SWTBot

Contributions list

Be notified

Provide a contribution using Gerrit

  1. First, make sure you have agreed and signed the Eclipse Contribution CLA.
  2. Then find out the repository URL. It should be something like 'ssh://username@git.eclipse.org:29418/swtbot/org.eclipse.swtbot.git'. In case you're unsure of the Gerrt repo URL, you can find it at https://git.eclipse.org/r/#/admin/projects/swtbot/org.eclipse.swtbot , once you're logged in.
  3. Then, read carefully this documents: Gerrit to set up commit hooks, learn about Change-Ids and other things.

We recommand using the EGit-Gerrit connector. Make sure that the options Add Signed-off by and Compute Change-Id for Gerrit Code-Review are selected in the commit dialog. After the push, the next dialog should show you the log message, which includes the Gerrit review URL.

In case you work without EGit Gerrit connector:

  1. Make your change locally, and git commit them in your local repo. Commit message must contain Bug Number.
  2. When you're ready, git push your change to Gerrit using the following command: git push ssh://username@git.eclipse.org:29418/swtbot/org.eclipse.swtbot.git HEAD:refs/for/master or
$ git remote add gerrit 
$ git push gerrit HEAD:refs/for/master
  1. After the push, log tells you about a URL which tracks the

In any case

  1. Share the URL of the review on the bug you're working on.


If you want to push an improved version of the patch, just amend your commit, make sure it has the same Change-Id as the original one, and push it again to refs/for/master. This will create another version of your patch, on the same Gerrit review.

Provide a patch (Deprecated in favor of Gerrit)

In order to provide a patch, follow the following process:

  1. git checkout branch_you_want_to_edit
  2. Modify code
  3. git add your/modified/file1 your/modified/file2 ...
  4. git commit Put number of the bug you are working on at the beginning of commit message
  5. git format-patch HEAD^
  6. Attach generated patch to the bug you want to contribute to.

Committers

  • Committer must subscribe to notifications to not miss a contribution. See how to set up nofications
  • Committer have to use Gerrit too and follow same process as contributors. They can approve their own contributions, but asking review from another contributor is a cool thing.
  • A Gerrit contribution is automatically merged when all "acceptance flags" (Verification, review, IP) are OK.

Contribute changes to website

Website can also be edited using Git and Gerrit process mentioned about for sources:

Release process

  1. Make sure upcoming release is listed in http://projects.eclipse.org/projects/technology.swtbot/releases
  2. Announce wish to release on swtbot-dev mailing-list, and wait for approval of committers
  3. Run all builds on Hudson (swtbot-tycho, swtbot-tycho-e42, swtbot-sonar).
  4. Keep the build and Tag then with the version of the release using Hudson UI.
  5. Tag source
$ git fetch eclipse master
$ git checkout FETCH_HEAD
$ git tag 2.1.1 -m "SWTBot 2.1.1 release"
$ git push gerrit 2.1.1
  1. Once all CI builds are done, go on build.eclipse.org, copy make the release available
$ ssh mistria@build.eclipse.org
$ cd download/technology/swtbot
$ cp snapshots releases/2.1.1
$ rm -r releases/latest
$ cp releases/2.1.1 releases/latest
  1. Change all pom.xml, MANIFEST.MF and feature.xml to use the version of next release, git commit and push
  2. Change bugzilla milestones (from portal.eclipse.org) to create a new release (2.1.1) and a new milestone (2.1.2)
  3. Update wiki pages SWTBot#Update Sites and SWTBot/Releases
  4. If necessary, update SWTBot marketplace entry. Since it's referencing the releases/latest URL, no change should be required.
  5. Announce release on swtbot-dev mailing-list and SWTBot forum
Hi all,

We're happy to announce you the release of SWTBot 2.2.0.
Main changes are:
* Introduction of UI to assist in usage of test Recorder (cf http://wiki.eclipse.org/SWTBot/Recorder#I.27m_using_an_IDE_to_write_test )
* Branding
* Introduction of a drag'n'drop APO
The full list of changes can be found here: https://bugs.eclipse.org/bugs/buglist.cgi?list_id=6242414&classification=Technology&query_format=advanced&target_milestone=2.2.0&product=SWTBot
Git tag can be found here: http://git.eclipse.org/c/swtbot/org.eclipse.swtbot.git/tag/?id=2.2.0
And release p2 repository can be found here http://download.eclipse.org/technology/swtbot/releases/2.2.0 (and http://download.eclipse.org/technology/swtbot/releases/latest ).

Big thanks to everyone who contributed to this release in any way.
Very big thanks to the people who contributed code in this release: Rohi Agrawal, Michal Borek, Marcel Hoetter, Mickael Istria, Kristine Jetzke, Jan Koehnlein, Ingo Mohr, Frank Schuerer, Robin Stocke, Rastislav Wagner.

Enjoy!
  1. From http://portal.eclipse.org, update Bugzilla to add the released version as a "Version" and the next version as a "milestone".