:Version: 1.11

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.

Basic level
-----------

Requirements to begin the certification process:

* A contact person with the authority to take decisions about all matters relating to the development shall be provided.

* The development license must be compatible with `GPL v2`_ or later and any other library that is incompatible with this license must not be used.

  To get recognition as an official project, the documentation submitted with the development project must carry a `GPL v2`_ or later compatible license, or a `Creative Commons`_ license that allows commercial use of this document as long as any modifications to the documentation carry the same redistribution restrictions as the original documentation.

* A report on the library or extension dependencies must be submitted and must indicate the libraries and versions on which they depend. This report must include the dependencies on other gvSIG extensions and libraries and identify these dependencies appropriately.

  Likewise the dependencies on native libraries should also be indicated.

  This document must be kept updated throughout the life of the project.

  If the project uses maven as a means of building units, it is sufficient to deliver the report on the maven site *dependencies* generated with *mvn site*. If maven is not being used then use the `Project Dependencies`_ template.

* Each development review must be identified unambiguously. In general terms, a library must contain a version number in the name of the *jar*, while an extension must have a *build* name unique to that extension. Two different binaries may not have the same name and version number.

- The sources from which the binaries are generated and the tools necessary to generate them must be available for public access.

  gvSIG is currently using OSOR_ forge as space for the project, space which includes a SVN repository for public access in read mode, *trackers* for bugs and tasks, and so on. If the project does not have the infrastructure necessary for its management, gvSIG can coordinate the creation of a new project for the collaborator.

- When the sources are downloaded from the source code repository, a `README.txt`_ file must exist in the root of the project. This file must include the instructions to compile, deploy and build the installable.

The requirements which must be fulfilled during the certification process are:

* There must be some `analysis documentation`_ that describes the development.

  It is not necessary to describe the design level, but it is essential that the analysis level is described. It includes the description of the main modules and their relation to other gvSIG modules.

* A repeatable and documented way to *create installable packages* for the gvSIG extension shall be provided. It's best to use the procedure used by the current gvSIG version for packaging extensions.

* It must be able to be internationalized using the necessary gvSIG libraries. At the very minimum, it must be submitted in **English**.

* A user manual, composed in ReST format and following the rules for writing proper documentation currently in force in gvSIG (`Documentation Guide`_), should be provided. The user documentation that must be submitted includes:

  * User manual
  * Installation manual
  * Credits that must appear in the gvSIG manual when the documentation associated with that project is included in the manual.

- With respect to **testing**, the requirements are:

  1. A Test Plan (TP) that covers the new features entirely, at least to the level of test case, must be designed. Both functional and persistence tests should be taken into account. The TP will be loaded into the project's test case management software and this software will be used to run the TP for the first time. It's also possible to request the execution of a test campaign, including regression and persistence tests, which the Department of Software Testing will purpose-design based on the analysis of the impact of the new developments on the rest of the application. Moreover, it is highly advisable to open a new bug ticket for each bug found when running the tests, indicating the actual step in which the bug was detected.

  2. A stabilization phase is necessary in which a developers team and a *testers* team will work intensively and in a coordinated way to fix bugs, both within the new functionalities and on bugs that appear in the other parts of the application owing to the integration of these functionalities.
  
  3. When an official development don't pass the test plan for a gvSIG version, that development will not be an official project for that gvSIG version.
  
  4. A bug and new features management system must be available for public access and any anonymous user must be able to register tickets.
  
     If the project do not have this kind of management system, it would be able to use the bug and new features management system that OSOR has. This management system allows the project to save the sources, download the binaries and manage its tickets. If it is not possible, as a last resort, all these elements would be able to be included in the bug management system of the gvSIG application.

  `See the general outline of the testing procedures`_

* There should be a gvSIG plugin for functionality, or groups of related functionalities, from the user standpoint, with an eclipse project for each of the plugins.

* There should be a clear and understandable policy for maintaining the project's version number.

* There should be a clear and understandable policy for naming the files of the project's distribution.

* The installation of a plugin in gvSIG must not overwrite any libraries included in the official release of gvSIG.

There are two templates in ReST_ format that must be completed and submitted with the basic project data, the `project sheet`_ and the `project contacts`_.

Full level
----------

It is not necessary to fulfil the requirements of this level until the end of the certification process.

* Maven_ must be used as build environment for the extension or library, using the gvSIG project structure, including the gvSIG criteria for naming packages, artefacts and libraries.
  
  Moreover, the pom.xml files must include all the necessary data, for example:
  
  * Description of the project
  * Links to the code repository
  * Links to the mailing lists
  * Developers
  * Etc.

