P AUTAS EL

Y

E STÁNDARES

PARA

LICENCIAMIENTO

DE

SOFTWARE LIBRE O DE CÓDIGO ABIERTO . Informe elaborado para el Programa ICT4BUS (ATN/ME-9733-RG) del Fondo Multilateral de Inversiones del Banco Interamericano de Desarrollo El presente documento define un conjunto de pautas y estándares para la implementación de soluciones de software en el marco del ICT4BUS. Las mismas permitirán instrumentar desde el punto de vista práctico, lo establecido en el “INFORME SOBRE POLÍTICAS DE PROPIEDAD INTELECTUAL DEL BANCO INTERAMERICANO DE DESARROLLO”, desarrollado por Alberto Cerda Silva/Claudio Ruiz Gallardo de setiembre de 2007. Estas pautas y estándares posibilitan que el software generado en el marco de operaciones financiadas por ICT4BUS, pueda efectivamente trasladarse desde la Institución que lo originó a otra Institución que lo demande, permitiendo por ende la réplica efectiva de cualquiera de los proyectos financiados en este marco. Por último, el presente documento también tiene por objetivo ser una guía que permitirá apoyar las evaluaciones a los desarrollos de software financiados dentro del marco aludido precedentemente definiendo modelos fundamentales para la objetividad de las evaluaciones.

Fredy Bentancurt Prada – [email protected] Revisiones/aportes incorporados: • •

Antonio Ca’Zorzi / Aminta Perez Gold (MIF/MIF) Alberto Cerda – DerechosDigitales.org V. 1.3 – 08ene08

INDICE INTRODUCCIÓN ................................................................................................................................................. 1  SOBRE EL USO DEL PRESENTE INSTRUCTIVO ....................................................................................................................... 1  SOBRE EL PORTAL WEB ................................................................................................................................................. 1  CONDICIONES PARA LA INCORPORACIÓN DE SOFTWARE LIBRE O DE CÓDIGO ABIERTO ..................................... 2  1.  2.  3.  4.  5.  6.  7.  8.  9. 

SOBRE LA FUNCIONALIDAD DEL SOFTWARE ............................................................................................................... 2  SOBRE EL CÓDIGO FUENTE DEL SOFTWARE ................................................................................................................ 3  SOBRE LA DOCUMENTACIÓN RESPECTIVA AL SOFTWARE .............................................................................................. 5  SOBRE LA DOCUMENTACIÓN TÉCNICA DE ERRORES DEL SOFTWARE ................................................................................ 7  SOBRE LOS AUTORES DEL SOFTWARE ........................................................................................................................ 7  NO OBJECIÓN DE BID/FOMIN CÓDIGO FUENTE Y DOCUMENTOS ANEXOS ....................................................................... 7  PUBLICACIÓN CÓDIGO FUENTE Y DOCUMENTOS ......................................................................................................... 7  CONTRIBUCIONES AL SOFTWARE ORIGINAL ............................................................................................................... 8  INSTITUCIONES QUE YA HAN FINALIZADO EL DESARROLLO ............................................................................................ 9 

ANEXO I. DOCUMENTO DE FUNCIONALIDAD DEL SOFTWARE ........................................................................... 10  ANEXO II.  MANUAL DE USUARIO .................................................................................................................... 13  ANEXO III. MANUAL DE ADMINISTRACIÓN ...................................................................................................... 16  ANEXO IV. MANUAL DE INSTALACIÓN/DESINSTALACIÓN ................................................................................. 19  ANEXO V. REGISTRO DE ERRORES ENCONTRADOS ........................................................................................... 22  ANEXO VI. DEFINICIÓN CONTACTOS DEL SOFTWARE ....................................................................................... 23  ANEXO VII. PUBLICACIÓN DEL SOFTWARE. ...................................................................................................... 24  1.  2.  3.  4.  5. 

INTRODUCCIÓN .................................................................................................................................................. 25  CREACIÓN DE UNA CUENTA DE USUARIO ................................................................................................................. 25  CREACIÓN DE UN NUEVO PROYECTO ...................................................................................................................... 26  SUBIDA DEL SOFTWARE A WWW.SOURCEFORGE.NET ................................................................................................ 26  CREACIÓN DEL SITIO WEB DEL PROYECTO ............................................................................................................... 30 

INTRODUCCIÓN SOBRE EL USO DEL PRESENTE INSTRUCTIVO Dentro del presente documento Ud. encontrará una serie de anexos donde se detallan las plantillas que contienen los formatos en los cuales deben ser presentados los diferentes documentos estándar, todos ellos tienen la misma estructura: (i) Carátula; (ii) Índice y (iii) Estructura del contenido, que en algunos casos tiene alguna ayuda de orientación, sin pretender transformarse en un instructivo. Dichos documentos también se encuentran incrustados en los respectivos lugares del documento en los cuales se hace referencia a su necesidad. Se aconseja utilizar directamente los archivos incrustados, ya que cada uno de ellos es totalmente operativo y contiene las estructuras y formatos de los respectivos documentos.

SOBRE EL PORTAL WEB Para efectos de su licenciamiento como software libre o de código abierto, ya sea al final del proyecto o luego de alguna eventual prórroga, la institución beneficiaria está obligada a proveer la última versión del software respectivo y de toda la documentación respaldante. Una vez dada la no objeción por parte del Banco la totalidad de los documentos serán publicados en el portal Web o puesta a disposición del público en repositorios de software libre o de código abierto.

Pautas y estándares para software libre/código abierto en Proyectos de ICT4BUS

Página 1

CONDICIONES PARA LA INCORPORACIÓN DE SOFTWARE LIBRE O DE CÓDIGO ABIERTO

