Scope of this document

This document covers the requirements to be fulfilled by a development project in order to become an official gvSIG project.

Exclusions

This document does not cover:

• The conditions a project must meet to be included in the official distribution of the gvSIG application.

  A project must be an official gvSIG project before it can be included in the official gvSIG distribution, but fulfilling this requirement is not automatically guaranteed.

• Modifications or contributions to existing gvSIG code.

  If you want to contribute code to an existing gvSIG project consult the document Contributions and patches to gvSIG code.

Levels of official development contributions to gvSIG

Before looking at these requirements, it should be noted that there are two official levels that a development can take:

• Basic level. This level integrates testing, user documentation (but the gvSIG project is not responsible for maintaining it), fixing of bugs, adding of new functionalities or adapting them to a new version.

  If it is decided to include a development in an official release and the new development does not compile, has a run-time failure or makes another extension fails, the contributor who created this extension will be informed and if the contributor does not devote resources to fix it, the development will be removed from that version.

  This level hardly covers restrictions on packaging, documentation and user testing. Moreover, it is not necessary to fulfil the rules or recommendations regarding design and implementation. So, the costs of maintaining the development for members who are working with gvSIG may be quite high.

• Full level. The contribution includes testing as well as user and development documentation. The gvSIG project may take charge of fixing some bugs and its adaptation to new versions that are released, depending on the resources the project has available at that time.

The main difference between the two levels is that one sets requirements related to packaging and distribution of a project, while the other focuses more on development issues (analysis, design, coding, documentation for developers...).

Requirements of an official gvSIG development

The requirements for each level should be considered to be cumulative, except when otherwise stated. This means that the requirements of the basic level must also be fulfilled at the full level.

Some requirements that a project must fulfil to become an official gvSIG project must be met at the start of the validation or certification process, while others may be fulfilled during the course of the process.

Starting the paperwork

If you are interested in your development becoming an official gvSIG project you may register a ticket or newsletter using the offical project collaboration request page in OSOR forge.

In the ticket enter a few paragraphs describing the functionality provided by your development, and also attach templates of the project sheet and project contacts. To complete the templates remember to do so from their source code. You can find more information on how to access document sources here.

We will then put you in contact with the appropriate person from the gvSIG project to lead the coordination of tasks required to formalize your development in gvSIG

Analysis documentation for basic level official projects.

When providing analysis documentation for a basic level official project the following sections have to be covered:

• Introduction.

  Provide a document entitled "Introduction", containing a brief description of the project and indicating the aims covered and not covered.

  This introduction should consist of three or four paragraphs describing briefly the objectives to be covered.

• Context.

  Provide a block diagram showing the components of the project in relation to gvSIG and a model of its layers, user interface/gvSIG application, geo/fmap logic, library support.

• Overview.

  Present an overview of the major components of the project and the relationships between them. Focus mainly on the components making up the project's API, ignoring components specific to the implementation. Also state the relationship between these components and those of gvSIG.

  Normally included are:

  • A few paragraphs containing a brief text description of the model and its components.
  • A diagram that shows graphically the relationships between the components, clearly distinguishing the project components from those components already existing in gvSIG.
  • A brief description of each of the components appearing in the diagram. A paragraph is usually sufficient for each of the artefacts in the model.
  • If the diagram is very complex, functionalities should be grouped into more general components, so that complex components in the diagram can be decomposed into others, leading to a greater understanding of the model. In this case, include a list of the components operating in the model.

• Detailed view of components.

  For each of the components specified in the overview and that can be used, include a description and a diagram, similar to that in the Overview but for the component in question.

Provide a document for each section, presenting as much detail as is required for the project.

It is advisable to follow certain conventions:

• Normally attributes or methods aren't specified for the different components in the diagrams since this documentation is analysis documentation and is not about design. Inclusion of design features at this level would obscure the understanding of the model.
• Diagrams are read from top to bottom and from left to right. With this layout, for example, inheritance can be indicated with super-classes at the top and sub-classes at the bottom, or in the case of one to many relationships, the master entity is shown at the top and the details are shown below or to the right.
• Design diagrams so that they are higher than they are wide (i.e. in portrait layout), and try to have their components at the top and not across the diagram. This is so that if the documentation is printed there will not be much loss in quality if the diagrams are scaled to fit an A4 page.
• Don't scale the diagrams for inclusion in the documentation. If they are too large they will be split into a series of diagrams.
• Try to cross lines as little as possible and don't overlap them with other lines.
• Try to use different entity background colours for grouping sets of functional entities, and provide a legend for identifying the functions.
• Use stereotypes to identify interfaces and abstract classes.
• If an analysis of the implementation's javadocs accompanies the documentation, then a link to the javadoc should be used when referencing one of these entities.
• When inserting diagrams into the documentation, use PNG format with a reduced colour palette (16 or 32 colour palette) in order to reduce the size of the document when accessing it via the web. For more information on this go to inserting images into documentation.

