Bugtracking Plugin Cookbook

Apache NetBeans Wiki Index

Note: These pages are being reviewed.

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

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

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

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

  • The Tasks Dashboard UI spec

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

The content in this page was kindly donated by Oracle Corp. to the Apache Software Foundation.

This page was exported from http://wiki.netbeans.org/BugtrackingCookbook , that was last modified by NetBeans user Tstupka on 2014-01-07T13:43:11Z.

This document was automatically converted to the AsciiDoc format on 2020-03-12, and needs to be reviewed.