Skip to main content

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.

Jump to: navigation, search

Difference between revisions of "SWTBot/Contributing"

(IDE tips)
(Generalities)
 
(17 intermediate revisions by the same user not shown)
Line 9: Line 9:
 
# Choose your preferred installation settings on the ''Variables'' page:
 
# Choose your preferred installation settings on the ''Variables'' page:
 
## If you plan to contribute patches using Gerrit ([[#Provide_a_contribution_using_Gerrit|section about Gerrit]]), check "Show all variables" and make sure you select ("SSH (read-write Gerrit)") in the ''Git or Gerrit repository''; the git URI will then look like <pre>ssh://${git.user.id|username}@git.eclipse.org:29418/swtbot/org.eclipse.swtbot</pre>  
 
## If you plan to contribute patches using Gerrit ([[#Provide_a_contribution_using_Gerrit|section about Gerrit]]), check "Show all variables" and make sure you select ("SSH (read-write Gerrit)") in the ''Git or Gerrit repository''; the git URI will then look like <pre>ssh://${git.user.id|username}@git.eclipse.org:29418/swtbot/org.eclipse.swtbot</pre>  
## Then specify your Bugzilla/Hudson password and Git/Gerrit user ID (you can also specify the password and check that your credential are correct using the "Authenticate..." button). An example is shown in the following screenshot. [[File:Swtbot-oomph-variables.png]]
+
## Then specify your Bugzilla/Jenkins password and Git/Gerrit user ID (you can also specify the password and check that your credential are correct using the "Authenticate..." button). An example is shown in the following screenshot. [[File:Swtbot-oomph-variables.png]]
 
# Press next and finish.
 
# Press next and finish.
  
Line 18: Line 18:
 
* setup the API baseline
 
* setup the API baseline
 
* setup Mylyn queries for SWTBot Bugzilla bugs and SWTBot Gerrit reviews
 
* setup Mylyn queries for SWTBot Bugzilla bugs and SWTBot Gerrit reviews
* setup the Mylyn Hudson build view
+
* setup the Mylyn Jenkins build view
 
* setup the working sets
 
* setup the working sets
  
Line 67: Line 67:
 
== Building SWTBot ==
 
== Building SWTBot ==
  
# First Get the sources, as explained a few lines above.
+
# First get the sources, as explained a few lines above.
 
# then <tt>mvn clean verify</tt>
 
# then <tt>mvn clean verify</tt>
 
# That's all!
 
# That's all!
  
NOTE: default build performs against Eclipse Luna. You can test and build against Juno instead by activating the "juno" profile: <tt>mvn clean verify -P juno</tt>, for Kepler, run <tt>mvn clean verify -P kepler</tt>, and for Indigo, run <tt>mvn clean verify -P indigo</tt>.
+
NOTE: default build performs against the latest available target. You can test and build against another target instead by activating its profile, e.g.: <tt>mvn clean verify -P photon</tt>.
  
 
== Continuous integration ==
 
== Continuous integration ==
  
Continuous integrations jobs for SWTBot are available here https://hudson.eclipse.org/swtbot . Here is a quick description of available jobs:  
+
Continuous integrations jobs for SWTBot are available here https://ci.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'' 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-on-*'' compiles and runs tests against a specific Eclipse 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-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]]  
+
* ''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 86: Line 85:
 
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/swtbot/job/SWTBot-Sonar/
+
* contains results of dedicated build https://ci.eclipse.org/swtbot/job/swtbot-sonar/
  
 
== Submit a contribution ==
 
== Submit a contribution ==
Line 93: Line 92:
  
 
Patches and contributions are always welcome! There are many general articles about contributing to Eclipse projects:
 
