Document Actions
gvSIG official projects
- gvSIG official projects
- Project Dependencies
- README.txt
- Analysis documentation
- Interpreting the gvSIG version number
- Naming binaries for a gvSIG plugin
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:
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:
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.
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.
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.
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.
- 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
| 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:
Project Dependencies
When specifying dependencies, these should be dependencies on other libraries. This includes both libraries that are already part of gvSIG, as well as new libraries that the project needs.
Other projects in the eclipse workspace should not be indicated as dependencies. If this does occur, an indication must be given of how to compile the library dependencies generated by these projects.
Compile
This is where the compile-time dependencies of the project are specified.
Runtime
The runtime dependencies of the project are specified here.
Test
Here the project dependencies for executing the project tests are specified.
For gvSIG projects prior to version 2.0.0, and for those that don't use maven as a build mechanism, if you are not sure which libraries are required then this should be indicated in all three sections. However, whenever the libraries are known they should be correctly specified.
Dependency Tree
In this section the relationships between the various libraries in the project are specified. This is a view, in the form of a tree, of the each of the transitive dependencies in the project.
For the dependencies on libraries that are already part of gvSIG it is not necessary to specify their transitive dependencies, as is mandatory for all other libraries in the project.
Licenses
In this section list the different licences of libraries that are used by the project but which are not part of gvSIG.
We will have an entry for this licence, and the various libraries that ship with it.
Don't include libraries that already form part of gvSIG.
If there are libraries for which the licence is not known, list the licence entry as unknown, bearing in mind that this might result in the project not being accepted as an official gvSIG project.
Dependency Repository Locations
In this section indicate the location of the official repository of those libraries that are not of gvSIG. This is the location from where the version of the library used by the project can be downloaded.
If maven is being used as a development tool, indicate one of the official maven repositories from which the library can be downloaded.
| 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:
Introduction
Include a list of the different sections that can be found in this file.
Version information
Specify the following:
- Files that must be updated every time the version number of the project needs to be updated.
- The operations that must be performed to update the version number.
- If the version number format or update policy of gvSIG is not followed, the format being used should be described.
It is recommended that you read the document Interpretation of the gvSIG version number.
Compilation instructions
You should include:
- Instructions on how to configure the eclipse workspace
- Instructions for compiling the project
- Instructions that allow a developer to deploy it as a framework for a gvSIG plugin.
Remember to specify whether to download and set up a workspace with gvSIG, or if the extension must be compiled as a gvSIG binary.
Packaging instructions
Here you should include instructions on how to package the project, both as a separate extension, and in a gvSIG installation.
The packaging instructions should include both the packaging process itself, such as maintaining a unique version number, and the updating of the corresponding files in the SVN in order to reflect the increase in version number (where appropriate).
There should also be instructions for generating a tag in the version control system for the sources corresponding to this version number, detailing the naming policy to use for naming the tag.
You must follow a well-defined policy for the name given to the binary distribution. It is essential that the binary name specifies:
- The project.
- The version.
- The platform.
If you follow a naming policy for the binary distribution that differs from that of gvSIG then this must be indicated in this section. You can view the gvSIG naming policy in the document Binary names for a gvSIG plugin.
Notes on internationalization
This contains the following subsections:
Location of the translation strings
Specify the location of the translation strings used by the project, as well as the languages that are available.
What should be done to include a new language
Indicate what needs to done to add a new language to the strings that already exist in the project.
| 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:
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:
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.
| 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:
- Major number. This is increased more for strategic than for technical reasons.
- Minor number. This number is increased when a new distribution adds new features when compared to the previous version.
- Revision number. This increases when a distribution is created that does not add new features, or they are irrelevant, when compared to the previous version. This distribution is normally for bug fixes.
- Build number. This increases each time a distribution is built, whether it is a public distribution or an internal build made for testing purposes.
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.
- 1.2.0 build 3
Don't ever use:
- 120 build 3
- 12 build 3
These incorrect formats might lead to confusion when future versions are released.
| version | description |
|---|---|
Naming binaries for a gvSIG plugin
| Version: | 1.5 |
|---|
Before discussing file names for the distribution, the following information is required:
- The short name or code of the plugin.
- The version number of the distribution. Read the document Interpreting the gvSIG version number to familiarise yourself with gvSIG version numbers.
- The platforms for which the distribution will be built.
- The status of the development: alpha, beta, RC, final, ...
- The version of gvSIG for which it will be packaged.
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:
gvsig-version is the gvSIG version number specified in the following format:
<major-number>_<minor-number>
Neither the revision nor the build number is specified as no changes to the API are expected between versions.
name is the project's short name or code.
major number, minor-number, revision-number, and build-number identify the version of the project. Depending on the gvSIG version for which the extension will be published, we advise to use a different major-number as well. E.g., if the extension is available for gvSIG 1.x as well as gvSIG 2.x, the extension's major-number could be set to 1 and 2 respectively. The important thing is for them to be different to avoid confusion, not to be the same numbers as the gvSIG ones.
state can be:
- devel, for versions under development.
- pilot, for pilot plugins. Pilots are usually made available for testing, don't have full functionality and might contain bugs.
- prototype indicates a proof of concept that shows how developers plan to undertake a development. Future developments might not necessarily follow the same track.
- testing is used for versions that need to be tested prior to moving to alpha, beta, etc., stages.
- alpha.
- beta.
- RC followed by a number (RC1, RC2, ...) identifies release candidates prior to the final version of the product.
- final identifies the final version of the plugin.
A development doesn't have to go through each of these stages but the distribution state should be specified.
platform contains information about:
- The system on which the development runs, windows, linux, mac or whether it is system independent.
- The hardware architecture.
- The minimum version of the java virtual machine required.
These could be one of the following:
- all-all-j1_5, for binaries compiled for Java Virtual Machine version 1.5.x that are independent of the system and hardware architecture.
- all-all-j1_6, for binaries compiled for Java Virtual Machine version 1.6.x that are independent of the system and hardware architecture.
- win-i586-j1_5, for MS Windows binaries compiled for Java Virtual Machine version 1.5.x.
- win-i586-j1_6, for MS Windows binaries compiled for Java Virtual Machine version 1.6.x.
- lin-i586-j1_5, for linux binaries compiled for Java Virtual Machine version 1.5.x.
- lin-i586-j1_6, for linux binaries compiled for Java Virtual Machine version 1.6.x.
- mac_10_4-i586-j1_5, for Mac OS version 10.4 binaries compiled for the Java Virtual Machine that includes the base for that version of Mac (java 1.5).
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.
- With respect to extensions, the following are used:
- exe for MS Windows installables.
- bin for Linux installables.
- zip for Mac installables and multi-platform versions.
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:
- man-version is the version number of the manual. It is possible that multiple versions of the manual might be generated for a specific version of the product. Normally the version of the manual that is made available at the product's initial distribution is enhanced during the following weeks or months. Updated versions of the manual are then published without recreating a new distribution of the application.
- lang-code identifies the language the manual is written in. ISO639 Alpha-2 code space codes should be used for these wherever possible.
For source distributions and documentation no distinction is made between platforms.
| 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. |
