SWT/Devel/Workflow

General tips

Common troubleshooting

Often Eclipse won't launch with various errors. Below are common steps to troubleshoot:

• API Baseline: Make sure API Baseline is set. If you updated Eclipse (e.g Neon to Oxygen), you may need to re-create the baseline.
• Enable Execution Environments: Make sure that relevant Execution Environments are enabled (1.5, 1.6 etc.).

Eclipse Execution Environments

• Target Platform: Make sure to have an Target Platform set. Try re-creating it with Default for running platform.
• Validate Plugins: In the runtime configuration for a child Eclipse, under the 'Plug-ins' tab, instead of launching all plugins, try to select only SWT and the binaries project. Try to Validate the setup to see if there are missing dependencies.

Bugzilla

All SWT bugs and new development work is carried out via the Eclipse Bugzilla instance.

Triage process overview

The goal of triage is a quick initial response to incoming bug submissions from users.
The intent is for users to receive initial feedback on their submission and for bugs to be categorized properly so that developers can find/identify them easily.

If the bug has sufficient information and is reproducible, then add the "triaged" keyword to it and optionally leave some message for the user e.g "Thank you for bug submission, I can reproduce the issue.". The bug status should remain "NEW" and remain assigned to platform-swt-inbox@eclipse.org.

Subsequently, when developers look for new bugs to work on, they can check bugs that have the "triaged" keyword.
All the triaged bugs with assignee as platform-swt-inbox@eclipse.org and status=NEW are considered active but are not currently being worked on. These bugs are available for anyone in the community to work on.
Assign "helpwanted" keyword for bugs that developers might not have time to work, but will review patches for.

The purpose of a bug's status is to tell readers if someone is working on a bug or not:

• NEW means that nobody is working on a bug, you can start work on it.
• ASSIGNED means someone is already working on the bug. When work has started on a bug, (either by you, or patch is being provided by community), then the status can be set to ASSIGNED. If for some reason work stops and requires a new contributor, the status should be returned back to "NEW".

See the following diagram:

As an SWT developer, consider watching the platform-swt-inbox@eclipse.org user in Bugzilla to get notifications about new and triaged bugs.

Triage check list

Use the following as a guideline on how to triage a bug:

• Check for duplicate bugs
• Set/update metadata/keywords/status correctly
• Link to other relevant bugs
• Briefly investigate if bug is real (i.e, reproducible on latest build or branch)
• Ask user to test with newer version if the reported version is very old
• Request versions of SWT/OS/GTK/WebKit. Note, GTK/WebKit versions can be acquired by setting version variable :

 export SWT_LIB_VERSIONS=1
 eclipse

• Request a snippet (or clear steps to reproduce) if it's not clear as to how to reproduce issue
• Ping/CC developers involved in related issue (especially when regressions occur)
• Try to bisect codebase for regression reports (optional/time permitting)

Setting proper metadata

• For severity and priority see the bug priority and severity guidelines.
• Prefix OS and Component to bug summary.
  
  • OS: [GTK][GTK2][GTK3][Wayland][Cocoa][Win32]
    • PI means Native library interface.
    • 64 means 32/64 bit issues.
    • I18N means Internationalization issues.
    • BiDi means Bi-directional text
  • ex: [GTK3] Button background not styled.
• Bug reports which are regressions can make use of the "regression" keyword
• Set appropriate target milestone if we plan to fix it within a particular time frame -- this is usually used by committers.

Bugzilla queries

New Bugs

• Highest voted bugs
• All
• All and Linux, CentOS
• All and Win32
• All and Cocoa

Triaged bugs

• All
• All, Linux, CentOS, Unix
• All, Windows
• All, Cocoa

Query construction

To construct the queries above:

Use quick search. For example:

•  :swt @platform-swt-inbox@eclipse.org -!Triaged
•  :swt @platform-swt-inbox@eclipse.org -!Triaged os:All,Linux,CentOS -os:Windows
• etc.

Columns were changed, such that the following were kept:

• Product, Component, Priority, Severity, Votes, Status, Whiteboard, Target Milestone, Summary, OS, Changed, Opened, Keywords, Tags, Reporter, Version, # of comments
• "Stagger Headers" was used.

Then result was sorted in desired order: Priority, Votes, Severity, Target Milestone

URL was copied.

In the past, triaged bugs were re-assigned from a platform-swt-inbox@eclipse.org to a swt-triaged@eclipse.org user. Instead, we now just add the "triaged" keyword.

In the distant past, bugs were assigned to component owners, but that lead to component owners to have large amount of bugs that they did not actually work on.

Some projects used to use platform-inbox, but to mark a bug as triaged, the "ASSIGNED" status was used. But this could lead to confusion where users could think that