* There must be complete API documentation through the *javadocs*, and also a mechanism to deploy them at the site where they are in the gvSIG project. The API documentation shall be written in **English**.

* Automated tests covering the extension API or library must be made using JUnit_ tests.

* The logic and the user interface must be strictly separated.

* There must be a strict separation between the API and the implementation, generating separate libraries for the API and the implementation, both for the **logic** and for the **user interface**.

* Existing `coding standards`_ should be followed in the project.

* A *guide for developers* must be drawn up to document how to use the functionalities. This guide should preferably be written in **English**.

* The development documentation must be generated in ReST_ format.

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

.. _ReST: http://docutils.sourceforge.net/rst.html
.. _maven: http://maven.apache.org/
.. _JUnit: http://www.junit.org/
.. _OSOR: http://forge.osor.eu
.. _GPL v2: http://www.gnu.org/licenses/old-licenses/gpl-2.0.html

.. _`coding standards` : /web/reference_catalog/lookupObject?uuid=84a57351f2a4d525623e6dcde182d609
.. _`project sheet` : /web/reference_catalog/lookupObject?uuid=075e729afb778e8f8018fc81e6b831e5/templates/project_sheet
.. _`project contacts` : /web/reference_catalog/lookupObject?uuid=aa581c88ee81bd6603ae740aa87586a1
.. _`See the general outline of the testing procedures`: /web/reference_catalog/lookupObject?uuid=bbd435f4caaa8fe0d0b28f223ed1e852
.. _`Documentation Guide`: /web/reference_catalog/lookupObject?uuid=55653a0583dd9a9cd5571ca4203959a3
.. _`analysis documentation` : /web/reference_catalog/lookupObject?uuid=fa5c5f964fda12699aa3393ea0d87d62
.. _`README.txt` : /web/reference_catalog/lookupObject?uuid=ea7c9855b5a1c3690eb44b25afc3c8d6
.. _`Project Dependencies` : /web/reference_catalog/lookupObject?uuid=3b996fde2cd63e91ab24b47d62a06e6e
.. _`more information on how to access document sources here` : /web/reference_catalog/lookupObject?uuid=529fc89cb1d4e7677ed4f3e2a16af644
.. _`offical project collaboration request` : http://forge.osor.eu/tracker/?func=add&group_id=89&atid=899
.. _`Contributions and patches to gvSIG code` : /web/reference_catalog/lookupObject?uuid=b49f9501f8f5740cb3d3d1a5e1b53778
.. _`package.info (Template)` : /web/reference_catalog/lookupObject?uuid=1c2c62ef24ca854671142ef2b774790a

.. _`Creative Commons` : http://creativecommons.org/

.. list-table:: Change log
   :header-rows: 1

   * - Version
     - Description

   * - 1.1
     - Added a link to the *dependency report* template.

   * - 1.2
     - Replaced the link to the dependency report template by a link to a document that describes how to complete the dependency report template and where to obtain it.

   * - 1.2
     - Added a link to an explanatory document about how to complete the README.txt file to be included with the source code and where to get this file template.

   * - 1.2
     - Added a link to an explanatory document to be submitted as the analysis documentation of the basic level, as well as a link to an example.

   * - 1.2
     - Added links to the *project sheets* and *contacts* templates.

   * - 1.2
     - Corrected reference to *basic* and *advanced* levels. At one point they where referenced as *minimum* and *high*.

   * - 1.3
     - Reworked the first paragraph of the document to better express what an official gvSIG project is.

   * - 1.4
     - Added a requirement that different functions should go on different plugins.

   * - 1.5
     - Added a requirement about the policy related to the version number.

   * - 1.5
     - Added a policy requirement related to the naming of the distribution files.

   * - 1.5
     - Replaced a requirement about following the naming rules for classes by one for following coding conventions.

   * - 1.6
     - Added a new section "*Starting the paperwork*".

   * - 1.6
     - Corrected spelling and syntax.

   * - 1.7
     - Split the *scope* section into two, *scope* and *exclusions*, and added a link to `Contributions and patches to gvSIG code`_.

   * - 1.8
     - You may not overwrite gvSIG libraries

   * - 1.9
     - Added licence conditions on the submitted documentation.
     
   * - 1.10
     - Added the point 3 of the testing requirements (If an official development don't pass the test plan for a gvSIG version, that development will not be an official project for that version).
     
   * - 1.10
     - Added the point 4 of the testing requirements (Each project must have a bug and new features management system and it must be available for public access)
     
   * - 1.10
     - Description of the different documents that are part of the user documentation that must be submitted: user manual, installation manual and credits.
     
   * - 1.11
     - Added paragraph about the pom.xml file must be properly completed.