#300 Contributing to Open Source

Github hace que sea muy fácil colaborar con proyectos de código abierto. En este episodio veremos cómo hacerlo enviando una petición de cambio al proyecto VCR. Vimos esta gema, que proporciona una manera de guardar las transacciones HTTP y reproducirlas para acelerar los tests, en el episodio 291. Myron Marston, el autor de la gema, suele estar muy pendiente de las colaboraciones que recibe su proyecto.

Supongamos que hemos encontrado un problema en esta gema, y que queremos enviar un parche que lo corrige. Lo primero que hay que hacer es ver la herramienta de incidencias de la gema y ver si este problema ha sido ya atacado. Si el proyecto dispone de lista de correo es buena idea hacer algunas búsquedas en ella para ver si hay mensajes relacionados con el problema que hemos encontrado. Si se trata de cambios grandes es buena idea discutirlos primero para ver si hay interés en dicho cambio.

Fork It!

Una vez que estemos listos para empezar en nuestra corrección, el primer paso es bifurcar el proyecto. Para esto tenemos que visitar la página del mismo y hacer clic en el botón ‘fork’, que al cabo de unos segundos creará nuestra propia copia del repositorio, y una vez que haya acabado podemos visitar nuestra propia versión y clonarla a partir de su URL.

$ git clone git@github.com:eifion/vcr.git
$ cd vcr

Tras el clonado, deberíamos poder ver las ramas que tenemos:

$ git branch -r
  origin/1-x-stable
  origin/HEAD -> origin/master
  origin/jruby_nailgun
  origin/master

Merece la pena destacar que hay una rama para la versión estable 1, que es la versión actual de la gema. La rama master apunta a la versión 2, que se encuentra actualente en fase de pre-lanzamiento. Debemos tener esto en cuenta: la versión de la gema con la que estamos trabajando puede que sea distinta de la que estamos viendo su código.

Siempre es buena idea leer la documentación al montar el entorno de desarrollo de un proyecto. En este caso hay una sección de desarrollo en el fichero README que nos dice que las peticiones de cambio serán bienvenidas siempre que los cambios que hagamos vengan con tests. El fichero README no da instrucciones sobre la suite de tests de la gema, pero al menos Travis CI dice que todos los tests están pasando.

El proyecto tiene un Gemfile, por lo que sabemos que utiliza Bundler para sus dependencias. Deberíamos poder instalarlas ejecutando bundle install, pero al hacerlo vemos un error. Esto no es de extrañar porque la configuración varía de un sistema a otro por lo que deberíamos esperar encontrarnos con algunas pegas a la hora de instalar un proyecto en nuestro entorno.

El error que vemos está relacionado con la gema rb-fsevent, y una búsqueda rápida nos indica que el problema tiene que ver con nuestra configuración. Estamos usando GCC Installer en lugar de la instalación completa de XCode en nuestro equipo, lo que impide que se instale rb-fsevent. El problema ya está corregido en esta gema, pero no en su versión estable, por lo que podemos corregirlo estableciendo la versión de rb-fsevent a la versión de pre-lanzamiento.

# Additional gems that are useful, but not required for development.
group :extras do
  gem 'guard-rspec'
  gem 'growl'
  gem 'relish', '~> 0.5.0'
  gem 'fuubar'
  gem 'fuubar-cucumber'

  platforms :mri do
    gem 'rcov'
    gem 'rb-fsevent', '0.9.0.pre4'
  end

  platforms :mri_18, :jruby do
    gem 'ruby-debug'
  end

  platforms :mri_19 do
    gem 'ruby-debug19'
  end unless RUBY_VERSION == '1.9.3'
end

Al ejecutar bundle todo se instalará correctamente.

Ejecución de los tests

Intentemos pasar a continuación los tests de la gema. Con frecuencia viene una tarea Rake por defecto que hace esto, por lo que debería bastar con lanzar rake, pero es mejor ejecutar bundle exec rake para asegurarnos que estamos usando los binarios de las gemas instaladas por Bundler.

$ bundle exec rake
  1504/1504:   100% |==========================================| ETA:  00:00:00