1. SOBRE LA FUNCIONALIDAD DEL SOFTWARE 1.1 La institución autora del software deberá generar la siguiente documentación que acompañará al software en cuestión. Esta información ayudará a la institución que decida utilizar dicho software a tener una mejor comprensión del mismo. a. Objetivo del software generado: propósito del mismo b. Necesidad que satisface o problema que resuelve: incluir el motivo por el cual el software fue generado. c. Características técnicas generales: describir en qué tecnología de base está desarrollado, qué herramientas son necesarias para compilarlo (qué compilador, qué versión, qué bibliotecas se necesitan, etc.), si permite acceso vía web, y todo otro dato considerado necesario para una institución que desee incorporar el software. d. Diseño y arquitectura del software: incluir los diagramas de diseño y arquitectura del software. A su vez también incluir las especificaciones de bases de datos utilizadas. e. Personas involucradas: incluir aquí los diferentes actores, implementadores, desarrolladores, etc., definiendo claramente el rol cada uno que interactúe con el mismo. f. Enumeración y descripción de funcionalidades: Enumerar y describir aquí las funcionalidades del software. Estas funcionalidades deben estar agrupadas por secciones, módulos u opciones de menú según sea la mejor conveniencia a efectos de claridad y comprensión por parte de los lectores. Se deben incluir las pantallas asociadas. g. Soporte: Incluir aquí las modalidades de soporte y asistencia, que la institución autora del software estaría dispuesta a proporcionar a otra institución que decidiera utilizar el software. h. Datos de contacto: Incluir información concerniente a la institución autora del software a efectos de que terceros interesados puedan contactarle.

Pautas y estándares para software libre/código abierto en Proyectos de ICT4BUS

Página 2

i. Plantilla: utilizar la siguiente plantilla para generar el documento (también incluido como Anexo I). Se deben respetar los estilos, títulos, fuente y colores aquí definidos. En el caso que alguna parte no aplique entonces se debe justificar su no inclusión, bajo el título o sección que no aplica, pero de ninguna manera deben suprimirse secciones de la plantilla o títulos. Es posible agregar más partes al documento incluyéndolos como anexos. El documento generado debe estar libre de errores sintácticos y ortográficos. Para el caso de los proyectos concluidos o en proceso de terminarse, si la institución autora ya posee un documento que cumpla con los requisitos que esta plantilla presenta, entonces podrá adjuntar el mismo, lo cual pretende facilitarle el proceso pero a su vez asegurar una documentación básica indispensable.

Definicion de Funcionalidad del soft

2. SOBRE EL CÓDIGO FUENTE DEL SOFTWARE 2.1 La institución autora del software deberá entregar la fuente al Banco, siguiendo las siguientes pautas y estándares. Esta información permitirá resolver la publicación y la utilización del software por parte de otras Instituciones. a. Estándar de Codificación a utilizar: el software preferentemente deberá utilizar el estándar de programación más aceptado por la comunidad del lenguaje. Se deberá indicar explícitamente el estándar utilizado, si es posible adjuntándolo o al menos referenciándolo a una página Web o nombrándolo si es muy conocido (p.e. Hungarian Notation). Si se diera el caso de un estándar privativo solo se requerirá su especificación y si fuere un lenguaje específico que no se conozca así deberá establecerse. b. Comentarios al código fuente: el código fuente deberá estar debidamente documentado. Se entiende por debidamente: i.

Cada archivo (entiéndase archivo como función, procedimiento, clases, módulos, etc.) deberá contener al inicio la siguiente estructura. La forma de comentar dependerá del lenguaje de programación utilizado (Ejemplos: *, --, */). • Nombre del (modulo, función, procedimiento, etc.): • Descripción y objeto: • Parámetros de entrada: describa además qué es cada parámetro (si aplica)

Pautas y estándares para software libre/código abierto en Proyectos de ICT4BUS

Página 3

• Parámetros de salida: describa además qué es cada parámetro (si aplica) • Autor: • Mail: • Otros: por ejemplo, manejo de excepciones ii.