Gerrit

Configure Repository for Gerrit review

Eclipse/SWT uses a code review tool called Gerrit.

Using EGit

It's quite easy to configure Gerrit if you have the EGit plugin installed.

1. Open the "Git Repositories" view
2. Expand the "org.eclipse.swt" item (assuming you have the org.eclipse.platform.swt project in your EGit repositories view)
3. Expand the "Remotes" item
4. Right click the "origin" item, and select "Gerrit configuration"
5. Fill in your information from Gerrit (username).

Manual configuration

Edit your git config file from the SWT repository. The file is located in top level directory of the org.eclipse.platform.swt git repository:

 .git/config

Then add the review branch:

 [remote "review"]
   url = ssh://YOUR_GERRIT_USER_NAME@git.eclipse.org:29418/platform/eclipse.platform.swt.git
   push = HEAD:refs/for/master

Substitute YOUR_GERRIT_USER_NAME with your username like 'lufimtsev' (not your full email address).

Now you can push patches to review

 git push review

Reviewing Changes

Fetching changes from Gerrit into Eclipse

For simplicity and ease of use, you can fetch changes from Gerrit into Eclipse using Egit (this assumes you have it installed).

To do so, you must know the Gerrit change number, and have your git config set up for review. Note: change number is not the same as change-ID.

To find the change number, go to the Gerrit review you intend to fetch and look at the URL to see the change number:

 git.eclipse.org/r/#/c/change_number_will_be_here/ 

You can also look at the header above the commit message, "Change <change_number>".

To fetch it, right click the repository in Eclipse that contains the change, and select "Fetch from Gerrit..." The following window will appear:

File:Fetch from Gerrit window.png

Fetch from Gerrit window

Enter the change number from Gerrit and press Ctrl + Space. Eclipse will pull information for the change and provide a drop down menu of patch sets to choose from. Choose the patch set you wish to fetch.

If you wish to create a separate branch with these changes, keep the default selected option and enter a branch name.

If you want the changes applied against the branch you are currently on, select the "Checkout FETCH_HEAD" option. Click finish and Eclipse will fetch the changes into your workspace.

Identifying dependencies between patches

Sometimes you want to know which patches have to be pushed to master before your patch can be merged (dependencies).

"Related changes" will pop up if there are related changes (e.g your patch depends on another patch, or it's a pre-requisite for another patch).

In older versions of Gerrit, there were explicit titles for 'parent' patches and 'child' patches. However now one thing to note is that the related changes are listed the same way a 'git-log' is listed. Meaning all dependencies will appear below the current patch etc... Please see documentation for details: [[1]]

Adding API to SWT

SWT API has to be backwards compatible, meaning changing existing API is basically not an option (except in a few cases). However it's very common to add new API -- to do so, follow the steps below.

1. Add the API. If you are doing this in a common class, you only have to add it once. Otherwise, be sure to add the constant/method to all platforms' classes.
2. If this is the first time you are adding API in this release cycle, bump the minor "version" fields in the pom.xml and MANIFEST.mf files. For example, 3.107.100 -> 3.108.0
3. Write the Javadocs, and be sure to include @since tags, indicating the API is available since the API version you just bumped in step 2.

Setting an API baseline

In general, it's important to configure API tools properly to warn you about API changes and versions that need to be bumped. To set an API baseline:

1. Go to Windows -> Preferences. Search for "API baseline"
2. Click "Add Baseline"
3. Select "An existing Eclipse installation directory"
4. Click "Browse" and point the wizard to the binary "eclipse" file for your current Eclipse installation
5. Click "Finish"

Mylyn

Mylyn is the task and application lifecycle management (ALM) framework for Eclipse.

Some video tutorials:

• Mylyn overview: Youtube : Mylyn Overview
• Doing Gerrit code reviews on through Mylyn Youtube : Code review inside Eclipse with Gerrit

Writing new and noteworthy (N&N) posts

If you've added a new feature or fixed a significant bug, it's often useful to write an N&N post. N&N posts are short HTML entries in a milestone's/release's N&N page. The N&N page showcases improvements and features for all aspects of the Eclipse IDE during that milestone/release. To write an N&N post:

1. Clone the eclipse/news repository
2. Look for the folder and file corresponding to the milestone/release and component you want to write about (for example: 4.9/platform.html)
3. Follow the instructions in the HTML page and/or look at other posts as example
4. Add a new section with a meaningful title and a short description about the feature/bug that was fixed. Images can be added to further demonstrate the fix (follow the instructions in the HTML file re: images)
5. Upload the change to the Gerrit repo for eclipse/news and add a committer from your component to review it