Apache NetBeansBugtracking Plugin Cookbook
This is a quick how-to for creating a plug-in module for a bugtracking system.
IDE supports several bugtracking systems out-of-the-box but there are numerous other systems still not directly supported in the IDE. We want to encourage community members and especially creators of these bugtracking systems to come and create the support for NetBeans. This how-to tries to make this process as easy as possible and puts you right into the process of coding the plugin itself without first messing with the Bugracking SPI and NetBeans API specifics.
Setup
Working Environment
-
Clone and build the main NetBeans repository at http://github.com/apache/netbeans
Download the Bugtracking skeleton/demo Module
-
Download the project skeleton - http://wiki.netbeans.org/wiki/images/5/5f/XXXBugtracking.zip
-
Unzip the skeleton code to a directory where you will develop the module
Build and test the demo Module
-
Start NetBeans and open the demo project
-
Build and Run the project to check that all is set up
-
Scan TODOs in the code for primary interest points
How To
Please note that until not mentioned otherwise, all classes are from the org.netbeans.modules.bugtracking.spi package.
Register a Connector
-
Create an implementation of
BugtrackingConnectorand register it via theBugtrackingConnector.Registrationannotation. -
see also
org.yourorghere.xxx.XXXConnectorin the attached project sample project
@BugtrackingConnector.Registration (
id=XXXConnector.ID,
displayName=XXXConnector.NAME,
tooltip=XXXConnector.NAME
)
public class XXXConnector implements BugtrackingConnector {
public static final String NAME = "XXX Bugracking";
public static final String ID = "org.yourorghere.xxx.xxxconnector";
...
}
Handle Repositories
Create
Invoked by user action from the Tasks Dashboard.
-
the method
BugtrackingConnector|createRepository()will be invoked when a new repository is supposed to be created. The infrastructure opens then a repository editor dialog and takes care for storing the confirmed repository data. -
see the javadoc on
RepositoryControllerto find out how the repository editor UI is handled. -
those repository data are used the next time when that repository is needed and no object is created yet (e.g. in a new IDE session). This will be done via
BugtrackingConnector.createRepository(RepositoryInfo)
Setup
use the BugtrackingSupport.createRepository(R, …) method when creating a Repository instance, so that the the infrastructure can setup your repo instance with additional feature providers.
-
for more information see the javadoc in:
-
RepositoryProvider(mandatory) -
QueryProvider(mandatory) -
IssueProvider(mandatory) -
IssueStatusProvider(optional) -
IssuePriorityProvider(optional) -
IssueScheduleProvider(optional) -
IssueFinder(optional)
-
-
see also
org.yourorghere.xxx.XXXConnectorin the attached sample
Handle Queries
Creating
Invoked by user action from the Tasks Dashboard.
-
the method
RepositoryProvider|createQuery®is invoked when a new Query is supposed to be created. Create and return an object representing your Query at that place. -
to find out how the lifecycle of queries is handled, see the javadoc of:
-
QueryController -
QueryProvider
-
-
once a Query is saved/persisted, it is expected to be returned by
RepositoryProvider|getQueries®.
Handle Issues
Creating
Invoked by user action from the Tasks Dashboard.
-
when a new Issue is supposed to be created the method
RepositoryProvider|createIssue®will be invoked. Create and return an object representing your Issue. -
to find out how the lifecycle of particular issues is handled, see the javadoc of:
-
IssueController -
IssueProvider
-
Retrieving from a remote repository
-
by Query - see the javadoc on:
-
QueryProvider|refresh(Q) -
IssueContainer
-
-
by Issue ID or text criteria - see the javadoc on:
Status - local and remote changes
Outgoing and incoming Issue changes are annotated (via coloring) in Query result lists in the Tasks Dashboard.
In case you want to provide status values for changes in your Issues then you have to implement the IssueStatusProvider interface and provide it via the BugtrackingSupport.createRepository(R, …) method call.
-
for more info see:
-
javadoc on
IssueStatusProvider -
and
org.yourorghere.xxx.XXXIssueStatusProvider
-
-
note that this feature is not mandatory
Scheduling
In the Tasks Dashboard it is possible to set user local scheduling information (e.g. what date the user plans to start working on the issue) and accordingly to categorise Issues given by that scheduling data (e.g list Issues scheduled for Today, This Week, etc.).
In case you want to provide local scheduling information for your Issues then you have to implement the IssueScheduleProvider interface and provide it via the BugtrackingSupport.createRepository(R, …) method call.
-
for more info see:
-
javadoc on
IssueScheduleProvider -
and
org.yourorghere.xxx.XXXIssueScheduleProvider
-
-
note that this feature is not mandatory
Priority
In case you want the Tasks Dashboard to show an priority icon next to an Issue in a Query result list then you have to implement the IssuePriorityProvider interface and provide it via the BugtrackingSupport.createRepository(R, …) method call. This icon can be determined either by a default icon for each given priority or by an icon provided directly by your implementation.
-
for more info see:
-
javadoc on
IssuePriorityProvider -
and
org.yourorghere.xxx.XXXIssuePriorityProvider
-
-
note that this feature is not mandatory
IDE integration
Issue references in text
Issue references can be hyperlinked in various places in the IDE - e.g. in source code comments or versioning commit messages.
The infrastructure parses for some default patters (e.g. Issue #12345), but in
case your remote repository comes with and untypical issue format, like for
example in case of JIRA, where the issue key is more complex ("Issue
#JIRAPOJECT-12345") you can provide your own IssueFinder implementation via
BugtrackingSupport.html.createRepository(R, …).
* for more info see javadoc on IssueFinder
Versioning Commits
On a versioning commit it is possible to select an issue and to add commit info and to close it eventually. All that has to be done to support this case is to implement IssueProvider.addComment(I, String, boolean).
Attaching Patches
When creating an patch via Versioning, it is possible to select an issue and to attach that patch to the issue. All that has to be done to support this case is to implement IssueProvider.attachFile(I, File, String, boolean).
