Trabajo:Cómo colaborar con el ayuntamiento

From FdIwiki ELP
Jump to: navigation, search

El Ayuntamiento de Madrid está desarrollando dos nuevas aplicaciones de participación y transparencia fomentando el desarrollo colaborativo y abierto. Estas aplicaciones están hechas enteramente en software libre para que luego puedan ser usadas en cualquier parte del mundo. Las aplicaciones están desarrolladas completamente en Ruby on Rails.

El Ayuntamiento va a organizar el evento #CodingMadrid el 2º jueves de cada mes de 12:00 a 15:00 (aunque se pueden sugerir otros horarios), en el Medialab-Prado, con todos aquellos que quieran unirse a trabajar en las nuevas aplicaciones de participación y transparencia: http://diario.madrid.es/blog/2015/11/16/desarrollo-colaborativo-y-abierto-en-codingmadrid/

Trabajo realizado por

  • Ana María Martínez Gómez (Doble Grado Ingeniería Informática - Matemáticas 5º)
  • Jakub Holubanský (Grado en Ingeniería Informática 4ºA)
  • Alberto Miedes Garcés (Grado en Ingeniería de Computadores)

¿Cómo puedo colaborar con el ayuntamiento?

Donde más ayuda se necesita es en el desarrollo.

Para quienes no se animen a programar, se puede colaborar de otras formas:

  • Pensando mejoras y cómo implementarlas, y proponerlas sin programarlas.
  • Se puede colaborar con análisis de datos. Ya hay un grupo que está realizando análisis de datos de cómo participa la gente en el Portal de Participación. Por ejemplo, la vida media de una propuesta, el uso que tiene, lo que atrae cada propuesta por tipo... hacen scrapping y analytics. Ese grupo se reúne regularmente en el Medialab, y está abierto a cualquiera que quiera unirse y colaborar.
  • Se puede ayudar a repensar los algoritmos de ordenación de las propuestas. Es decir, al usuario se le muestra una lista de propuestas en portada. ¿Cuáles deberían subir/bajar y en qué casos? Ahora mismo se usa uno como el de Reddit pero simplificado. Hay muchos posibles, y un análisis de los que hay para elegir otro mejor sería algo muy útil.


Participar en el desarrollo

¿Qué necesito saber para poder participar en el desarrollo?

El ayuntamiento de Madrid utiliza Ruby on Rails en todo su software, por tanto si no sabes Ruby on Rails lo primero que debes hacer es aprender. Para ellos puedes utilizar este artículo: Trabajo: Cómo aprender Ruby on Rails

También necesitaras tener un cuenta en Github. Puedes crearla aquí si no la tienes ya: https://github.com/join

Deberás además saber usar Github y Git. Para ello puedes utilizar la siguiente guía: https://git-scm.com/doc

Manos a la obra

El portal de participación se encuentra en: https://github.com/consul/consul

El portal de transparencia de encuentra en: https://github.com/AyuntamientoMadrid/transparencia


Requisitos previos (Linux y Windows)

Para colaborar en ambos proyectos lo primero que debes hacer es instalar git, Ruby 2.2.3, la gema Bundler y PostgreSQL (9.4 o superior). Además para el de participación también necesitarás GhostScript.


Git

Si estás en Linux para instalar git basta con:

  sudo apt-get install git


Ruby 2.2.3

Si estás usando Ubuntu o Debian NO utilices

  sudo apt-get install ruby-full

Esto instalará la versión 1.9.3 que no es válida para este proyecto.


Puedes descargar la versión 2.2.3 en formato .gz aquí:

https://cache.ruby-lang.org/pub/ruby/2.2/ruby-2.2.3.tar.gz

Luego ejecuta desde la consola lo siguiente:

  sudo apt-get update
   sudo apt-get install build-essential openssl libreadline6 libreadline6-dev curl git-core zlib1g zlib1g-dev libssl-dev libyaml-dev libsqlite3-dev sqlite3 libxml2-dev libxslt-dev autoconf libc6-dev ncurses-dev automake libtool bison nodejs subversion

Desde la carpeta donde esté la descarga descomprime el archivo:

  tar xvfz ruby-2.2.3.tar.gz

Cambia de directorio:

  cd ruby-2.2.3

Compila e instala:

  ./configure
  make
  sudo make install

Actualiza las gemas:

  sudo gem update --system


En algunos sistemas operativos hay formas más sencillas:

CentOS, Fedora, or RHEL:

  sudo yum install ruby

Windows: Usando el siguiente instalador http://rubyinstaller.org/ (importante: no bajéis la versión de 64 bits, pues no es compatible con algunas de las gemas que usan los proyectos del ayuntamiento)