Los tests pasan, quedando un par de ellos pendientes, lo que está bien. Tras esto se ejecutan los escenarios de Cucumber, donde vemos un mensaje de error bastante largo, que básicamente viene a decir “no such file to load -- spec”. Parece ser que nos falta una dependencia que Bundler no ha instalado.

Después de investigar un poco resulta que el proyecto utiliza submódulos de Git por lo que para que funcione debemos ejecutar estas dos órdenes:

$ git submodule init
$ git submodule update

Con esto se copiarán los submódulos a nuestro repositorio. Ya podemos intentar ejecutar los tests y ver si pasan, cosa que esta vez sí ocurre.

Desarrollo de nuestros cambios

Hemos tenido algunos problemas para que pasen los tests pero lo hemos conseguido al fin. Podríamos habernos ahorrado algo de tiempo si la documentación hubiera sido un poco más detallada en cuanto a la configuración del entorno. Por tanto, nuestra primera petición de cambio consistirá en la mejora de la documentación del fichero README para configurar el entorno de desarrollo.

Resulta que ya existe una página de wiki dedicada a la colaboración con el proyecto VCR, pero sólo contiene lo más básico de la configuracón. Editemos esta página para añadir más información, basándonos en los problemas que hemos encontrado. Tras esto podemos enviar una petición de cambio para añadir el enlace a esta guía en el README.

Antes de hacer cambios al código debemos estar seguros de que tenemos el directorio limpio.

$ git status
# On branch master
# Changes not staged for commit:
#   (use "git add <file>..." to update what will be committed)
#   (use "git checkout -- <file>..." to discard changes in working directory)
#
#        modified:   Gemfile
#
no changes added to commit (use "git add" and/or "git commit -a")

Como hemos modificado el Gemfile, será mejor que deshagamos este cambio antes de avanzar.

$ git checkout .
noonoo:vcr eifion$ git status
# On branch master
nothing to commit (working directory clean)

Es buena idea establecer una rama Git separada para cada petición de cambio que queramos hacer.

$ git checkout -b readme-contributing-link

Con esto ya podemos hacer nuestro cambio. En la sección de desarrollo de README.md hemos añadido un enlace a la página del wiki que acabamos de cambiar.

## Development

* Source hosted on [GitHub](http://github.com/myronmarston/vcr).
* Direct questions and discussions to the [mailing list](http://groups.google.com/group/vcr-ruby).
* Report issues on [GitHub Issues](http://github.com/myronmarston/vcr/issues).
* Pull requests are very welcome! Please include spec and/or feature coverage for every patch,
  and create a topic branch for every separate change you make.
* See the [Contributing](https://github.com/myronmarston/vcr/blob/master/CONTRIBUTING.md)
  guide for instructions on running the specs and features.

Una vez que hayamos hecho estos cambios podemos ejecutar git diff para repasarlos. Si estamos satisfechos, podemos entregar los cambios :

$ git commit -a -m "adding contributing link to readme."Next we need to push our branch to our remote repository.
$ git push origin readme-contributing-link
Counting objects: 5, done.
Delta compression using up to 2 threads.
Compressing objects: 100% (3/3), done.
Writing objects: 100% (3/3), 328 bytes, done.
Total 3 (delta 2), reused 0 (delta 0)
To git@github.com:eifion/vcr.git
 * [new branch]      readme-contributing-link -> readme-contributing-link

Esto añadirá la rama a nuestro repositorio en Github.

Cuando ahora visitemos nuestro repositorio en Github podremos cambiar la rama actual a la que tenemos recién creada.

Luego podemos hacer clic en “Pull Request” para enviar nuestra solicitud de cambio al dueño original. Tendremos que rellenar un formulario explicando los cambios que hemos hecho, tras lo cual podremos enviar nuestra petición.

Esto es todo lo que hace falta para enviar una petición de cambio a un proyecto de código abierto en Github. Si nuestro cambio es aceptado, pondrá las cosas más fáciles para el siguiente que quiera colaborar. Ahora es tu turno.