netbeans.apache.org/src/content/wiki/BugtrackingCookbook.adoc

// 
//     Licensed to the Apache Software Foundation (ASF) under one
//     or more contributor license agreements.  See the NOTICE file
//     distributed with this work for additional information
//     regarding copyright ownership.  The ASF licenses this file
//     to you under the Apache License, Version 2.0 (the
//     "License"); you may not use this file except in compliance
//     with the License.  You may obtain a copy of the License at
// 
//       http://www.apache.org/licenses/LICENSE-2.0
// 
//     Unless required by applicable law or agreed to in writing,
//     software distributed under the License is distributed on an
//     "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
//     KIND, either express or implied.  See the License for the
//     specific language governing permissions and limitations
//     under the License.
//


= Bugtracking Plugin Cookbook
:jbake-type: wiki
:jbake-tags: wiki, devfaq, needsreview
:markup-in-source: verbatim,quotes,macros
:jbake-status: published
:syntax: true
:description: Bugtracking Plugin Cookbook
:icons: font
:source-highlighter: pygments
:toc: left
:toc-title:
:experimental:


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]]
== Setup


[[Working_Environment]]
=== Working Environment

* Clone and build the main NetBeans repository at link:http://github.com/apache/netbeans[]

*Download the Bugtracking skeleton/demo Module*

* Download the project skeleton - link: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]]
== How To

Please note that until not mentioned otherwise, all classes are from the
link:https://bits.netbeans.org/dev/javadoc/org-netbeans-modules-bugtracking/org/netbeans/modules/bugtracking/spi/package-summary.html[org.netbeans.modules.bugtracking.spi]
package.


[[Register_a_Connector]]
=== 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
[source,java,subs="{markup-in-source}"]
----
@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]]
=== Handle Repositories


[[Create]]
==== 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 `link:https://bits.netbeans.org/dev/javadoc/org-netbeans-modules-bugtracking/org/netbeans/modules/bugtracking/spi/BugtrackingConnector.html#createRepository(org.netbeans.modules.bugtracking.spi.RepositoryInfo)[BugtrackingConnector.createRepository(RepositoryInfo)]`


[[Setup_2]]
==== Setup

use the link:https://bits.netbeans.org/dev/javadoc/org-netbeans-modules-bugtracking/org/netbeans/modules/bugtracking/spi/BugtrackingSupport.html#createRepository(R,%20org.netbeans.modules.bugtracking.spi.IssueStatusProvider,%20org.netbeans.modules.bugtracking.spi.IssueScheduleProvider,%20org.netbeans.modules.bugtracking.spi.IssuePriorityProvider,%20org.netbeans.modules.bugtracking.spi.IssueFinder)[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]]
=== Handle Queries


[[Creating]]
==== 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]]
==== Executing

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

* see the javadoc on:
** link:https://bits.netbeans.org/dev/javadoc/org-netbeans-modules-bugtracking/org/netbeans/modules/bugtracking/spi/QueryProvider.html#setIssueContainer(Q,%20org.netbeans.modules.bugtracking.spi.QueryProvider.IssueContainer)[`QueryProvider.setIssueContainer(Q, IssueContainer)`]
** `QueryProvider|refresh(Q)`
** `IssueContainer`

* see also how Queries are handled in the attached sample - `org.yourorghere.xxx.XXXRepositoryProvider.createQuery()`.


[[Handle_Issues]]
=== Handle Issues


[[Creating_2]]
==== 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]]
==== 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:
** link:https://bits.netbeans.org/dev/javadoc/org-netbeans-modules-bugtracking/org/netbeans/modules/bugtracking/spi/RepositoryProvider.html#getIssues(R,%20java.lang.String...)[`RepositoryProvider.getIssues(R, String)`]
** link:https://bits.netbeans.org/dev/javadoc/org-netbeans-modules-bugtracking/org/netbeans/modules/bugtracking/spi/RepositoryProvider.html#simpleSearch(R,%20java.lang.String)[`RepositoryProvider.simpleSearch(R, String)`]


[[Status_-_local_and_remote_changes]]
==== 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 `link:https://bits.netbeans.org/dev/javadoc/org-netbeans-modules-bugtracking/org/netbeans/modules/bugtracking/spi/BugtrackingSupport.html#createRepository(R,%20org.netbeans.modules.bugtracking.spi.IssueStatusProvider,%20org.netbeans.modules.bugtracking.spi.IssueScheduleProvider,%20org.netbeans.modules.bugtracking.spi.IssuePriorityProvider,%20org.netbeans.modules.bugtracking.spi.IssueFinder)[BugtrackingSupport.createRepository(R, ...)]` method call. 

* for more info see:
** javadoc on `IssueStatusProvider`
** and `org.yourorghere.xxx.XXXIssueStatusProvider`
* xref:TaskDashboardDesignSpec.adoc[The Tasks Dashboard UI spec]
* note that this feature is not mandatory


[[Scheduling]]
==== 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 `link:https://bits.netbeans.org/dev/javadoc/org-netbeans-modules-bugtracking/org/netbeans/modules/bugtracking/spi/BugtrackingSupport.html#createRepository(R,%20org.netbeans.modules.bugtracking.spi.IssueStatusProvider,%20org.netbeans.modules.bugtracking.spi.IssueScheduleProvider,%20org.netbeans.modules.bugtracking.spi.IssuePriorityProvider,%20org.netbeans.modules.bugtracking.spi.IssueFinder)[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]]
==== 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 `link:https://bits.netbeans.org/dev/javadoc/org-netbeans-modules-bugtracking/org/netbeans/modules/bugtracking/spi/BugtrackingSupport.html#createRepository(R,%20org.netbeans.modules.bugtracking.spi.IssueStatusProvider,%20org.netbeans.modules.bugtracking.spi.IssueScheduleProvider,%20org.netbeans.modules.bugtracking.spi.IssuePriorityProvider,%20org.netbeans.modules.bugtracking.spi.IssueFinder)[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]]
=== IDE integration


[[Issue_references_in_text]]
==== 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
link:https://bits.netbeans.org/dev/javadoc/org-netbeans-modules-bugtracking/org/netbeans/modules/bugtracking/spi/BugtrackingSupport.html#createRepository(R,%20org.netbeans.modules.bugtracking.spi.IssueStatusProvider,%20org.netbeans.modules.bugtracking.spi.IssueScheduleProvider,%20org.netbeans.modules.bugtracking.spi.IssuePriorityProvider,%20org.netbeans.modules.bugtracking.spi.IssueFinder)[`BugtrackingSupport.html.createRepository(R, ...)`].
* for more info see javadoc on `IssueFinder`


[[Versioning_Commits]]
==== 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 `link:https://bits.netbeans.org/dev/javadoc/org-netbeans-modules-bugtracking/org/netbeans/modules/bugtracking/spi/IssueProvider.html#addComment(I,%20java.lang.String,%20boolean)[IssueProvider.addComment(I, String, boolean)]`.


[[Attaching_Patches]]
==== 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 `link:https://bits.netbeans.org/dev/javadoc/org-netbeans-modules-bugtracking/org/netbeans/modules/bugtracking/spi/IssueProvider.html#attachFile(I,%20java.io.File,%20java.lang.String,%20boolean)[IssueProvider.attachFile(I, File, String, boolean)]`.


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

This page was exported from link:http://wiki.netbeans.org/BugtrackingCookbook[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.
====