Scope of this document

This document aims to give guidance on the steps to follow to make changes to the existing code in gvSIG.

The contributions to the gvSIG code are mainly divided into three types:

1. Bugs. Bug fixes in the existing feature in gvSIG.
2. Improvement of a feature finishing. They are small improvements on existing feature in gvSIG.
3. New features. Contribution of new feature or modifications to existing code to develop new feature externally.

Since these three ways to contribute to the gvSIG code do not follow exactly the same channels and procedures, we will describe them separately.

A common theme to the forms to contribute to the gvSIG code is that you must surrender the authorship rights of the code contribution to the gvSIG project, as described in the documents What is the gvSIG CLA? and the Contributor License Agreement.

Exclusions

This document does not cover the requirements to be met by a project that provides a new plugin to gvSIG, for this we recommend you to consult the Official gvSIG Projects.

Bugs

If you have detected a bug in the application and have implemented to correct code to fix it, you can contribute it to the project so this is included in future versions of the application.

Not always all corrections will be accepted, sometimes for a lack of resources for inclusion in the review, others for disagreements over whether that implementation is adequate or not to correct the bug. Keep in mind that sometimes the correction of a small bug can give rise to unwanted effects in other parts of the application.

You must complete two tasks to make corrections and fix a bug:

• Firstly, the bug must be recorded in the gvSIG bug registry. gvSIG uses as a bug registry a tracker into the issues manager.

  To record the bug, it is advisable to register as a user of the forge, but if you do not register you still can record it.

  It is advisable to read the following documentation before loading a bug into the registry:

  • Before opening a bug
  • Tracker help document

  Once the bug is recorded, you could attach to it a patch with the source code and mark the field Has patch with a yes in the ticket.

  Tip

  It is very important to mark in the ticket since the Patch field is used by the development team to identify bugs that contribute code.

  The more information is provided in the ticket description about what your code does, more ease will be the task of the gvSIG person responsible for assessing the potential impact of its correction.

  If after evaluating the correction of the bug it is considered appropriate to place it in gvSIG, you will be advised through your ticket that the task has been performed.

  If this correction is considered to be problematic, you will also be informed through your ticket.

• On the other hand, the first time you must send us the document with the CLA surrendering your copyright on the code that you are giving to gvSIG. More information about this can be found in the Contributor License Agreement document.

Remember that the gvSIG project resources are limited and we can not always act immediately on the tickets received. We will try to respond as soon as possible.

Improvements in a feature finishing

We understand that sometimes there are a number of small changes that although they are not considered errors or bugs; it would be good that they are made on gvSIG. They can be as simple as changing the default option of a dropdown menus or the position of a menu option which it seems more logical somewhere else. They are not errors as such because the application works as designed. They are really small improvements in the existing feature.

The steps to follow to make such amendments to the code will be similar to those to be followed during the contribution of code for a bug, with the only exception that instead of using the gvSIG bug registry it should be used the New request for features .

New Features

When implementing a new feature in gvSIG it must be noted that, in general, new features are incorporated in the form of new plugins, so from the user point of view to add a new feature does not normally requires going through this process. The simplest way is to add the new feature to the unofficial gvSIG catalogue or to follow the procedures described in Official gvSIG Projects so it is included as an official project.

So ... When do we follow these procedures?

We should apply this procedure when in order to add our feature we have to modify parts of gvSIG, usually adding new extension points. The features from the user point of view will be kept in a separate plugin, and the necessary changes will be introduced in gvSIG so the plugin works as designed.

To provide sufficient code to gvSIG that would allow us to develop our plugin, we should request it through the tracker in New request for features. There we will register a ticket with a description of what we want to do, attaching the code as a patch or patches, with the implementation of it.

Before we develop our feature we should register the ticket, describing:

• What is the new feature to be added to gvSIG? It is not the feature that you want to implement in your plugin, but the one you need to add to gvSIG in order to develop your plugin.
• The motivation that led you to seek the introduction of this feature, what do you need it for?.
• How you plan to address it. A written account of how you will implement the feature, which modules need to be changed, why and what for?
• A written account of what parts of gvSIG you think may be affected by the proposed changes.

In the ticket you must mark in the Has patch field a yes so that development team clearly identifies the ticket as a request for feature that aims to provide code to gvSIG.

Note that:

• If your request involves changes in various parts of the application it may require the intervention of several developers for testing. This may slow down the process of inclusion of the amendments.
• If it is found that your request may result in loss compatibility or data with user projects, you should review your proposal, because it will not be accepted.
• An inadequate documentation of the new feature may cause not be understood by those responsible with its evaluation, with the consequent rejection. Provide all information you deem relevant to facilitate the task of evaluating your proposal.
• Your request can be considered irrelevant since there might be already other ways to do it. Consult with development lists before you begin making changes in gvSIG.

Once the petition is read, you can be requested to provide more information or to make some changes in some part of what it claims to do, and finally, to be asked for the code that implements it, as a patch or patches, to be attached to the ticket.

Remember, the first time you must send us the document with the CLA surrendering your copyright on the code that you are giving to gvSIG. More information about this can be found in the Contributor License Agreement document.