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.

Change registry

version	Description
1.1	(translation pending) Añadidos los valores a los que deben dejarse los campos state y resolution de un ticket.
1.2	Update references from OSOR to the https://devel.gvsig.org/redmine site

References

Similar pages of other free software projects:

• OpenLayers HowTo Contribute: http://trac.openlayers.org/wiki/HowToContribute
• OpenBravo legal aspects: http://wiki.openbravo.com/wiki/Contributor%27s_Guide#Legal_aspects
• Nuxeo contributors page: http://www.nuxeo.org/xwiki/bin/view/Main/ContributionSpace

Change log

Version	Description
1.0	First published version of the document

Organizations

Organization name	Date received
LSI (UJI)	2011/06/01
ai2 (UPV)	2011/06/01
DISID	2012/03/28
Laboratorio de Bases de Datos. Universidade da Coruña	2012/04/24
Software Colaborativo	TBD
Prodevelop	TBD
CartoLab	TBD
iCarto	TBD

Individual contributors

Name	Date received
Fernando Pinotti (UPV)	2011/09/04
Fernando González	2012/03/26
Antonio Falciano	2012/08/02
César Martínez Izquierdo	2012/09/28

Introduction

This document integrates the description of the different contributor profiles that can participate on the development of gvSIG, presenting at the end on a pretty schematic way the main workflows available when contributing software code to gvSIG.

Described profiles are:

• External developer
• Project developer
• Maintainer
• Reviewer
• Tester
• Software architecture support

Profiles

gvSIG code point of view of every role

Every role related with the development and interaction with the source code of gvSIG has a different point of view of the project. It can be of high level or in-depth. For example, a high level perspective will see a gvSIG product as a set of subsystems that interact trough a group of well defined interfaces. A low level point of view is focused on a subsystem implementation. With this definition in mind, next table shows the roles points of view on the gvSIG code:

Role	Visibility
Software architecture support	They have a general point of view of the application, looking at it as a whole.
Maintainer	He looks for his module code, as well as any API his module interacts
Reviewer	He looks at interfaces or even methods. He evaluates the impact of changes on the semantics, interfaces, method signatures or their context.

Rights and Obligations

The following are the duties and rights of each of the profiles:

