BugtrackingCookbook

Revision as of 17:57, 25 November 2013 by Tpavek (Talk | contribs)

Contents

Bugtracking Plugin Cookbook

WORK IN PROGRESS

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

Download the Bugtracking skeleton/demo Module

  • Download the project skeleton - File: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.bugracking.spi package.

Register a Connector

  • Create an implementation of BugtrackingConnector and register it via the BugtrackingConnector.Registration annotation.
  • see also org.yourorghere.xxx.XXXConnector in 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 RepositoryController to 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(...) callback methods 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.XXXConnector in 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().

Executing

Invoked by user action from the Tasks Dashboard or in automatically by a customisable time interval.

  • see the javadoc on:
    • QueryProvider.refresh(IssueContainer)
    • IssueContainer
  • see also how Queries are handled in the attached sample - org.yourorghere.xxx.XXXRepositoryProvider.createQuery().

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(IssueContainer)
    • IssueContainer
  • by Issue ID or text criteria - see the javadoc on:
    • RepositoryProvider.getIssues()
    • RepositoryProvider.simpleSearch()

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(...) method call.

  • for more info see:
  • 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(...) 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(...) 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.createRepository(...).

  • 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().

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().

Not logged in. Log in, Register

By use of this website, you agree to the NetBeans Policies and Terms of Use. © 2012, Oracle Corporation and/or its affiliates. Sponsored by Oracle logo