In the event of the project providing functionality that can be used by other projects in the form of a library, it is advisable to submit documentation showing how to use these features.

It is preferable to use the ReST format for preparing the documentation, although basic level projects submitted in HTML format will also be permitted.

Analysis documentation similar to that required here can be seen at:

• DAL analysis documentation.

It may be helpful to read the Documentation guide before starting to write the analysis documentation.

Before starting the analysis documentation it is also advisable to contact a member of the gvSIG architecture group to discuss what needs to be done.

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.

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

Organizations

Individual contributors

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:

Rights and Obligations

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

Activities restrictions

Next table shows what is not allowed to every role.

Role metrics

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

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

Use cases and work flows overview

Scope

This document specifies the procedure to add a new package to the package repository of gvSIG project whether a package is hosted on servers project or not.

Exclusions

This document does not cover:

• What must a for inclusion in the Distribution gvSIG enforcement officer. Package supplied will be included in the web repository of packages gvSIG it need not be distributed with the binaries the official release.

• What must a to be considered a project gvSIG official. You can find documentation on the document gvSIG official projects

• Modifications or contributions to existing code in gvSIG.

  If you want to contribute code to an existing project in gvSIG see Contributions and patches to the gvSIG code.

• Como solicitar al proyecto que albergue nuestro paquete. El responsable y creador del paquete deberá alojarlo en un servidor publico con acceso a el por http, entregando al proyecto solo el archivo gvspki con los metadatos del paquete.

Requirements

To add a package to the package repository of gvSIG must create the installation package and deliver the file ". gvspki" generated. You can find documentation on how to build the package for a gvSIG plugin in the document Generación desde el plugin de instalación . Ask on the development list if you have doubts.

The package must be met:

• To be released under GPL 2 or compatible license.
• You can not replace files out of plugin folder being installed. If it is necessary to be communicated and assess this need.
• Information should be provided on the code and version package.
• You must provide the name and description of the package in English.
• You must provide the name of the owner.
• You must supply the URL that allows access to the source from which it was generated.
• They must be correctly filled all the packet data package.info the file.
• It will be advisable to follow the package name nomenclature generated by the plugin package tool provided in gvSIG facilities. If not, be justified.

In addition to these requirements is highly recommended:

• The existence of associated user documentation for functionality provided by the package. This documentation must be freed with Creative Commons .
• That there is a tracker to report bugs in the creators of this.

Expclusion a package repository

This section describes why a package may not be included in the package repository gvSIG or eliminated if already formed part of it.

• Update the contents of a package without increasing the number of version or build.

  Each time you change the plugin, you must generate a new package reflecting that at least the increasing number of build, sending back to the project gvspki the file. If detected from the project has changed the package keeping the same version number and build, will retire on package repository.

• If from the gvSIG team are consulted through the comments to the ticket which apply for registration packet that are not answered, you can remove the package from the repository or not enter the if you have not been done.

• If it is found that the use of the functionality provided by the package can cause loss of data by the user of these, this may be removed from the package repository.

How to start the paperwork

If you have already created the installation package associated with their plugin (. gvspkg and. gvspki) may request inclusion in the repository gvSIG package by the trac ticket Addons repository requests . To this should be registered as a user of the gvSIG_platform.

You must add the fields filled out a ticket:

• Add-on name must indicate the name of the package on which want to make the request.
• Add-on code. In case it is a new packet and not in a list of packages add-on name, you must indicate here Package code to add.
• Add-on operation requested. You must indicate the type of operation that applying.
• Subject short description of what you want done.
• Description. Indicate here the url to the file gvspki of your package. You enter the information that it considers may be of interest to facilitate the acceptance of the package, as well as inclusion in the package repository.

Make sure the download-url entry package.info package that provides is correct and accessible from the internet, otherwise the package may not be included in the package repository gvSIG.

Do not assign the ticket to anyone and leave the other fields with the values defects have a ticket.

Note that since the project if you have questions about has made the request was answered on the same ticket by adding comment.