Puedes encontrar más información sobre como instalar Ruby aquí: https://www.ruby-lang.org/en/documentation/installation/

Ruby version manager (RVM)

RVM es una herramienta de linea de comandos (No funciona con windows) que te permite instalar y tener varias versiones de ruby sin que haya conflicto entre ellos puesto que varios proyectos del ayuntamiento están en distintas versiones. Para poder instalar rvm necesitas tener instalada la herramienta curl (En Mac OS X viene instalada por defecto) y git y ejecutar el siguiente comando.

   gpg --keyserver hkp://keys.gnupg.net --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3
   \curl -sSL https://get.rvm.io | bash -s stable

   rvm install 2.2.3

Si estas utilizando Debian o sus derivados necesitaras instalar el metapaquete build-essential.

En Linux deberás instalar estas dependencias usando el administrador de paquetes de tu distribución.

Y podrás instalar cualquier versión de ruby que necesites.

Si necesitas mas información sobre la instalación visita Rvm

Gema Bundler

Si estás en Linux basta con:

  gem install bundler

Si necesitas más información: http://bundler.io/


Ghostscript

En Debian/Ubuntu basta con

  sudo apt-get install ghostscript


PostgreSQL (9.4 o superior)

Esto es lo más difícil de instalar y configurar.

En Debian tienes la siguiente guía detallada: https://wiki.debian.org/es/PostgreSql

Para evitar problemas es recomendable instalar también:

  apt-get install postgresql-9.4-postgis-scripts


PhantomJS

Para ejecutar los tests es necesario tener instalado PhantomJS. En el proyecto consul se dice que la versión tiene que ser igual o superior a 2.0. Para Windows puedes instalarlo como se indica en el siguiente enlace:

http://phantomjs.org/download.html

Instalar PhantomJS en Linux es algo más complicado. Si tienes problemas para instalar la versión 2, lo mejor es que instales la 1.9.8 con la que los test del proyecto también funcionan. Puedes hacerlo así:

  sudo apt-get install libfreetype6 libfreetype6-dev
  cd ~
  export PHANTOM_JS="phantomjs-1.9.8-linux-x86_64"
  wget https://bitbucket.org/ariya/phantomjs/downloads/$PHANTOM_JS.tar.bz2
  sudo tar xvjf $PHANTOM_JS.tar.bz2
  sudo mv $PHANTOM_JS /usr/local/share
  sudo ln -sf /usr/local/share/$PHANTOM_JS/bin/phantomjs /usr/local/bin
  phantomjs --version

Requisitos previos (Mac OS X)

En principio esta sección de requisitos es autocontenida y no es necesario que ejecutes ninguno de los pasos que se detallan en las secciones comunes.

Homebrew

Homebrew es un gestor de maquetes para OS X muy popular que desempeña una función similar a la de apt-get en sistemas de tipo Debian. Es recomendable que lo instales pues facilita enormemente la instalación de determinados paquetes. Puedes encontrar las instrucciones de instalación en: http://brew.sh

XCode y XCode Command Line Tools

Para utilizar git necesitas instalar Xcode (está en la Mac App Store) y las Xcode Command Line Tools (se instalan desde el menú de Xcode).

Git y Github

Puedes descargarlo desde: https://git-scm.com/download/mac Y si también quieres instalar la aplicación de escritorio de GitHub: https://desktop.github.com

Ruby y rbenv

OS X ya viene con una versión preinstalada de ruby, pero es bastante vieja y en nuestro caso no nos sirve. La forma más recomendable de instalar Ruby es a través de rbenv (mejor que RVM). Las instrucciones de instalación están en su GitHub y son bastante claras: https://github.com/rbenv/rbenv

Bundler

Basta con ejecutar:

  > gem install bundler

PostgreSQL y postscript

La forma aparentemente más sencilla de instalarlos es hacerlo de forma conjunta mediante esta app: http://postgresapp.com No obstante no he comprobado que funcione y a continuación paso a detallar la forma que sí que probado (bastante más complicada). PostgreSQL puedes instalarlo a través de Homebrew mediante:

  > brew install postgres

Una vez instalado es necesario inicializar la instalación:

  > initdb /usr/local/var/postgres

Ahora vamos a configurar algunos aspectos del usuario por defecto. Primero iniciamos el servidor de postgres con:

  > postgres -D /usr/local/var/postgres

Para cuando quieras cerrarlo (ahora no!!) puedes hacerlo con Ctrl+C. Si quieres información más detallada sobre cómo terminar el proceso (mediante distintos tipos de señales) puedes consultar este enlace: http://www.postgresql.org/docs/9.3/static/server-shutdown.html

