gvSIG official projects

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:

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:

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

Change log
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.

Project Dependencies

Version: 1.1

To specify the dependencies of your project you have to complete the template that exists for that purpose in ReST format.

For the template you have to use the document source code. This can be accessed from the icon at the bottom of the template (more information on how to access document sources can be found here).

If maven is being used as a build tool then the dependency report generated for the project site can be submitted, rather than following the format specified in the template.

The template describes the dependencies the project has at compile time, execution and implementation of tests, as well as transitive dependencies and where to find the libraries that are not already part of gvSIG.

To clarify, libraries that are part of gvSIG should be distinguished from those that are not. Libraries that are part of gvSIG are those that have been built from sources within any of the gvSIG projects. Libraries of other projects, whether used in any gvSIG project or not, are not considered part of gvSIG for the purposes of this template.

The following sections can be found in the template:

Change log
version description
1.1 Modified of the wording of the paragraph describing how to obtain the template

README.txt

versión:1.2

At the root of the SVN project there should be a README.txt file that guides people who download the project on how to compile, deploy, package and translate the project into other languages. There is a template in ReST format that can be used for this purpose.

For the template you have to use the document source code. This can be accessed from the icon at the bottom of the template (more information on how to access document sources can be found here).

The following sections can be found in the template:

Change log
version description
1.1 Modified the wording of the paragraph on how obtain the template.
1.1 Extended the packaging instructions to include the maintenance of the build number and the corresponding tags in SVN.
1.2 Modified the wording of the section on Compilation instructions to make it clearer what should be included.
1.2 Minor changes to the wording of the paragraph describing tags in the section on Packaging instructions.
1.2 Rewrote the paragraph on Version information; added links to the document that describes how to interpret the version number in gvSIG.
1.2 Added a note about the necessity of a policy for naming binaries.

Analysis documentation

Version: 1.1

Analysis documentation for basic level official projects.

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

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

It is advisable to follow certain conventions:

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:

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.

change log
version description
1.1 Added a link on how to insert images into the documentation.
1.1 Added the recommendation to contact the GVSIG architecture group before starting the documentation.

Interpreting the gvSIG version number

versión:1.0

The gvSIG version number consists of four numbers:

Note

Note: The adaptation of a plugin to a higher version of gvSIG must always include an increase in the plugin version number, either in the major, minor or revision number.

There should never be two distributions emerging from different sources with the same version number, even if only for internal use. Users should always be able to identify exactly which version they are working with as this is extremely important when reporting bugs.

Use the following format to indicate the version number to users:

<Major-number>.<Minor-number>.<revision-number> build <build-number>

Underscores, "_", can be used instead of points, but never dispense with one or the other to separate the different numbers that make up the version number.

Don't ever use:

These incorrect formats might lead to confusion when future versions are released.

change log
version description
   

Naming binaries for a gvSIG plugin

Version: 1.5

Before discussing file names for the distribution, the following information is required:

Once this information has been collected, the file naming criteria for the distribution can be reviewed.

The first criterion is that the entire file name must be in lower case.

The format to use for the name is as follows:

gvSIG-desktop-<gvsig-version>-<name>-<major-number>_<minor-number>_<revision-number>-<build-number>-<state>-<platform>.<zip|exe|bin>

Where:

Warning

The platform identifier "i586" is being evaluated and an alternative that better identifies the platform is being considered. While most identifiers currently distinguish between 32 bit and 64 bit architecture rather than between i586 or i686, we propose using x86 and x86_64.

For source distributions the format will be:

gvSIG-desktop-<gvsig-version>-<name>-<major-number>_<minor-number>_<revision-number>-<build-number>-<state>-src.zip

Finally, when distributing formatted versions of the documentation these should be in PDF format and should be named as follows:

gvSIG-desktop-<gvsig-version>-<name>-<major-number>_<minor-number>-man-v<man-version>-<lang-code>.pdf

Where:

For source distributions and documentation no distinction is made between platforms.

change log
version description
1.1 Added gvsig-version.
1.1 Added the status.
1.2 Corrected a formatting error. The location of the state was incorrect.
1.3 Added devel as an option for state.
1.4 Changed the literal gvSIG at the start of the file name to gvSIG-desktop and modified the platform support to all.
1.5 Substituted status with state and added a new state testing.