Cuando el software sólo consta de un archivo, al final de la última línea de programación debe incluirse la siguiente información: Copyright , Multilateral Investment Fund of the Inter-American Development Bank. This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as Publisher by the Free Software Foundation, either version 3 of the License, or(at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program. If not, see .

iii.

Cuando el software conste de varios archivos, el licenciamiento GLP requiere que tras la última línea de programación cada archivo contenga la siguiente información como comentario, por más información referirse a The GNU General Public License: “Copyright (C) Multilateral Investment Fund of the Inter-American Development Bank. Este archivo es parte de es software libre: usted puede redistribuirlo y/o modificarlo bajo los términos de la Licencia Pública General GNU publicada por la Fundación para el Software Libre, ya sea la versión 3 de la Licencia, o (a su elección) cualquier versión posterior. se distribuye con la esperanza de que sea útil, pero SIN GARANTÍA ALGUNA; ni siquiera la garantía implícita MERCANTIL o de APTITUD PARA UN PROPÓSITO DETERMINADO. Consulte los detalles de la Licencia Pública General GNU para obtener una información más detallada. Debería haber recibido una copia de la Licencia Pública General GNU junto a este programa. En caso contrario, consulte http://www.gnu.org/licenses/.”

Pautas y estándares para software libre/código abierto en Proyectos de ICT4BUS

Página 4

iv.

Cada cálculo deberá también tener su comentario explicando la fórmula y su función. Asegurarse que los comentarios estén bien alineados, de forma de agilizar la lectura de los mismos, por ejemplo: var MAX_USERS = 2 var MAX_POINTS = 100000

v.

//all players //needed to win game

No comentar lo innecesario, por ejemplo: for(i = 0; i < object.length; i++) { //loop until i hits max length

vi.

Algunas notaciones son especificadas en el caso que: (i) TO DO: incluya este tipo de notación al principio del comentario si se desea incluir una sugerencia a las instituciones ulteriores sobre alguna funcionalidad futura que podría agregarse; (ii) BUG: incluya este tipo de notación al principio del comentario si un trozo de código da como resultado algún error que no ha podido ser corregido1.

3. SOBRE LA DOCUMENTACIÓN RESPECTIVA AL SOFTWARE 3.1 La institución para la cual el software fue realizado, originalmente y en cada una de sus implementaciones posteriores, deberá hacer entrega al BID, además documentos que describan cómo se utiliza y opera el software publicado. a. Manual de usuario: se deberá generar un manual de usuario en donde su finalidad es describir a los usuarios finales del software cómo se utiliza el mismo. i.

Plantilla: utilizar la siguiente plantilla para generar el documento (también incluido como Anexo II). Se deben respetar los estilos, títulos, fuente y colores aquí definidos. En el caso que alguna parte no aplique entonces se debe justificar su no inclusión. Es posible agregar más partes al documento incluyéndolos como anexos. El documento generado debe estar libre de errores sintácticos y ortográficos. En el caso que la institución autora posea un documento que cumpla con los requisitos que esta plantilla presenta, entonces podrá adjuntar el mismo.

Definicion Manual de Usuario.doc 1

Por más información referirse a Successful Strategies for Commenting Code

Pautas y estándares para software libre/código abierto en Proyectos de ICT4BUS

Página 5

b. Manual de administración del software: se deberá generar un manual de administración del software de forma que el administrador del mismo pueda configurar el sistema previamente a su utilización. i.

Plantilla: utilizar la siguiente plantilla para generar el documento (también incluido como Anexo III). Se deben respetar los estilos, títulos, fuente y colores aquí definidos. Se presenta un contenido sugerido dada que la administración de los software pueden variar. El documento generado debe estar libre de errores sintácticos y ortográficos. En el caso que la institución autora posea un documento que cumpla con los requisitos que esta plantilla presenta, entonces podrá adjuntar el mismo.

Definicion Manual de Administracion del Sof

c. Manual de Instalación/Desinstalación: se deberá generar un manual de instalación/desinstalación del software. i.

Plantilla: utilizar la siguiente plantilla para generar el documento (también incluido como Anexo IV). Se deben respetar los estilos, títulos, fuente y colores aquí definidos. En el caso que alguna parte no aplique entonces se debe justificar su no inclusión. Es posible agregar más partes al documento incluyéndolos como anexos. El documento generado debe estar libre de errores sintácticos y ortográficos. En el caso que la institución autora posea un documento que cumpla con los requisitos que esta plantilla presenta, entonces podrá adjuntar el mismo.

Definicion Manual de Instalacion del Softwa

Pautas y estándares para software libre/código abierto en Proyectos de ICT4BUS

Página 6

4. SOBRE LA DOCUMENTACIÓN TÉCNICA DE ERRORES DEL SOFTWARE

4.1 Registro de Errores: se deberá entregar al Banco la lista de errores no corregidos, de forma que la institución ulterior que vaya a utilizar el software esté informada al respecto. a. Plantilla: utilizar la siguiente plantilla para registrar (transcribir) los errores (también incluido como Anexo V). Se deben respetar los estilos, títulos, fuente y colores aquí definidos. En el caso que alguna parte no aplique entonces se debe justificar su no inclusión.

Definicion Errores del Software.xls

5. SOBRE LOS AUTORES DEL SOFTWARE 5.1 Registro de autores del software: la institución autora del software, previa autorización de quienes han intervenido en el desarrollo, en su caso, indicará los datos de éstos, a efectos de ser contactados por usuarios posteriores del software. a. Plantilla: utilizar la siguiente plantilla para registrar los contactos (también incluido como Anexo VI). Se deben respetar los estilos, títulos, fuente y colores aquí.

Definicion Contactos Técnicos del Software

6. NO OBJECIÓN DE BID/FOMIN CÓDIGO FUENTE Y DOCUMENTOS ANEXOS

6.1 Dentro del contexto de la evaluación final del respectivo proyecto, se procederá a hacer una revisión de cumplimiento de las diferentes pautas y estándares definidos en el presente documento.

7. PUBLICACIÓN CÓDIGO FUENTE Y DOCUMENTOS 7.1 La Institución productora del software deberá ponerlo a disposición del Banco, a efectos de que éste pueda publicarlo en un repositorio externo de software, una vez que las condiciones de licenciamiento así lo permitan. Debe asimismo brindar los datos de la persona oficial de contacto de la Institución respectiva. Las Instituciones que lo utilicen Pautas y estándares para software libre/código abierto en Proyectos de ICT4BUS

Página 7

en un futuro, dispondrán de la posibilidad de registrarse en: http://www.pymespracticas.net/ como usuarios de dicho software. 7.2 Esta posibilidad de identificación de quien desee utilizar el software no es de ninguna manera una restricción o autorización de uso sino un mero ordenamiento interno de la comunidad que está involucrada con alguna iniciativa del Banco. La misma, si bien no es obligatoria, permitirá a todos obtener los beneficios de pertenencia a una comunidad. Se mantendrán por ende las estipulaciones de licencias GNU o BSD en el sentido que cualquiera lo puede modificar y/o adaptar. Software XXXXX Versión V.n Funcionalidad del Software Códigos Fuentes y Bases de Datos Ejecutable Registro de Errores Manuales Etc.

8. CONTRIBUCIONES AL SOFTWARE ORIGINAL 8.1 Existen varias maneras de contribuir con el software original, entre ellas: a. Reporte de errores: reportar errores del software original de forma que la institución autora pueda estar informada al respecto y eventualmente corregirlos. b. Mejoras: reportar el pedido de algún perfeccionamiento a las funcionalidades actuales. Esto quiere decir que en la actualidad funciona correctamente pero que se podrían mejorar. c. Parches: reportar parches ante la corrección de algún error. d. Mejoras en la documentación: mejorar la documentación provista por la institución autora mejorando áreas de los mismos que no estén claras o faltantes.

Pautas y estándares para software libre/código abierto en Proyectos de ICT4BUS

Página 8

9. INSTITUCIONES QUE YA HAN FINALIZADO EL DESARROLLO 9.1 Esta documentación será de utilización obligatoria en todas las nuevas operaciones. Por ende se exceptúan de su presentación aquellas instituciones que han hecho sus desarrollos de software previamente. Para éstas, los fuentes y documentación deberá cumplir con estos requisitos mínimos: a. Adjuntar los siguientes manuales, en los cuales si bien no importa el formato deberán incluir la información más relevante solicitada: i. ii. iii.

Manual de Usuario Manual de Administración Manual de Instalación/Desinstalación

b. Adjuntar el documento de funcionalidad c. Adjuntar lista de autores del software 9.2 Estos documentos pueden no cumplir con los estándares previstos en este documento por tratarse de productos ya entregados, pero deben poseer un mínimo de documentación respaldante que permita que una Institución que quiera hacer uso de la solución pueda hacerlo. -o-o-o-o-o-o-o-o-o-o-o-o-o-

Pautas y estándares para software libre/código abierto en Proyectos de ICT4BUS

Página 9

Nombre software

ANEXO I. DOCUMENTO DE FUNCIONALIDAD DEL SOFTWARE

Copyright (c) Banco Interamericano de Desarrollo. Se concede permiso para copiar, distribuir y/o modificar este documento bajo los términos de la Licencia Creative Commons BY-SA disponible en http://creativecommons.org/licenses/by-sa/3.0/.

Versión

Ciudad – País,

Pautas y estándares para software libre/código abierto en Proyectos de ICT4BUS

Página 10

Nombre Software

Documento de Funcionalidad

ÍNDICE (activo en el documento incrustado)

O BJETIVO DEL S OFTWARE …………………………………… N ECESIDAD QUE RESUELVE ………………………………….. C ARACTERÍSTICAS G ENERALES ……………………………… D ISEÑO Y A RQUITECTURA …………………………………… A CTORES INVOLUCRADOS ……………………………………. F UNCIONALIDADES …………………………………………… F UNCIONALIDAD 1…………………………………….. F UNCIONALIDAD 2…………………………………….. G LOSARIO …………………………………………………….

Pautas y estándares para software libre/código abierto en Proyectos de ICT4BUS

Página 11

Nombre Software

Documento de Funcionalidad

O BJETIVO DEL SOFTWARE El objetivo del software ….

N ECESIDAD QUE RESUELVE C ARACTERÍSTICAS G ENERALES D ISEÑO Y A RQUITECTURA A CTORES INVOLUCRADOS FUNCIONALIDADES Funcionalidad 1 Funcionalidad 2

G LOSARIO

Pautas y estándares para software libre/código abierto en Proyectos de ICT4BUS

Página 12

Nombre software

ANEXO II. MANUAL DE USUARIO

Copyright (c) AÑO Banco Interamericano de Desarrollo. Se concede permiso para copiar, distribuir y/o modificar este documento bajo los términos de la Licencia Creative Commons BY-SA disponible en http://creativecommons.org/licenses/by-sa/3.0/.

Versión

Ciudad – País,

Pautas y estándares para software libre/código abierto en Proyectos de ICT4BUS

Página 13

Nombre Software

Manual de Administración

ÍNDICE (activo en el documento incrustado)

D ESCRIPCIÓN DEL SOFTWARE …………………………… A CTORES INVOLUCRADOS ……………………………….. A LCANCE Y OBJETIVO DEL DOCUMENTO……………….. CONSIDERACIONES PARA LA LECTURA DEL DOCUMENTO G ENERALIDADES DEL SOFTWARE……………………….. I NGRESO AL SISTEMA ……………………………………. MENSAJES DE ERROR ……………………………………. I DENTIFICACIÓN DEL USUARIO EN EL SOFTWARE ………. Í CONOS Y BOTONES ………………………………………. MENÚ …………………………………………………….. A YUDA……………………………………………………. PARAMETRIZACIÓN ( SI EXISTE )………………………….. O TROS ( CUSTOMIZAR SEGÚN SE NECESITE )……………… MÓDULO X………………………………………………… MODULO XX………………………………………………. G LOSARIO …………………………………………………..

Pautas y estándares para software libre/código abierto en Proyectos de ICT4BUS

Página 14

Nombre Software

Manual de Administración

D ESCRIPCIÓN DEL SOFTWARE constituye un sistema informático……

A CTORES INVOLUCRADOS A LCANCE Y OBJETIVO DEL DOCUMENTO El objetivo del presente documento es presentar de forma clara y sencilla una descripción de las funcionalidades de …… El contenido del documento ha sido desarrollado en función de las factibles necesidades de información del usuario final del sistema, por lo tanto no contiene especificaciones técnicas que puedan requerirse para su instalación, configuración o mantenimiento, no obstante, para disponer de la ayuda en dichos aspectos diríjase por más información al Manual de Instalación del software.

C ONSIDERACIONES PARA LA LECTURA DEL DOCUMENTO G ENERALIDADES DEL SOFTWARE Ingreso al sistema Mensajes de Error Identificación del usuario en el software Íconos y botones Menú Ayuda Parametrización (si existe) Otros (customizar según se necesite) Módulo X Modulo XX

G LOSARIO Pautas y estándares para software libre/código abierto en Proyectos de ICT4BUS

Página 15

Nombre Software

Manual de Administración

ANEXO III. MANUAL DE ADMINISTRACIÓN

Copyright (c) AÑO Banco Interamericano de Desarrollo. Se concede permiso para copiar, distribuir y/o modificar este documento bajo los términos de la Licencia Creative Commons BY-SA disponible en http://creativecommons.org/licenses/by-sa/3.0/.

Versión

Ciudad – País,

Pautas y estándares para software libre/código abierto en Proyectos de ICT4BUS

Página 16

Nombre Software

Manual de Administración

ÍNDICE (activo en el documento incrustado)

P ROPÓSITO DEL M ANUAL ……………………………………………….. P ARÁMETROS GENERALES DEL SOFTWARE ……………………………… U SUARIOS Y PERFILES ……………………………………………………. D EFINICIÓN DE U SUARIOS ……………...………………………….. R ECUPERACIÓN DE ARCHIVOS …………………………………………… R ESPALDO ………………………………………………………………… G LOSARIO …………………………………………………………………

Pautas y estándares para software libre/código abierto en Proyectos de ICT4BUS

Página 17

Nombre Software

Manual de Administración

PROPÓSITO DEL MANUAL El propósito de este manual es servir de guía para los usuarios que deben administrar el Funcionamiento del software ….

PARÁMETROS GENERALES DEL SOFTWARE Esta función le permite establecer un conjunto de parámetros que determinan el comportamiento general del software y alguno de sus módulos.

U SUARIOS Y PERFILES Definición de Usuarios El esquema de seguridad del software se basa en la identificación previa de los usuarios que trabajan con el sistema. La identificación de los usuarios es validada mediante una contraseña. Usted debe catalogar los usuarios del sistema estableciendo el código de usuario y la contraseña para cada uno

R ECUPERACIÓN DE ARCHIVOS R ESPALDO G LOSARIO

Pautas y estándares para software libre/código abierto en Proyectos de ICT4BUS

Página 18

Nombre software

ANEXO IV. MANUAL DE INSTALACIÓN/DESINSTALACIÓN

Copyright (c) AÑO Banco Interamericano de Desarrollo. Se concede permiso para copiar, distribuir y/o modificar este documento bajo los términos de la Licencia Creative Commons BY-SA disponible en http://creativecommons.org/licenses/by-sa/3.0/.

Versión

Ciudad – País,

Pautas y estándares para software libre/código abierto en Proyectos de ICT4BUS

Página 19

Nombre Software

Manual de Instalación

ÍNDICE (activo en el documento incrustado)

R EQUERIMIENTOS DE H ARDWARE PARA INSTALACIÓN ……………….... R EQUERIMIENTOS DE S OFTWARE ……………………………………….. C ONFIGURACIONES PREVIAS ……………………………………… P ASOS DE LA I NSTALACIÓN ……………………………………………… P ASO 1…………………………………………………………….. P ASO 2…………………………………………………………….. P ASOS DE LA D ESINSTALACIÓN ………………………………………… P ASO 1…………………………………………………………….. P ASO 2…………………………………………………………….. V ERIFICACIÓN DE LA I NSTALACIÓN …………………………………….. G LOSARIO ………………………………………………………………..

Pautas y estándares para software libre/código abierto en Proyectos de ICT4BUS

Página 20

Nombre Software

Manual de Instalación

R EQUERIMIENTOS DE HARDWARE PARA INSTALACIÓN R EQUERIMIENTOS DE SOFTWARE Configuraciones previas

PASOS DE LA I NSTALACIÓN Paso 1 Paso 2

V ERIFICACIÓN DE LA I NSTALACIÓN PASOS DE LA D ESINSTALACIÓN Paso 1 Paso 2

G LOSARIO

Pautas y estándares para software libre/código abierto en Proyectos de ICT4BUS

Página 21

Nombre Software

Registro de Errores Encontrados

ANEXO V. REGISTRO DE ERRORES ENCONTRADOS Registro de errores encontrados Software: Versión: Institución/Organización:

Nro Error

Descripción

A qué funcionalidad corresponde

Modulo/ Función/ Procedimiento

Cat.

Gravedad

Prioridad

Pautas y estándares para software libre/código abierto en Proyectos de ICT4BUS

Estado

Página 22

Fecha encontrado

Fecha Resolución

Comentarios

Nombre Software

Definición de Contactos del Software

ANEXO VI. DEFINICIÓN CONTACTOS DEL SOFTWARE Contactos Software: Versión: Institución/Organización:

Nombre

Rol en el desarrollo

e-mail

Teléfono (cod país + característica ciudad)

Pautas y estándares para software libre/código abierto en Proyectos de ICT4BUS

Mensajería instantánea

Página 23

Horario de contacto

Nombre Software

Publicación en Sourceforge

ANEXO VII. PUBLICACIÓN DEL SOFTWARE. EL PRESENTE ANEXO ES ORIENTATIVO PARA UTILIZAR www.sourceforge.net EFECTOS DE PUBLICAR EL SOFTWARE DESARROLLADO COMO OPEN SOURCE

A

  1.  INTRODUCCIÓN ......................................................................................................................... 25  2.  CREACIÓN DE UNA CUENTA DE USUARIO ................................................................................... 25  3.  CREACIÓN DE UN NUEVO PROYECTO ......................................................................................... 26  4.  SUBIDA DEL SOFTWARE A WWW.SOURCEFORGE.NET ................................................................ 26  5.  CREACIÓN DEL SITIO WEB DEL PROYECTO .................................................................................. 30 

Pautas y estándares para software libre/código abierto en Proyectos de ICT4BUS

Página 24

Instalación en www.sourceforge.net

1. INTRODUCCIÓN 1.1

Se ha desarrollado esta ayuda para que el software open source propiedad intelectual del Fomin pueda ser publicado en http://www.sourceforge.net.

1.2

Se escogió esta plataforma luego de una investigación de posibilidades existentes en el momento. Dicha investigación concluyó que: (i) la plataforma seleccionada tiene el inconveniente, para nuestra audiencia, de no estar en idioma español; (ii) que no existen alternativas en español, al menos en la actualidad; (iii) que la plataforma seleccionada es la más difundida y por ende la más conveniente para cumplir con el propósito de difusión y replicabilidad.

1.3

Sin perjuicio de la publicación en http://www.sourceforge.net, los beneficiarios podrán publicar el software respectivo en otras plataformas similares. Dentro de ellas se llama la atención al Google Code Project http://code.google.com/hosting/.

1.4

El presente documento no pretende ser un instructivo, sino una ayuda producto de la experiencia del Banco obtenida de subir la información del proyecto ICT4BUS-PVL. Para llevar adelante esta experiencia se contó con las instrucciones de la propia plataforma y también el acceso a foros públicos que fueron de una ayuda invaluable a la hora de hacer la primera publicación.

2. CREACIÓN DE UNA CUENTA DE USUARIO 2.1

Ingresar a http://www.sourceforge.net/account/registration

2.2

Ingresar todos los datos personales: (i) Nombre; (ii) Apellido; (iii) eMail; (iv) confirmar e-mail; (v) Idioma; (vi) Zona horaria; (vii) País.

2.3

Ingresar todos los datos de la cuenta: (i) Nombre a ser publicado; (ii) Nombre de usuario; (iii) Contraseña; (iv) Reingresar contraseña; (v) Pregunta de seguridad, por si olvidamos la contraseña; (vi) Respuesta a la pregunta de seguridad.

2.4

Ingresar en opciones/términos/poliza: los datos correspondientes.

2.5

Registrar en Sourceforge.net

2.6

Deberá esperar un e-mail de confirmación de Sourceforge.net que su cuenta ha sido aceptada.

Pautas y estándares para software libre/código abierto en Proyectos de ICT4BUS

Página 25

Nombre Software

Publicación en Sourceforge

3. CREACIÓN DE UN NUEVO PROYECTO 3.1

Cuando llega el mail de confirmación de que su cuenta personal ha sido aceptada viene un link que permite ingresar directamente a su cuenta en Sourceforge.net. Tambien puede ingresar directamente a la pagina http://www.sourceforge.net y desde allí ingresar a su cuenta.

3.2

Desde allí debemos ir a “Create Project”

3.3

Ingreso de información del proyecto: (i) Selccionar el tipo, que en nuestro caso será “An open source Software Project”; (ii) Nombre del proyecto, que en nuestro caso será el nombre detallado del proyecto (nombredelproyecto 2 ); (iii) Unix name ICT4BUSnombredeproyecto 3 ; (iv) Descripción detallada del proyecto; (v) Descripción de registro (en ingles).

3.4

Ingreso de la información de licencia, que en nuestro caso será GNU General Public Licence (GPL).

3.5

Selección de la categoría de proyecto: A partir de las alternativas que presenta la propia página. Se deben asignar al menos cinco categorías. Mínimo una debe ser un tópico.

3.6

Llena en “User Agreements”: (i) Definición de Open Source; (ii) Terminos de servicio; (iii) Requerimientos de hosting; (iv) seleccionar que se han leído los tres elementos precedentes y someterlo a aprobación.

3.7

A partir de este momento se debe aguardar que Sourceforge.net apruebe el proyecto.

4. SUBIDA DEL SOFTWARE A WWW.SOURCEFORGE.NET 4.1

El archivo de proceso de carga utiliza solo el protocolo FTP, los protocolos SSH no se usan aquí (SFTP, SCP y SSH más de rsync no son soportadas).

SUBIR ARCHIVOS: 4.2

2 3

Pasos: Al momento de subir archivos se puede optar por dos maneras, una es como se muestra a continuación, utilizando el

Este nombre será el nombre resumido que usamos internamente para el proyecto. Este será el nombre con el cual se conocerá el proyecto en Sourceforge.net

Pautas y estándares para software libre/código abierto en Proyectos de ICT4BUS

Página 26

Nombre Software

Publicación en Sourceforge

cliente por defecto que los Sistemas Operativos modernos traen, generalmente por línea de comandos: 1- usar FTP para conectarse a upload.sourceforge.net. 2- Loguearse usando Usuario 'anonymous' para el nombre de usuario y la dirección de correo electrónico incluida en la generación de la “cuenta de usuario” para la contraseña. 3- Cambiar a modo binario (command: bin). 4- Cambiar a modo pasivo (command: passive), ya que si no es del modo pasivo no funciona. 5- Cambiar directorio local al directorio que contenga los archivos a subir (comando: LCD / PATH / ALL / FILES). 6- Cambio de directorio remoto /incoming (command: cd /incoming). 7- Encienda el estado de subida de impresión (status printing), si quieres ver los progresos (command: hash). 8- Subir los archivos deseados para la liberación. Los nombres de archivo sólo pueden contener caracteres alfanuméricos, guiones altos o guiones bajos (command: put FILENAME). 9- Desconecte del servidor FTP (command:quit).

4.3

Lo siguiente es como se vería una ejecución por línea de comandos (en Windows) -------------------------------------------------------------------------------------------------------------$ ftp upload.sourceforge.net Connected to osdn.dl.sourceforge.net. 220-******************************************************************** 220- On This Site: 220- /incoming SourceForge.net Project File Upload 220- ********************************************************************* 220220 530 Please login with USER and PASS. 530 Please login with USER and PASS. KERBEROS_V4 rejected as an authentication type Name (upload.sourceforge.net): anonymous 331 Please specify the password. Password: 230 Login successful. Remote system type is UNIX. Using binary mode to transfer files. ftp> bin 200 Switching to Binary mode. ftp> passive Passive mode on. ftp> hash Hash mark printing on (1024 bytes/hash mark).

Pautas y estándares para software libre/código abierto en Proyectos de ICT4BUS

Página 27

Nombre Software

Publicación en Sourceforge

ftp> lcd /PATH/TO/FILES Local directory now /PATH/TO/FILES ftp> cd /incoming 250 Directory successfully changed. ftp> put FILENAME local: FILENAME remote: FILENAME 227 Entering Passive Mode (66,35,250,221,233,148) 150 Ok to send data. ################################################################### ######## 226 File receive OK. 255908 bytes sent in 4.6 seconds (54 Kbytes/s) ftp> quit -------------------------------------------------------------------------------------------------------------------

4.4

Paginas con comandos para ftp: http://www.spinthemoose.com/~ftptask/help/tasks/ftp.html

4.5

La otra alternativa es bajar un cliente ftp con un entorno más amigable, a continuación se muestra como realizar el procedimiento, a modo de ejemplo, a través de el cliente “Filezilla” (http://filezilla-project.org)

4.6

Preparación: Bajar el cliente de Filezilla en (http://downloads.sourceforge.net/filezilla/FileZilla_3.0.8.1_win32-setup.exe) Instalar y ejecutar Filezilla

4.7

Realización del procedimiento: 1. Logearse en el servidor upload.sourceforge.net con el usuario anonymus, y como contraseña la cuenta de correo que usamos para crear la cuenta de sourceforge. Por ser una conexión ftp en puerto pondremos el 21 2. Una vez conectados, debemos arrastrar el archivo que deseamos subir hasta la carpeta incoming. En este momento podremos ver el proceso de subida en la pestaña de archivos en cola. Una vez se muestre completo ya estará disponible el archivo para agregarlo a nuestro proyecto (siguiente paso)

4.8

NOTA 1: Existe la posibilidad de que en Sourceforge se demore alrededor de 1 hora antes de que el archivo esté disponible en todos los servidores de descarga.

4.9

NOTA 2: Para asegurarse de que el archivo se distribuya asegurarse de que no se encuentre como oculto al momento de subirlo.

Pautas y estándares para software libre/código abierto en Proyectos de ICT4BUS

Página 28

Nombre Software

Publicación en Sourceforge

CREACIÓN DE LA VERSIÓN (RELEASE) 4.10

Los releases pertenecen a cada paquete. Generalmente un release contendrá archivos relacionados con una versión del software. Sourceforge permite también que dentro del mismo paquete se tenga más de una versión con el mismo nombre, (por ejemplo para identificarlas, cuando son diferentes, para distintas plataformas).

4.11

Para crear un release: 1. 2. 3. 4. 5. 6. 7.

8.

9.

Loguearse en SourceForge.net. Seleccionar “My Projects” de la sección “My Page”. Seleccionar “File Releases” del menú desplegable “Admin”. Cliquear el link “Add Release” cerca del nombre del paquete al que estará asociado el release. Escribir el nombre del release en el campo “New release name:” y cliquear el botón “Create This Release”. Escribir o pegar el log de cambios o las notas del release, si lo desea. Estos deben estar en texto plano. Seleccionar el checkbox al costado del nombre de cada archivo a agregar al release seleccionado en la sección 2 del formulario, luego clickear el botón “Add Files and/or Refresh View” Ir a la sección 3 del formulario y modificar el valor para cada archivo, como sea necesario. Clickear el botón “Update/Refresh” después de cambiar cada archivo. Si desea enviar un mail de notificación del release, dirijase a la sección 4 del formulario, seleccione el checkbox “I'm sure” y de clic en el botón “Send Notice”.

CONFIGURAR LA PÁGINA DE DESCARGA (download page) 4.12

La página de descarga es una página para los usuarios que hagan clic en el botón verde de descarga en la página de resumen del proyecto. Tiene la capacidad de detección automática de usuario final y ayuda a saber de detalles plataforma que tiene el usuario (Windows, Linux y Mac OS son detectados automáticamente).

4.13

Si bien esto no es requerido para hacer un “release”, se recomienda actualizarlo con cada “release” para hacer más fácil el proceso de descarga para los usuarios.

ACTUALIZAR LA PÁGINA DE DESCARGA 4.14

Para actualizar esta página: 1-

Ingresar a la página web www.sourcegorge.net.

Pautas y estándares para software libre/código abierto en Proyectos de ICT4BUS

Página 29

Nombre Software

234567-

89-

101112-

Publicación en Sourceforge

Seleccione el proyecto para administrar “My Projects” en la lista de “My Page”. Seleccione “File Releases" en el menú desplegable del administrador (Admin pulldown) Haga clic en “Create / Edit Download Page”. Seleccione la plataforma de la página que desea editar en el menú desplegable. Haga clic en la “Add a primary file downl" Seleccione el archivo principal de la liberación y la plataforma seleccionada en la lista proporcionada, llenar en el “Archivo exhibidos Título”, “Displayed File Title” y haga click en el botón “Submit”. Si hay otros archivos que se requieren o relacionadas con la principal plataforma para el archivo, seleccione usando la “Add file ...”/ Enlace. Rellene las “Download Instructions” en el cuadro con toda la información para que sus usuarios tengan idea a cómo lo desea, puede descargar e instalar el software. Haga clic en la “vista previa” para tener una vista previa de la página de descarga creada. Haga clic en el botón “Preview” “Guardar”, para guardar la página de descarga. Repita estos pasos para cada plataforma de apoyo de su proyecto.

5. CREACIÓN DEL SITIO WEB DEL PROYECTO SITIO WEB DE DOCUMENTACIÓN DEL PROYECTO CON “Maven Site”4 5.1

Se desarrolla a continuación un ejemplo del sitio desarrollado con MAVEN: 1234-

Crear una carpeta en el Program File: Apache Software Foundation En esa carpeta un-zip el Maven (se probó con 2.0.8-bin), se crea una carpeta llamada apache-maven-2.0.8 Instalar Java jdk (se probó con 1_5_0_15-nb-6_0_1-windows-ml) En variables de entorno, agregar/crear: o Variables de usuario Variables

Ruta

M2_HOME

C:\Program Files\Apache Software Foundation\apache-maven2.0.8

4 Se da este ejemplo de creación del sitio del proyecto con la herramienta MAVEN. Sin embargo el sitio puede ser creado con cualquier herramienta, o incluso directamente en lenguaje html, y luego subirlo de la misma forma que se explica para el sitio generado con MAVEN.

Pautas y estándares para software libre/código abierto en Proyectos de ICT4BUS

Página 30

Nombre Software

o

•

Publicación en Sourceforge

M2_HOME

%M2_HOME%\bin

MAVEN_OPTS

-Xms256m -Xmx512m

Path

%M2%;%Path%

Variables de sistema JAVA_HOME

C:\Program Files\Java\jdk1.5.0_02

JAVA_HOME

%JAVA_HOME%\bin

PATH

C:\Program Files\Java\jdk1.5.0_02\bin

PATH

C:\ Program Files \Apache Software Foundation\apache-maven2.0.8\bin

Bajo C:\WorkIct4BUS\ICT4BUS> 1. (Winkey + R y digitar "cmd" ) 2. Correr "mvn --version" a efectos de verificar que esté correctamente instalado. 3. mvn archetype:create -DgroupId=net.sf.ict4bus_pvl DartifactId=ict4bus_pvl 4. El resultado debería ser “BUILDING SUCCESSFULL”. En caso contrario se deben revisar los pasos anteriores.

• •

Se habrá creado la carpeta ict4bus_ en nuestro espacio de trabajo. La carpeta tiene la organización típica de Maven. A continuación se debe crear al sitio de documentación del proyecto. Creación de las carpetas del sitio web. El plugin archetype:create nos permite crear las carpetas origen de la documentación de nuestro sitio web. Esto nos crea las carpetas correctas en nuestro sitio web de documentación: 5. mvn archetype:create -DgroupId=net.sf.ict4bus_pvl DartifactId=ict4bus_pvl -DarchetypeArtifactId=maven-archetype-site

•

5.2

Bajo C:\WorkIct4BUS\ICT4BUS\ ict4bus_pvl>

Para procesar la documentación usaremos el comando site de maven. Este comando crea en la carpeta target/site del proyecto todos los ficheros del sitio web de nuestro proyecto, a partir de las plantillas que hemos creado en la carpeta src/site. 6. mvn site (Esto nos genera el sitio Web completo, en la carpeta target/site)

Pautas y estándares para software libre/código abierto en Proyectos de ICT4BUS

Página 31

Nombre Software

5.3

Publicación en Sourceforge

Para probar la web vamos a usar el plugin jetty que viene integrado en el Maven. Simplemente hacemos mvn site:run y esto cargará el servidor web local jetty y dejará el sitio listo para revisarlo. 7. mvn site:run

5.4

Si todo va bien nos saldrá algo como:

5.5

Esto nos indica que se ha arrancado un servidor web en la dirección http://localhost:8080/index.html

5.6

Abrimos un navegador para comprobarlo:

Pautas y estándares para software libre/código abierto en Proyectos de ICT4BUS

Página 32

Publicación en Sourceforge

Nombre Software

5.7

Como vemos esto es una página por defecto, que luego deberemos modificar. Paramos el servidor con Ctrl-C (o similar) y haremos algunos cambios.

ORGANIZACIÓN DE LOS FICHERON DEL SITIO 5.8

Dentro de (verificar):

la

carpeta

src/site

tendremos

varios

elementos

1. El fichero site.xml es el descriptor del sitio web. Deberemos editarlo para configurar las páginas y el resto de la información del sitio. 2. En la carpeta apt se dejarán los ficheros con formato APT 3. En la carpeta Resources dejaremos los ficheros de recursos de nuestro sitio: imágenenes, iconos, documentos, ficheros en general y otras páginas html que no se transformarán mediante el plugin.

5.9

Podemos colocar dentro de subcarpetas los diferentes elementos, y luego usaremos URLs relativas para llegar a ellos.

EDITANDO EL CONTENIDO DEL SITIO 5.10

Editando el menú de nuestro sitio web. El descriptor del sitio generado por el plugin archetype es muy simple. Contiene lo siguiente: 1. 2. 3. 4. 5. 6. 7. 8. 9. 10. 11. 12. 13. 14. 15. 16. 17. 18. 19. 20. 21. 22. 23.

5.11

Maven http://maven.apache.org/images/apache-maven-project.png http://maven.apache.org/ http://maven.apache.org/images/maven-small.gif

Hay varias secciones:

Pautas y estándares para software libre/código abierto en Proyectos de ICT4BUS

Página 33

Nombre Software

1. 2. 3. 4.

Publicación en Sourceforge

Información general del proyecto, como el nombre del proyecto Los banners del sitio web Los enlaces a otras páginas de interés, en el apartado links. El menú del sitio, con sus elementos.

AÑADIENDO NUESTRO LOGO 5.12

Para añadir el logo creamos la carpeta src/site/resources/images y copiamos la imagen que queramos usar como logo. Yo he partido de la imagen del apache maven, que he copiado de la url que tengo en el descriptor del sitio, y luego la editaré:

5.13

Modificación de menú de nuestro sitio web: Ir a src/site y editar el menu para realizar cambios en el, como por ejemplo, hacer que aparezca nombre de proyecto, imagen de cabecera de proyecto (banner).

5.14

Ejemplo de modificación: 1. 2. 3. 4. 5. 6. 7. 8. 9. 10. 11. 12. 13. 14. 15. 16. 17. 18. 19. 20. 21. 22. 23. 24. 25. 26.

idb_logo images/cabecera.jpg http://ict4bus-pvl/sourceforge.net http://http://sourceforge.net/sflogo.php?group_id=223281&type=5< /src> http://ict4bus-pvl/sourceforge.net