Patches and contributions are always welcome! There are many general articles about contributing to Eclipse projects:
* [http://blog.hantsuki.org/2008/03/07/how-to-contribute-to-eclipse-projects/ How to contribute to Eclipse projects...]
+
* [https://wiki.eclipse.org/How_to_contribute How to contribute]
* [http://www.eclipsezone.com/eclipse/forums/t99339.html Getting started with Eclipse plug-ins: contributing to Eclipse]
+
* [https://wiki.eclipse.org/Gerrit Gerrit]
 
* [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]
  
Line 133: Line 132:
  
 
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.
 
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:
 
# <tt>git checkout branch_you_want_to_edit</tt>
 
# Modify code
 
# <tt>git add your/modified/file1 your/modified/file2 ...</tt>
 
# <tt>git commit</tt> Put number of the bug you are working on at the beginning of commit message
 
# <tt>git format-patch HEAD^</tt>
 
# Attach generated patch to the bug you want to contribute to.
 
  
 
== Committers ==
 
== Committers ==
Line 159: Line 148:
 
== Release process ==
 
== Release process ==
  
# Make sure upcoming release is listed in http://projects.eclipse.org/projects/technology.swtbot/releases
+
# Make sure upcoming release is listed in http://projects.eclipse.org/projects/technology.swtbot/releases. Click the 'Create a new release...' link and fill the requested information. To edit the release details, select it in the table and click the 'Edit' tab on the following page.
# Announce wish to release on swtbot-dev mailing-list, and wait for approval of committers
+
# 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).
+
# When participating in a new simultaneous release, [https://wiki.eclipse.org/SimRel/Simultaneous_Release_Requirements#State_intent_early_.28M4.29 state your intent] by sending a message to the cross-project-issues-dev mailing list by M1, or by touching the swtbot.aggrcon file by M2.
# Keep the build and Tag then with the version of the release using Hudson UI.
+
# To create a Milestone or Release Candidate build for a simultaneous release, on [https://ci.eclipse.org/swtbot/ Jenkins] run the swtbot-tycho job to create a snapshot then run the swtbot-milestone job to copy the snapshot to the milestones download area. Then update the simultaneous release aggregator file (swtbot.aggrcon) to point to the milestone folder via a [https://wiki.eclipse.org/Simrel/Contributing_to_Simrel_Aggregation_Build#Contribute_via_a_Gerrit_review_.28recommended.29 Gerrit change on the correct target branch] ([https://git.eclipse.org/r/80728 example]).
# Tag source
+
# Generate an IPLog from the [https://projects.eclipse.org/projects/technology.swtbot project page] in the Committer Tools side menu
<source lang="bash">
+
# A bug may be created by the EMO to track the release. When PMC approval is required, send a message to the technology-pmc mailing list ([https://www.eclipse.org/lists/technology-pmc/msg09921.html example]).
$ git fetch eclipse master
+
# Schedule a release review. From the release record page, click the 'Schedule a review for this release' link that appears at the top.
$ git checkout FETCH_HEAD
+
# Send an email to emo@eclipse.org stating your intent to release.
$ git tag 2.1.1 -m "SWTBot 2.1.1 release"
+
# Wait for the release review to be approved.
$ git push gerrit 2.1.1
+
# Run all builds on [https://ci.eclipse.org/swtbot/ Jenkins] (swtbot-tycho, swtbot-sonar).
</source>
+
# Keep the build and tag it with the version of the release using Jenkins UI. In the Job Dashboard for swtbot-tycho, select the build and click 'Keep this build forever', then in the 'Edit Build Information' page change 'DisplayName' to e.g. '2.1.1 release'.
# Once all CI builds are done, go on build.eclipse.org, copy make the release available
+
# Tag source in git repository. From the History view, select the commit and click 'Create Tag...'. Set the tag name to the release version, e.g. '2.1.1', and the message to 'SWTBot 2.1.1 release'. Then from Git Repositories view, select the org.eclipse.swtbot repository and click 'Remote > Push Tags...', select the new tag and finish the wizard.
<source lang="bash">
+
# Run the swtbot-release job to copy the build to the releases download area.
$ ssh mistria@build.eclipse.org
+
# From http://portal.eclipse.org, update Bugzilla in the Committer Tools to add the released version as a "version" and the next version as a "milestone".
$ cd download/technology/swtbot
+
# Update wiki pages [[../#Update Sites]] and [[../Releases]].
$ 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.
 
# 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
+
# Announce release on swtbot-dev mailing-list and SWTBot forum ([https://dev.eclipse.org/mhonarc/lists/swtbot-dev/msg00698.html example]).
<pre>
+
# Update the simultaneous release aggregator file (swtbot.aggrcon) to point to the new release folder via a [https://wiki.eclipse.org/Simrel/Contributing_to_Simrel_Aggregation_Build#Contribute_via_a_Gerrit_review_.28recommended.29 Gerrit change on the correct target branch] ([https://git.eclipse.org/r/72320 example]).
Hi all,
+
# Change all pom.xml, MANIFEST.MF and feature.xml to use the version of next release, git commit and push.
 
+
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 11:11, 21 May 2021


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


Setting up the workspace with Oomph (NEW)

  1. Download and start Oomph.
  2. On the initial page, click on the Switch to advanced mode button in the top right.
  3. On the Product page, select Eclipse IDE for Eclipse Committers.
  4. On the Projects page, double-click SWTBot
  5. Choose your preferred installation settings on the Variables page:
    1. If you plan to contribute patches using Gerrit (section about Gerrit), check "Show all variables" and make sure you select ("SSH (read-write Gerrit)") in the Git or Gerrit repository; the git URI will then look like
      ssh://${git.user.id|username}@git.eclipse.org:29418/swtbot/org.eclipse.swtbot
    2. Then specify your Bugzilla/Jenkins password and Git/Gerrit user ID (you can also specify the password and check that your credential are correct using the "Authenticate..." button). An example is shown in the following screenshot. Swtbot-oomph-variables.png
  6. Press next and finish.

This will first create an Eclipse installation with all the needed plug-ins for developing SWTBot (including the Recommended Eclipse plugins), and then will start the new installed Eclipse (press Finish to close the first installation dialog). The new installed Eclipse will automatically setup the workspace and you will have to wait for this procedure to end (you can click on the animated arrow icon on the status bar to show the progress). This workspace setup procedure includes:

  • cloning the SWTBot git repository (you'll be asked for a password if you selected the read-write git URI)
  • setup the target platform
  • setup the API baseline
  • setup Mylyn queries for SWTBot Bugzilla bugs and SWTBot Gerrit reviews
  • setup the Mylyn Jenkins build view
  • setup the working sets

Once this procedure ends, your workspace will be built and you are ready to develop.

The installed Eclipse can be found in the "Installation folder name" selected in the "Variables" dialog, under the subdirectory "eclipse".

Getting the source (old manual way)

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.

API Baseline

To track API changes, it is advised to use the API tool. To set up the API baseline, follow these steps:

  • Select "Window -> Preferences". In the window that opens, select "Plug-in Development -> API Baselines" on the left pane.
  • Click on "Add Baseline..."
  • Choose "A target platform" and click Next.
  • In the next page check the box next to the target which contains "baseline" in its name, like "swtbot-baseline".
  • Click "Reset" to download the contents of the target.
  • Specify a name for this baseline in the top area, like "SWTBot API" for example.
  • Click "Finish", then "OK" in the previous dialog.

It should offer you do to a full rebuild. You can click "Yes" at this point.

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 the latest available target. You can test and build against another target instead by activating its profile, e.g.: mvn clean verify -P photon.

Continuous integration

Continuous integrations jobs for SWTBot are available here https://ci.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-on-* compiles and runs tests against a specific Eclipse 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

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.

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. Click the 'Create a new release...' link and fill the requested information. To edit the release details, select it in the table and click the 'Edit' tab on the following page.
  2. Announce wish to release on swtbot-dev mailing-list, and wait for approval of committers.
  3. When participating in a new simultaneous release, state your intent by sending a message to the cross-project-issues-dev mailing list by M1, or by touching the swtbot.aggrcon file by M2.
  4. To create a Milestone or Release Candidate build for a simultaneous release, on Jenkins run the swtbot-tycho job to create a snapshot then run the swtbot-milestone job to copy the snapshot to the milestones download area. Then update the simultaneous release aggregator file (swtbot.aggrcon) to point to the milestone folder via a Gerrit change on the correct target branch (example).
  5. Generate an IPLog from the project page in the Committer Tools side menu
  6. A bug may be created by the EMO to track the release. When PMC approval is required, send a message to the technology-pmc mailing list (example).
  7. Schedule a release review. From the release record page, click the 'Schedule a review for this release' link that appears at the top.
  8. Send an email to emo@eclipse.org stating your intent to release.
  9. Wait for the release review to be approved.
  10. Run all builds on Jenkins (swtbot-tycho, swtbot-sonar).
  11. Keep the build and tag it with the version of the release using Jenkins UI. In the Job Dashboard for swtbot-tycho, select the build and click 'Keep this build forever', then in the 'Edit Build Information' page change 'DisplayName' to e.g. '2.1.1 release'.
  12. Tag source in git repository. From the History view, select the commit and click 'Create Tag...'. Set the tag name to the release version, e.g. '2.1.1', and the message to 'SWTBot 2.1.1 release'. Then from Git Repositories view, select the org.eclipse.swtbot repository and click 'Remote > Push Tags...', select the new tag and finish the wizard.
  13. Run the swtbot-release job to copy the build to the releases download area.
  14. From http://portal.eclipse.org, update Bugzilla in the Committer Tools to add the released version as a "version" and the next version as a "milestone".
  15. Update wiki pages SWTBot#Update Sites and SWTBot/Releases.
  16. If necessary, update SWTBot marketplace entry. Since it's referencing the releases/latest URL, no change should be required.
  17. Announce release on swtbot-dev mailing-list and SWTBot forum (example).
  18. Update the simultaneous release aggregator file (swtbot.aggrcon) to point to the new release folder via a Gerrit change on the correct target branch (example).
  19. Change all pom.xml, MANIFEST.MF and feature.xml to use the version of next release, git commit and push.

Back to the top