Llegados a este punto se supone que tenemos postgre correctamente instalado y se nos habrá creado un usuario por defecto (cuyo nombre es nuestro nombre de usuario), y que (todavía) no tiene contraseña. Si ejecutamos:

  > psql

accederemos a la consola de postgre con el usuario por defecto. Probablemente fallará porque es necesario que de antemano exista una base de datos por defecto para dicho usuario. Podemos crearla ejecutando sobre la terminal:

  > createdb tu_nombre_de_usuario

Si ahora ejecutamos psql de nuevo deberíamos poder acceder correctamente a la consola de postgres. Si sobre la consola de postgres ejecutas \du puede ver la lista de usuarios actual. En el caso de que quieras asignarte una contraseña puedes hacerlo desde la consola de postgres con:

  ALTER USER tu_nombre_usuario WITH PASSWORD 'tu_contraseña';

Te llamará la atención que si sales de la consola y vuelves a ejecutar psql volverás a entrar sin que te pregunte la contraseña. Esto es porque postgre guarda la contraseña internamente para no preguntártela todo el rato.

Ahora vamos a crear el usuario consul, que es el que utiliza la aplicación del ayuntamiento. Ejecuta sobre la consola de postgres:

  CREATE ROLE consul WITH PASSWORD '000';
  ALTER ROLE consul WITH SUPERUSER;
  ALTER ROLE consul WITH login;

Para instalar postgis:

  > brew install postgis

Si en algún momento durante la instalación de PostgreSQL y postgis sospechas que te has equivocado y deseas desinstalarlo y volver a empezar desde cero:

  > brew uninstall postgres

