#300 Contributing to Open Source

Nov 21, 2011 | 9 minutes | Testing, Tools

GitHub makes it easier than ever to contribute to open source with pull requests. Here I show how to submit a pull request to the VCR project.

Click to Play Video ▶

Download:
mp4Full Size H.264 Video (27.3 MB)
m4vSmaller H.264 Video (13.3 MB)
webmFull Size VP8 Video (12 MB)
ogvFull Size Theora Video (37.8 MB)

Github vous permet très facilement de contribuer à un projet Open Source. Dans cet épisode, nous allons vous montrer comment faire en soumettant un pull request au projet VCR. Nous avons déjà parlé du projet VCR dans l'épisode 291 ; ce gem permet d'enregistrer les intéractions HTTP et de les lancer en arrière plan afin d'accélérer les tests. Myron Marston, l'auteur du gem VCR, est très réactif concernant les contributions extérieures.

Imaginez que nous ayons trouvé un problème avec ce gem et qu'on aimerait contribuer en proposant un patch. La première chose à faire est de regarder la partie 'issues' (sur github) afin de s'assurer qu'il n'a pas déjà été abordé. Si le projet possède une mailing-list, il est conseillé de chercher si des éléments existe à propos de ce problème. Pour les gros changements, il est préférable d'en discuter afin de voir si le changement est nécessaire.

Fork It!

Une fois que nous sommes prêt à travailler sur ce patch, la première chose à faire est de fork le projet. Pour ce faire, nous devons nous rendre sur sa page github et de cliquer sur le bouton "Fork". Cela nous fournit une copie du dépôt en quelques secondes. Une fois terminé, nous pouvons visiter notre nouveau fork, obtenir son URL et donc le cloner.

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

Comme nous vennons de cloné le dépôt, nous pouvons voir les branches qu'il possède

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

Nous pouvons donc remarquer qu'il y a une branche pour la version stable de la version 1, qui est la version courante du gem. La branche master correspond à la version 2 qui est actuellement en pre-release. Une chose importante à garder en tête : la version du gem que vous utilisez est souvent différente de celle sur laquelle vous travaillé.

Lors de la mise en place de votre environnement de développement pour un projet précis, il est conseillé de se référer à sa documentation. Dans notre cas, il y a une section "development" dans le fichier README qui nous dit que les ``pull request`` sont les bienvenus mais que tous les changements doivent être totalement couverts par des tests. Le README ne contient pas d'instructions sur le lancement de la suite de test mais il est encourageant de voir que Travis CI affirme que les tests sont actuellement tous passés.

Le projet possède un Gemfile, il utilise donc Bundler pour gérer ses dépendances. Nous devrions être capable de les installer en exécutant bundle install mais une erreur se produit lorsque nous essayons. C'était à prévoir puisque tous les environnements de développement sont différents.

L'erreur que nous pouvons apercevoir est liée au gem rb-fsevent. Une petite recherche sur Internet nous confirme que cela vient de notre installation. Nous utilisons actuellement GCC Installer à la place de l'installation complète de Xcode et c'est ce qui pose problème. Le problème a été résolu dans rb-fsevent mais n'est pas encore disponible dans la version stable. Nous allons donc résoudre ce problème en utilisant une version particulière de rb-fsevent dans notre Gemfile, nous utiliserons la version pre-release.

          /Gemfile
        
# 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

Maintenant, lorsque nous lançons ``bundle`` tout semble être correct.

Lancer les tests

Ensuite, nous allons essayer d'exécuter les tests du gem. Ils sont souvent définis comme tâche Rake par défaut, nous pouvons donc lancer les tests en exécutant rake. Cependant, il vaut mieux utiliser bundle exec rake.

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

Les tests passent malgré quelques problèmes en suspens. Après que les tests ont été lancés, c'est au tour des scénarios Cucumber d'être exécutés. Nous obtenons une erreur avec un long message d'erreur, l'essentiel du message est "no such file to load -- spec". Il semble que nous ayons oublié une dépendances que Bundle n'a pas géré.

After some investigation it turns out that this project uses Git submodules so to get it working we need to run these two commands.

Après quelques recherches, il s'avère que ce projet utilise des Sous-modules de Git. Il faut donc les installer en utilisant les deux commandes suivantes :

          terminal
        
$ git submodule init
$ git submodule update

Ceux-ci seront copiés pour nous dans le dépôt des sous-modules. Nous pouvons alors relancer les tests et vérifier qu'ils passent. Cette fois oui :)

Apporter des changements

Nous avons eu quelques soucis pour faire passer les tests mais nous avons réussis. Encore une fois, ceci vient du fait que chacun possède son propre environnement de développement. On aurait pu gagner du temps si la documentation avait été meilleure concernant la mise en place du projet.

Notre premier pull request sera donc d'embellir cette documentation afin de mettre en place un environnement de développement fonctionnel. Cette documentation se trouve dans le README.
Il s'avère qu'il existe déjà une page Wiki destinée à la contribution au projet VCR mais elle contient seulement les bases de sa mise en place. Nous allons donc éditer cette page pour y ajouter des informations baséee sur les problèmes que nous avons rencontrés. Une fois ces changements effectués nous pouvons alors proposer notre pull request qui ajoute un lien dans le README vers ce guide.

Avant de faire des changements, nous allons nous assurer que notre répertoire de travail est propre.

          terminal
        
$ 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")

Nous avons modifé le Gemfile, donc nous devons revenir sur ce changement avant d'aller plus loin.

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

It’s a good idea to setup a separate Git branch for each pull request we want to make so we’ll do that now.

          terminal
        
$ git checkout -b readme-contributing-link

Maintenant, nous pouvons faire nos changements. Dans la section "development" du README.md nous allons y ajouter un lien vers la page Wiki que nous avons changée.

          /README.md
        
## 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.

Une fois que cela est fait, nous pouvons lancer git diff afin de visualiser les changements que nous venons d'appliquer. Si cela nous convient, nous pouvons commit les changements :

          terminal
        
$ 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

Lorsque nous visitons notre dépôt (qui est, je vous rappel, un fork) nous pouvons changer la branche actuelle par celle que nous venons d'ajouter.

Maintenant cliquez sur "Pull Request" pour proposer nos changements au propriétaire du dépôt. Github nous renvoit sur un formulaire permettant d'expliquer les changements apportés puis de l'envoyer

Voilà, c'est tout ce que nous avons besoin de faire pour proposer un pull request à un projet open source hébergé sur Github. Si il est accepté cela sera plus facile pour les personnes suivantes voulant contribuer au projet.
Maintenant, c'est votre tour !