Role	Rights and Obligations
External developer	To open new tickets attaching code patches. To know about Contributions and patches to the gvSIG code recommendations To know about coding conventions used by the project When your contribution modifies any API, the corresponding javadocs will be updated accordingly If your contribution breaks any existing automated test, they will be updated accordingly If the package maintainer requests it, you will provide additional or updated tests in order to cover the new behaviour contributed If your contribution changes the Graphical User Interface, the maintainer could ask for an update on the user documentation to accept the patch
Project developer	Create new tickets attaching patches or references to changes at source code repository Commit code to the source code repository (always with a ticket assigned to the commit) To know about Contributions and patches to the gvSIG code recommendations. To know about coding conventions used by the project. To know when is allowed to commit changes to the source code repository and when is not. The project managers will notify about this timing on mailing lists. To know well the development documentation. Any uploaded code will have updated also the javadocs. If your contribution breaks any existing automated test, they will be updated accordingly. Likewise, you will provide additional or updated tests in order to cover the new behaviour contributed. Provide to the testers all the information they could need to validate the change, as well as update the test cases (nowadays this last requirement is not possible by technical impediments, but it will be needed as soon as they are solved). If the package maintainer requests it, you will provide additional or updated tests in order to cover the new behaviour contributed If your contribution changes the Graphical User Interface, the maintainer could ask for an update on the user documentation to accept the patch.
Maintainer	Create new tickets attaching patches or references to changes at source code repository Commit code to the source code repository Assign tickets to reviewers Ask to software architecture team about the impact of a code change Assign tickets to developers to commit changes to the source code repository or to ask for more information to the community contributor. That doesn't avoids revision, it's just to speed up the process if it has to be done. Auto-assign a tickets with an attached patch and commit it or ask for any change to the contributor. This doesn't remove revision, it just speeds up the process if it has to be done. To assure that tickets have all the information needed by testers to validate the change, and if this is not true, to claim for it to the developer that contributed the change. As a maintainer is also a project developer, (s)he will have the same rights and obligations besides their specific ones. To assure that tickets received on his subsystem are treated accordingly (assign tickets to reviewers or to developers) To reject tickets without updated javadocs if they are needed (always asking first to the developer if the first time they weren't provided) To reject tickets that broke any automated test existing at the project of the contributed code (always asking first to the developer if the first time they weren't provided) To reject tickets with code that doesn't follow the project code conventions (always asking first to the developer if the first time they weren't followed) To reject tickets that don't specify how a tester can verify the change solves the incorrect behaviour (always asking first to the developer if the first time it wasn't provided) Maintain the configuration, information and documentation about the building process of the subsystem. If maven is used, assure that besides compilation, deploy mechanisms are working, site generation, etc. as well as the information stored at pom.xml file: developers, description, etc. Be responsible on the application on corrections and new functionalities between different live versions of gvSIG, at least against superior versions. It's not necessary to apply or ask for changes on all versions, but at least (s)he has to create the tickets in order to not lose the changes. For example, there is a bug with a patch for gvSIG Desktop 1.x, it should be applied or at least to create the corresponding ticket for 2.x. He is in charge to maintain a high cohesion and loose coupling in the subsystem he maintains He is in charge of the source code version control he maintains He has to coordinate changes to be ready for next releases of the application He has to be aware of the dependencies of the subsystem he maintains He has to maintain the user documentation updated, asking to the ticket creator for additional information or needed screenshots He has to know about the project procedures associated with the user documentation generation He has to know about the procedures associated with the process of releasing a new version of the project, binaries naming, where they have to be placed, how to update libraries,....
Reviewer	Create new tickets attaching patches or references to changes at source code repository Commit code to the source code repository Accept or reject tickets with code contributions Ask to software architecture team about the impact of a code change when knowledge of gvSIG as a complete systems are needed. Ask the maintainer when the code contribution is related with a subsystem with an assigned maintainer. Review assigned tickets Report on the ticket any detected problem on the code Reject any ticket that broke existing automated tests on the project where the changes will be applied. Reject any ticket without the proper documentation (javadocs) on the code changed or contributed. Reject any ticket with code that doesn't follow the gvSIG code guidelines Reject any ticket with code but without instructions for the testing team about how to verify that code works as expected Fix small problems that the code contribution can arise, annotating that on the same ticket If the ticket is a patch an the change is accepted, commit it to the source code repository Inform the maintainer when (s)he can not attend an allocated ticket for review
Tester	To mark a ticket as a non resolved To mark a ticket as a non valid To mark a ticket a validated Review assigned tickets by the testing manager and mark them as validated, non solved or waiting for more information
Software architecture support	Assign tickets to be reviewed. Assign tickets to the reviewers to be reviewed on a given version stabilisation period, on those modules where there is no assigned maintainer. Attend developers help requests

Activities restrictions

Next table shows what is not allowed to every role.

Role	Restricitons
External developer	To commit code directly to the source repository To approve a ticket with a patch To auto-assign a ticket To validate a ticket
Project developer	To approve a ticket with a patch or code contribution To assign tickets To validate tickets
Maintainer	Review his own patches or code contributions
Reviewer	When accepting code, to take decisions about functionality Review their own tickets Commit code from a ticket that has not be assigned to him by a maintainer or the architecture team

Role metrics

Next table shows the different metrics to take in account to obtain a role.

Role	To obtain a role
Project developer	Provide at least three code patches Participate on at least two gvSIG product revisions To exists at least two reviewers, maintainers or software architecture team members supporting the candidate, specially those reviewers that had worked on candidate contributions.
Maintainer	Participate as a project developer on at least the complete period between two gvSIG revisions. Participate actively on the wanted module, at least with 6 (six) code patches. To exists at least one reviewer, maintainer or software architecture team member supporting the candidate, specially those reviewers that had worked on candidate contributions.
Reviewer	Participate as a project developer on at least the complete period between two gvSIG revisions. To exist at least one reviewer, maintainer or software architecture team member supporting the candidate, specially those reviewers that had worked on candidate contributions.

This table shows some considerations to be taken in account when losing a role:

Role	To lose a role
Project developer	Provide at least four consecutive code patches rejected after their revision by a maintainer or reviewer Inadvertently repeated contributions that cause other errors in the application Two years of no participation If there is a clear dissociation with the project
Maintainer	Provide at least four consecutive code patches rejected after their revision by a reviewer or a software architecture team member Two years of no participation If there is a clear dissociation with the project Four or more contributions to a module of an specific version, without applying or creating a new ticket for the superior version
Reviewer	Provide at least four consecutive code revisions where the software architecture team considers that the API syntax or semantics has been altered, affecting the behaviour of any other part of the application Two years of no participation If there is a clear dissociation with the project If there is a neglect of their duties clearly and repeatedly

Use cases and work flows overview