También tendrás que borrar el siguiente directorio para que no de conflictos cuando intentes volver a instalarlo (fuente: https://gist.github.com/lxneng/741932):

  > rm -rf /usr/local/var/postgres

Ghostscript

Lo más sencillo es hacerlo a través de Homebrew:

  > brew install ghostscript

PhantomJS

Lo más sencillo es hacerlo a través de Homebrew:

  > brew install phantomjs

Clonar el repositorio

Ahora que ya tenemos todo instalado podemos bajarnos el proyecto:

  > git clone https://github.com/consul/consul.git
  > cd consul
  > bundle install
  > cp config/database.yml.example config/database.yml
  > cp config/secrets.yml.example config/secrets.yml

Ahora copia en database.yml el usuario y la contraseña que pusiste para consul. Cuando ya lo hayas hecho:

  > rake db:create
  > rake db:setup
  > rake db:dev_seed
  > RAILS_ENV=test bin/rake db:setup

Para probar si te funcionan los tests ejecuta sobre el directorio dentro del directorio de consul:

  > rspec

Descargar y configurar proyecto

Descarga el proyecto de Github y sigue las instrucciones. Lo más adecuado es bajarlo usando el comando git. Para esto, visita el enlace del repositorio y copia el enlace del .git (aparece entre los botones, junto al botón HTTPS). Tras esto, ejecuta (cambiando el enlace en caso de que uses un repositorio distinto):

  git clone https://github.com/consul/consul.git


Si al hacer bundler install te da problemas la gema pg en Ubuntu o Debian prueba lo siguiente:

  sudo apt-get install libpq-dev
  gem install pg


Debes crear un usuario en PostgreSQL (por ejemplo consul) con una contraseña (por ejemplo 000). Puedes hacerlo así:

  sudo su - postgres
  psql
  CREATE ROLE consul WITH PASSWORD '000';
  ALTER ROLE  consul WITH attribute_options;

No olvides darle permisos al usuario, sino seguramente bin/rake db:setup te dará errores. El proyecto hace uso de muchos de ellos, por lo que es aconsejable asignarle permisos de súper usuario. La siguiente documentación puede serte de utilidad:

http://www.postgresql.org/docs/8.2/static/sql-alterrole.html

Puedes usar \du en psql para ver los de usuarios y sus permisos. También puedes usar \l para ver las tablas y su dueño. Para salir de psql usa \q y para salir de postgres exit.

A continuación modificar el fichero config/database.yml antes de hacer bin/rake db:setup. Lo que debes modificar en el fichero es lo siguiente:

  username: consul
  password: '000' 


Si obtienes un error similar a este:

ActiveRecord::StatementInvalid: PG::UndefinedFile: ERROR: could not open extension control file "/usr/share/postgresql/9.4/extension/unaccent.control": No such file or directory

Lo más probable es que tengas un error con tu instalación de postgis. Prueba con:

  apt-get install postgresql-9.4-postgis-scripts

Instalación en Windows

Dependencias

Al menos una de las gemas que usa el proyecto del ayuntamiento es incompatible con Windows, por lo que no es posible ejecutar el servidor sin antes haber cambiado sus dependencias. Es por esto por lo que es más aconsejable realizar las pruebas sobre un sistema Linux en una máquina virtual en esta situación. En caso de seguir queriendo ejecutarlo en esta plataforma, seguimos las siguientes instrucciones:

  • Abrimos el Gemfile y quitamos/comentamos la línea "gem unicorn", puesto que esta librería es incompatible con Windows.
  • Añadimos una línea al Gemfile con el siguiente texto para poder incluir tzinfo-data: gem 'tzinfo-data', platforms: [:mingw, :mswin]
  • Añadimos una línea al Gemfile con el siguiente texto para poder incluir una versión compatible de Nokogiri: gem 'nokogiri', '1.6.7.rc4
  • En la página de descarga de Ruby ( http://rubyinstaller.org/downloads/ ) nos bajamos el Development Kit para Ruby >= 2.0 de 32 bits. Lo extraemos y ejecutamos devkitvars.bat. Se nos abrirá la línea de comandos con comandos especiales de MinGW. Seguimos los siguientes pasos:
    • Ejecutamos gem install --no-ri --no-rdoc bcrypt para bajar el código fuente de bcrypt.
    • Cambiamos de directorio al directorio de gemas de Ruby, y vamos a la carpeta en la que se nos bajó el código fuente. Por ejemplo, C:\Ruby22\lib\ruby\gems\2.2.0\gems\bcrypt-3.1.10-x86-mingw32\ext\mri (depende de dónde hayamos instalado Ruby y la versión actual de bcrypt).
    • Ejecutamos ruby extconf.rb, make' y luego make install para instalar bcrypt en Ruby.
    • Volvemos al archivo Gemfile, quitamos la línea que requiera bcrypt en caso de que lo haga, y añadimos la línea gem 'bcrypt.

Ejecución

Con esto, deberíamos haber solucionado las dependencias del proyecto (aunque la de Nokogiri nos la hemos cargado, por lo que podemos haber perdido funcionalidad). Es importante que tengamos la versión de 32 bits de Ruby, puesto que de lo contrario no nos servirá alguno de los pasos anteriores. Una vez hayamos seguido los pasos anteriores, instalado PosgreSQL y configurado la conexión en config/database.yml, podemos pasar a ejecutar el servidor con los siguientes comandos:

  rake db:setup
  rails s

Issues

GitHub utiliza un sistema de tickets para manejar los avisos de bugs y peticiones de nuevas funcionalidades, llamados aquí issues. Un usuario comienza abriendo un issue informando del problema o proponiendo cambios, y otros usuarios pueden comentar el issue para discutir cambios o informar de que han decidido trabajar en él. En issues complejos (principalmente funcionalidades nuevas), se sigue el siguiente proceso:

  • Se abre el issue sugiriendo los nuevos cambios.
  • Los usuarios comentan el cambio, incluyendo a veces bocetos.
  • Uno o más usuarios se encargan de hacer el informe de los cambios. Publican el informe.
  • Uno o más usuarios se encargan de llevar a cabo la implementación.
  • El código se publica en una Pull Request (una solicitud para incluir el nuevo código en el repositorio principal).
  • Se acepta la Pull Request y se cierra el issue.

En caso de issues menores como bugs, es posible pasar directamente a la parte de implementación. En la lista de issues, habitualmente veremos etiquetas que avisan del estado del issue y de si se encuentra asignado a algún colaborador. En el caso de querer ayudar con alguna implementación, lo ideal es buscar aquellos issues que no estén asignados y se encuentren marcados como PRs-welcome, puesto que esta etiqueta indica que está esperando a que algún programador aporte el código para solucionar el issue. Aquellos issues marcados como Not-ready no tienen los nuevos cambios todavía definidos del todo, por lo que es mejor no comenzar a implementarlos aún.

Contribuir sin necesidad de programar

Es posible también colaborar sin contribuir código, abriendo nuevos issues en los que se informe de un bug o se proponga una nueva funcionalidad. Es de mucha ayuda ser descriptivos en estos casos, incluyendo información sobre el sistema operativo y navegador en caso de informar de un bug, por ejemplo. Por supuesto, dar a conocer más el proyecto es también una buena forma de ayudar a su desarrollo.

Proceso para llevar a cabo una Pull Request

En caso de querer aportar el código para un issue, el primer paso (normalmente) es pedir que te asignen el issue. Tras esto, toca hacer un fork del repositorio, creando así un repositorio en nuestra cuenta en el que iremos poco a poco añadiendo el código necesario hasta haber terminado.


Trabajar en un fork

Para crear un fork y trabajar en él, seguimos los siguientes pasos:

  • Abrimos la página de GitHub principal del repositorio.
  • Hacemos click en el botón de fork y tendremos ahora un nuevo repositorio en nuestro perfil personal.
  • Cogemos el enlace .git del nuevo repositorio (suele salir al lado de un botón que pone HTTPS) y hacemos clone del repositorio en nuestro ordenador:
  git clone <https://-----.git>
  • Configuramos los archivos database.yml y secret.yml usando las instrucciones que hemos visto anteriormente.
  • (Bucle) Realizamos cambios en el código en nuestro ordenador. Para subirlos a nuestro repositorio, los agrupamos en un nuevo commit en git:
  git commit -m "descripción sobre los nuevos cambios"

Luego lo subimos con push (podemos hacer varios commits antes de realizar un push para ir registrando las diferentes versiones):

  git push 

Esto último pide usuario y contraseña de GitHub.

  • Repetimos el bucle hasta tener el código listo. Antes de realizar el Pull Request, nos aseguramos de que cumpla los tests Spec:
  bin/rspec

En Windows podemos usar bundle rspec, aunque es más aconsejable no usar Windows para esto.

Nota: a la hora de escribir nuevo código, intenta seguir las buenas prácticas de Ruby que aparecen en este enlace: https://github.com/styleguide/ruby


Crear la Pull Request

Ahora que ya tenemos el código listo, toca pedir que sea añadido al repositorio principal. Para ello, creamos un Pull Request:

  • Nos dirigimos al repositorio principal y elegimos New Pull Request
  • Pulsamos "compare across forks", pues queremos añadir el código de nuestro fork.
  • En base fork dejamos el repositorio original. En head fork, elegimos el repositorio de nuestro usuario (por ejemplo, <usuario/consul> y master, aunque podemos usar otros nombres).
  • Añadimos un título y una descripción al Pull Request (informando además de qué issue estamos resolviendo), y hacemos click en Create Pull Request

Con esto, nuestro Pull Request aparecerá en el repositorio principal, y en él la lista de cambios al código que queremos realizar. Al principio, se ejecutarán automáticamente dos controles sobre nuestro código para comprobar que cumple los requisitos:

  • Travis CI: comprueba que no haya ningún error a la hora de ejecutar rspec. No deberíamos tener problemas si lo hemos ejecutado nosotros antes y nos salía todo correcto.
  • Coverage: analiza la proporción de líneas de código que han llegado a ser ejecutadas en los tests y comprueba que no haya disminuido. Al añadir nueva funcionalidad es normal añadir código que no llega a ser ejecutado en ninguno de los tests existentes, por lo que necesitaremos crear nuevos tests para pasar esta comprobación.

Por supuesto, el código no será incluido hasta que uno de los administradores del repositorio decida hacer un merge (unir el código). Mientras el pull request siga disponible, podemos añadirle más código subiendo nuevos commits al repositorio.

Deshacer el último commit

En ocasiones, podemos subir un commit erróneo a nuestro repositorio y necesitamos borrarlo. Para ello, deshacemos el commit desde git y actualizamos el repositorio con los siguientes comandos:

   git reset --soft HEAD~1
   git push -f

Esto eliminará el commit, pero mantendrá los cambios realizados en nuestro ordenador.

Mantener actualizado nuestro repositorio

Dado que el proyecto del ayuntamiento se actualiza muy frecuentemente es conveniente que lo actualices de vez en cuando. Esto deberás hacerlo sobre todo antes de hacer pull request para evitar crear conflictos entre tu copia y la actual del ayuntamiento.

Primero debes configurar con que repositorio quieres que se sincronice tu proyecto (en este caso el del ayuntamiento):

  git remote add upstream https://github.com/consul/consul.git

Esto solo hará falta hacerlo una vez.

Si necesitas cambiar el upstream puedes eliminarlo y después volver a añadirlo. Para eleminarlo usa:

  git remote rm upstream

Con el siguiente comando puedes comprobar que esto último se ha realizado correctamente:

  git remote -v


Sincroniza tu repositorio con el del ayuntamiento:

  git fetch upstream
  git checkout master
  git merge upstream/master

En caso de que haya algún conflicto se avisa en la consola y aparece señalado en el código para que puedas corregirlo.

Si ocurre algún problema y quieres volver a bajarte todo desde upstream puedes hacer:

  git remote add upstream /url/to/original/repo
  git fetch upstream
  git checkout master
  git reset --hard upstream/master  
  git push origin master --force

Véase también