Document Actions
Extensions repository manual
This document explains the procedure to publis and manage gvSIG repository projects
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.
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.
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.
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.
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.
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.
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.
Adding an improvement proposal
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.
