¡La versión 2.0 de Play ya está lista! Ayúdanos a traducir la documentación de la útlima versión y sigue nuestro progreso.

Manuales, tutoriales & referencias

Consulte

Contenidos

Elija la versión

Buscar

Busque con google

Libros

Guía para colaborar con un proyecto en github

Al igual que la documentación original de Play!, este proyecto se encuentra alojado en github, a fin de que la comunidad de usuarios de play pueda colaborar con nosotros en la traducción y actualización de la documentación del framework.

Para facilitar esta tarea, hemos elaborado esta guía que te permitirá crear tu propia versión del sitio (fork), instalarla en tu estación de trabajo (clone), hacer modificaciones y contribuciones trabajando localmente, y enviarnos pedidos (pull requests) para integrar tu trabajo en la versión de producción de playdoces.

Trabajando con github

El esquema de trabajo que nos propone github puede parecer confuso al principio, pero en realidad es bastante simple, tan sólo hay que tener presente que uno está trabajando con tres repositorios distintos y entender el rol que cada uno cumple.

Repositorio upstream: es el repositorio en github de la aplicación con la cual vamos a colaborar. En nuestro caso el repositorio está en https://github.com/opensas/playdoces y la aplicación es http://playdoces.appspot.com. No podremos hacer ningún cambio directamente sobre este repositorio, ya que no tendremos permisos de escritura sobre el mismo. Lo que haremos es crear nuestra propia copia (fork) del mismo.

Repositorio origin: es nuestra copia del repositorio que forkeamos alojada en github. A este repositorio enviaremos los cambios que efectuaremos en nuestro repositorio local.

Repositorio local: es el repositorio local que tendremos en nuestra propia estación de trabajo.

Comunmente realizaremos los cambios trabajando en nuestro repositorio local. Cuando hayamos confirmado (commit) nuestros cambios localmente, los enviaremos (push) a nuestro repositorio origin alojado en github. Luego haremos un pedido (pull request) al repositorio upstream solicitándole que integre los cambios del repositorio origin.

Este es el esquema general de trabajo con github, que nos servirá no sólo para colaborar con playdoces, sino con cualquier proyecto libre alojado en github, incluido el propio play framework.

Crear una cuenta en github

Lo primero que tendremos que hacer es navegar a https://github.com/signup/free y crear una cuenta gratuita en github, en nuestro ejemplo hemos creado la cuenta traductor-play.

Luego deberás instalar git en tu equipo y configurar tu cuenta siguiendo las instrucciones para linux o las instrucciones para windows, según el sistema operativo que estés utilizando.

Hacer un fork del repositorio upstream

Navega al sitio de github e ingresa con tu usuario y password. Luego tendrás que navegar a https://github.com/opensas/playdoces y hacer click en “fork”. Con esto ya habrás creado tu repositorio origin, que en nuestro caso se encuentra en https://github.com/traductor-play/playdoces.

Clonar nuestro repositorio origin en un repositorio local

En nuestra estación de trabajo ejecutamos las siguientes instrucciones (debes ajustarlas según tu nombre de usuario, remplazando [tu_cuenta_de_github] por tu nombre):

cd ~
mkdir apps
cd apps
git clone git@github.com:[tu_cuenta_de_github]/playdoces.git

De esta manera nos quedará la aplicación playdoces instalada en ~/apps/playdoces. Para ejecutar la aplicación y traducir la documentación sigue los pasos en la guía para traducir play

Coordinar nuestro trabajo con el resto de los traductores

A fin de evitar que más de un traductor esté trabajando en las mismas páginas es conveniente utilizar el sistema de incidentes que nos provee github. Simplemente debemos dirigirnos al sitio del repositorio upstream https://github.com/opensas/playdoces/issues/ y crear un nuevo incidente, poniendo el nombre de la página que vamos a traducir y entre corchetes nuestro nombre de usuario en github.

Por ejemplo, si quisiéramos traducir la página lib.textile, primero nos fijaríamos en los incidentes para asegurarnos que nadie esté trabajando en ella, y luego cargaremos uno nuevo con el siguiente texto lib.textile [traductor-play].

Guardar los cambios y enviar nuestras traducciones

Una vez que hemos terminado de traducir algún archivo, vamos a querer enviarlo a los administradores de playdoces para que sean incluidos en producción. Para ello tendremos que confirmar los cambios en nuestro repositorio local, actualizar nuestro repositorio origin en github, y hacer un pedido para que estos cambios sean incluido en el repostiorio upstream.

Mediante el comando git status podemos ver los archivos que hemos modificado localmente. Con el comando git add, le indicamos a git cuáles son los archivos que vamos a querer confirmar (commit). Con git commit confirmamos los cambios en nuestro repositorio local y finalmente, con git push origin master subimos los cambios locales a nuestro repositorio origin. Situados en el directorio del repositorio, en nuestro ejemplo ~/apps/playdoces, estos serían los comandos que deberemos ejecutar:

git status
git add .
git commit -m "traduje una nueva página"
git push origin master

En caso de haber cargado un incidente para esa página, es súmamente útil incluir el texto fixes seguido del signo # y el número del incidente en el texto que utilizamos al hacer el commit, de la siguiente manera git commit -m "fixes #34 - traduje una nueva página". De esta manera github relacionará nuestros cambios con el incidente y lo cerrará automáticamente.

Luego navegamos a nuestro repositorio origin, en este caso https://github.com/traductor-play/playdoces, en donde ya deberías poder ver los cambios que acabas de impactar. Para solicitar al repositorio upstream que integre nuestros cambios simplemente hacemos click en el botón pull request. Y ahora tan sólo resta esperar que los administradores del repositorio upstream (en este caso nosotros) revisen los cambios y los impacten en la aplicación.

Manteniendo nuestros repositorios actualizados

A medida que sigamos trabajando, querremos mantener actualizados nuestros repositorios (local y origin) con los cambios del repositorio upstream. Para eso configuramos el repositorio upstream como un repositorio remoto (remote) vinculado a nuestro repositorio local. Situados en el directorio del repositorio, en nuestro ejemplo ~/apps/playdoces, deberemos ejecutar:

git remote add upstream git@github.com:opensas/playdoces.git

Cuando querramos traer las actualizaciones de upstream, deberemos ejecutar:

git fetch upstream
git merge upstream/master