How to publish Open Data using github

Many organizations have little resources for "extra" activities, such as create their own Open Data portals. For example, small municipalities and towns do not have the time, personel or budget to expose datasets that could be useful and relevant for the community. In order to alleviate this situation, I present a simple method to publish Open Data using Github.

##What is GitHub?

Github is a company that offers hosting for software projects, based on the GIT version control system. The service is free for Open Source projects. In general, there is no problem for projects smaller than 1GB in size, which is more than enough to host a large amount of datasets.

##If it is for software, why usiing it for data?

Bueno, porque en realidad datos y software son lo mismo para este caso :-) GIT provee un sistema de versionamiento de archivos, por lo que se hace fácil hacer cambios a los datos. Asimismo, GitHub permite hacer forks, es decir, crear réplicas copias de un repositorio ya existente. Esta copia puede ser modificada a gusto y es independiente de la versión original. Eventualmente se puede aplicar los cambios realizados en la copia al repositorio original (por ejemplo, cuando se escribe un parche). GitHub facilita este proceso al permitir hacer pull requests, es decir, pedir al dueño del repositorio original que acepte los cambios hechos en la réplica. Como GIT es un sistema de control de versiones, cualquier cambio en los archivos queda marcado y es muy fácil ver el historial de estos. Todo lo anterior hace de git un sistema ideal para publicar y mantener datos abiertos.

##Ok, me convenciste, ¿Qué tengo que hacer ahora?

Lo primero es ir a http://github.com y crear una cuenta, si es que no tienes una ya. Segundo, es altamente recomendable bajar el cliente para tener una GUI amigable (sólo para Mac y Windows). ##Crear un repositorio

En el cliente de github, creamos un nuevo repositorio. Al mío lo llamaré github-open-data-portal:

Dentro del repositorio, crearé un directorio llamado data:

##Agregar datasets

Para efectos del ejemplo, simplemente bajé datos de datos.gob.cl: el listado de cooperativas de transporte (http://datos.gob.cl/datasets/ver/3877) y listado de cooperativas de trabajo (http://datos.gob.cl/datasets/ver/3870). Tomé estos archivos y los guardé en el directorio data recién creado.

Si vamos al cliente de GitHub, veremos que ha detectado que los archivos han sido agregados

Para subirlos, sólo necesitamos hacer un commit, es decir, se guarda el estado actual del repositorio: Los archivos ya están seleccionados por defecto y sólo debemos describir qué cambio estamos haciendo al repositorio.

Finalmente presionamos en commit & sync, lo que subirá los cambios a GitHub

##Modificando datasets

En el caso del archivo Transporte.csv, las últimas 3 líneas en realidad no sirven para nada, y queremos eliminarlas. Abrimos el archivo con un editor de texto y las eliminamos.

Después de guardar el archivo, vamos nuevamente al cliente de github, el cual ha detectado el cambio. Las líneas en rojo indica líneas que han sido eliminadas, si hay líneas en verde quiere decir que han sido agregada.

Creamos un nuevo commit, esta vez indicando que hemos eliminado las líneas sin usar.

Cada vez que agreguemos nuevos datasets o editemos algunos existentes, debemos crear un nuevo commit y sincronizar, de manera que los cambios se vean reflejados en github. github mantendrá todo el historial de cambios realizados, los archivos agregados y eliminados, quién realizó los cambios, etc.

##Licencia

Es importante dejar en claro cómo estamos publicando los datos en términos legales. Una medida sencilla y razonable es tener un archivo LICENCIA (o LICENSE en inglés) que describa estos términos. En nuestro ejemplo, los datasets publicados por datos.gob.cl están licenciados bajo CC-3.0-BY, por lo que agregamos esa licencia en nuestro repositorio.

#¿Cómo acceder a los datos?

Para que un tercero pueda acceder a nuestros datos, sólo es necesario proveer la URL del repositorio, en este caso https://github.com/alangrafu/github-open-data-portal/tree/master/data. Desde ahí es posible bajar cada dataset. También es posible bajar TODO el repositorio accediendo a la copia master de éste que genera github, en nuestro caso https://github.com/alangrafu/github-open-data-portal/archive/master.zip. Finalmente, cualquiera puede clonar nuestro repositorio, obteniendo así todos los datos y las versiones anteriores de estos usando el cliente provisto por GitHub. Demo

Para simplificar el proceso de mostrar el contenido del repositorio en otros sitios, hice una pequeña aplicación que usa la API de GitHub donde se lista todos los archivos disponibles en el directorio data del repositorio a definir. Para hacer esto, es necesario copiar el siguiente código dentro de una página web:

<div id="datasets"></div>
  <script src="https://raw.github.com/alangrafu/github-open-data-portal/master/app/js/jquery.min.js"></script>
  <script src='https://raw.github.com/alangrafu/github-open-data-portal/master/app/js/main.js'></script>
  <script>
  GDP.config.userName = 'alangrafu'; //Nombre del usuario
  GDP.config.projectName = 'github-open-data-portal'; //nombre del repositorio
  GDP.render("#datasets");
</script>

##Demo Un ejemplo del script en acción puede ser visto en http://graves.cl/example-github-opendata

##En resumen

Cada vez se hace más fácil publicar datos en la Web. Utilizando este método es posible publicar datos en 10 minutos o menos. Los pasos a seguir serían:

• Crear cuenta en github y bajar cliente
• Crear repositorio (o hacer un fork al de ejempo github-open-data-portal)
• Agregar todos los datasets que se quiera en directorio data
• Opcionalmente, usar el sistema de listado disponible en el ejemplo para listar los archivos disponibles en otras páginas web