.. contents:: Contents

Background 
============== 

Having a place to share contributions from developers and users is a long time issue for the gvSIG project. Thus, those contributions would be given by independent developers or from different companies, universities because they think the community can take profit from them.

This new area_ at gvSIG portal will serve as a common place to publish extensions and non official contributions.

.. _area: /plugins/downloads

Definitions
==================
**repository**
  Web application that can catalog extensions and contributions for gvSIG.
  Technically it is a product added to a Plone CMS instance.  

**repository administrator**
  Who is in charge of this application. His responsibility is to create user accounts and approve project publishing.
  
**project**
  Development of a new gvSIG extension or any other contributions, big enough to 
  be published on the repository. The project should have some metadata, like a 
  contact email, web page and optionally developers contact, source code repository, 
  bug tracking system, etc.

**project manager**
  Who creates the repository project, as well as the contact between gvSIG project and the entity who wants to publish a contribution.

**release**
  On every new project version, the repository can configure different versions (usually known as *releases*) from unstable versions to more stable or final versions.

Previous requisites
=====================
The only technical requisite to start working with the repository is to have a valid user/password for the application. It's worth pointing out that the user/password **are not the same** that the used at the gvSIG portal because they are different Plone instances.

So, the first step is to contact the repository administers trough this form_.

.. _form: requestCatalogUser_form

Project creation
=======================

Once validated it's easy to create a new project clicking on the **Add new software project** button. This step requests the general information about the project. That is to say, the common data for every release:

* Title, abstract and long description of the project
* Category or categories where the project fits
* gvSIG versions where this project has been tested
* Several addresses (when applicable):

  * URL or email address for the contact person (the only non optional)
  * Web page for the project
  * Source code repository
  * Bug tracking repository
  * Mailing lists
  * Logo (to upload or link) and an screenshot

Once the data are filled, as mostly Plone documents, you should ask for the project publishing. The administer will decide if the project is published or not.

In general is better to have in touch with the administers before starting the project editing. This way is easy to coordinate and track the project from the beginning.


.. figure:: add_project.png
   :scale: 100
   :alt: Adding a project to the repository
   :align: center

   Adding a project to the repository


Creating *releases*
=============================
After the repository administer has published the project, the project administer can start adding releases.

To add the first release the web application shows a link for this purpose. To publish the next ones you should enter into the release list.

These are the data you should provide for a release:

* Version number and an alias
* Short and long description
* Change log
* Name and email of the *release manager*
* Dates:

* Limit to accept new enhancement proposals
  * Limit to stop adding new features
  * Proposed date for the release publishing

* Contribution license. Nowadays accepted licenses are:

  * GNU GPL
  * GNU LGPL
  * BSD revised license

* Compatibility of the extension with different versions of gvSIG (1.0 and later)
* Accepted list of changes (see below)
* Branch of the source code versioning system for this release

Only the version, the short description and the license are required.

.. figure:: add_release.png
   :scale: 100
   :alt: Adding a release
   :align: center

   Adding a release to the project



Adding files to a release
++++++++++++++++++++++++++++++++++

Once you've created a release, you have to add files to it. This files can be uploaded files or external links uploaded in an external server. To add files on the release screen you should click on the top right menu item *add new item->{downloadable file|externally hosted file}*.

When you add a file you should point a name and platforms (operating systems) where this file is applicable.

**WARNING**: Nowadays gvSIG project is not supporting to upload files, so you **must** have your files uploaded in an external server. Any file uploaded to gvSIG servers will be automatically deleted.

.. figure:: add_file.png
   :scale: 100
   :alt: Add files menu
   :align: center

   Menu to add files to a release


Release statuses
++++++++++++++++++++++++++

**unreleased**
  Once a release has been created, it's under *unreleased* status. That doesn't mean that it's not public, it means that this version is not finished and it shouldn't have binaries or any file to distribute (but the system will let that situation, it's under project administer decision to publish files in an *unreleased* release).

  During this phase, change proposals or new features could be managed (see roadmap section below), as well as publishing dates, comments, etc.

**alpha**, **beta**, **release candidate**, **final release**
  These are the typical phases of status for a release, common at free software domain. Those status are configured using the top right menu.
  

Project roadmap management
==================================

If the project administer thinks it's worth, he can use the repository as a feature and roadmap administering center. That is, he can catalog planned features for next releases and assign them, discuss, accept comments and so on.

.. figure:: edit_roadmap.png
   :scale: 100
   :alt: Editing roadmap properties
   :align: center

   Editing roadmap properties


Improvement proposals
+++++++++++++++++++++++++

To add a improvement proposal you should access the roadmap and add it from the menu. The fields you should fill are:

* Title and abstract for the proposal
* Name of the proposer and if anyone seconds it
* Type of proposal (types are administered from roadmap editing dialog)
* Motivation
* Complete description of the proposal
* Definitions
* Assumptions
* Implementation details
* Generated products
* Risks
* List of actions to resolve the proposal
* Participants
* Branch of the source code version control where the proposal is being implemented


The required fields are: title, abstract, proposer, type, motivation and long description.


.. figure:: edit_proposal.png
   :scale: 100
   :alt: Adding an improvement proposal
   :align: center

   Adding an improvement proposal


.. figure:: sample_proposal.png
   :scale: 100
   :alt: Sample proposal
   :align: center

   Sample proposal 



Improvement proposal statuses
+++++++++++++++++++++++++++++++++++++++

An improvement proposal is a *draft* when is created. The project administer can upgrade the proposal (*propose*) at anytime. The proposal will be at *discussed* status.

Only validated users of the system can comment a proposal.

A proposal can be *rejected*, delayed (*defer work*) or started (*begin work*). So, this is the typical work flow for a task and the application lets project manager to deal with them easily.

These features can be assigned to an specific release when a new one is created, this way you can inform your users witch ones are being included on your next releases.


Sample extension
========================
There is a sample extension (but functional) that has been used as a test case to write this manual. This extension has almost all the information a project can have, a release and some improvement proposals.

https://gvsig.org/plugins/downloads/georss-support/