Working with git and github/es

Under Construction

Introducción

Este documento te proporcionará información acerca de como contribuir con el CMS de Joomla! con la ayuda de Git y GitHub. Si te gusta hacer un cambio simple (un sólo archivo), es más fácil el uso de esta documentación: Uso de la interfaz de usuario Github para Hacer Solicitudes de Extracción Si deseas añadir cambios más complejos o simplemente está interesado en esto, ¡sigue leyendo!

¿Qué son Git y GitHub?

Git es un sistema de control de versiones distribuido. Es un sistema que registra los cambios en los archivos y mantiene un historial de los mismos. Siempre podrás mirar una versión anterior del código y restablecer los cambios si lo deseas. Debido al historial, Git es muy útil cuando trabajas con muchas personas en un mismo proyecto.

Así es como GitHub puede ser utilizado. GitHub es un sitio web que ayuda a manejar Proyectos Git de una manera visual. Como propietario de un proyecto puedes cambiar el código y comparar las diferentes versiones. Como usuario del proyecto puedes contribuir haciendo una Solicitud de Extracción. Una Solicitud de Extracción es una petición al propietario para sacar un poco de código del proyecto. Estás ofreciendo un trozo de código (tal vez una solución a un error) y preguntas si el propietario del Proyecto desea usarlo. Si al dueño le gusta, lo puede combinar (agregar) a su proyecto.

Joomla! utiliza GitHub y Git para mantener su código. Todo el mundo puede contribuir con el software de Joomla!. La dirección URL del proyecto CMS de Joomla! en GitHub es: https://github.com/joomla/joomla-cms

Primeros pasos

Inscribirse en GitHub e instalar Git

First, you will need to register at GitHub. It's free and easy to do. Just follow the provided steps.

Uno estamos inscritos, necesitamos instalar Git. La última versión de Git se puede encontrar en http://git-scm.com. Descargamos y abrimos el instalador. Git es un programa CLI( CLI significa Interfaz de Línea de Comandos, por sus siglas en ingés). Al principio esto puede ser confuso y un poco intimidante pero este documento te guiará en todo el proceso.

Si no eres un usuario avanzado, sólo tienes que ejecutar el instalador y presionar el botón "siguiente" hasta que el programa se termine de instalar. Git no dañara tu sistema. Más tarde lo puedes quitar al igual que otros programas si lo deseas.

Una vez que hemos instalado Git, abrimos el programa que se llama "Git Bash". Una comando en línea se abrirá. Vamos a decirle a Git cual es nuestro nombre y correo electrónico. Git utilizará esta información para contribuir a un proyecto. Con los siguientes comandos damos a Git esa información:

git config --global user.name "Your name"
git config --global user.email youremail@mail.com

En los comandos anteriores y todas las demás órdenes que se imparten en esta documentación, cada línea es un nuevo comando. Así que escribes la primera línea, presiona enter y, a continuación, escribes la segunda línea y presiona enter.

Ahora estamos listos para usar Git e ir más allá con la creación de nuestra instalación de prueba.

Configurar una instalación de prueba

Para nuestra instalación de prueba necesitamos un programa servidor web, para que podamos instalar y ejecutar Joomla! en nuestro equipo. Hay varios programas que pueden hacer esto, por ejemplo MAMP o XAMPP. Descarga e instala alguno de ellos.

Después de la instalación de un programa (yo uso MAMP en esta documentación), vamos a instalar la última versión de Joomla!. En nuestro caso, la última versión de Joomla! no es la última versión estable. La última versión de Joomla! es la presentación de la rama en GitHub. En primer lugar, permítanme explicar un poco más acerca de GitHub.

Bifurcar y Clonar Joomla!

On GitHub you can find projects, so called Repositories. Inside a project you might find several versions. Such a version is called a Branch. Joomla! has the following branches:

• Presentación: Esta rama contiene las últimas correcciones de errores y nuevas características de Joomla!
• Maestro: Esta rama es la versión estable actual de Joomla!
• 3.5-dev This branch contains the files for Joomla! 3.5, which is not stable at this writing.

On our test location we going to use the Staging branch but if we should use this branch directly we have problem. We cannot modify this branch because we are not the owner of it. We are going to make a copy of it. On GitHub this is called a Fork. We are the owner of that copy so we can modify it. After modifying we compare our fork with the original project. Then we can make a Pull Request for the changes we've made. More about that later. You can Fork a branch by pressing the Fork button on the Joomla! CMS Github Repository. This button is located at the right top of the page.

After forking, we are going to install Joomla! on our local Web server. Go to the folder were you can run files on you Web server. Most of the program use a folder called htdocs. Once we are inside that folder, press the right mouse button an click on: "Git Bash Here". The command line will open for this location.

Type the following command to download the files from your Fork of the Joomla! CMS to your computer. Please replace username with the username you are using on GitHub.

git clone https://github.com/username/joomla-cms.git

Para todas las órdenes que se imparten en esta documentación, tienes que abrir Git a través de los pasos descritos anteriormente. Por favor, recuerda esto para otros comandos en esta documentación.

Once Git is ready, open your browser and go to the installation on your localhost. Usually the URL is something like: http://localhost/joomla-cms. You will now see the default Joomla! installation process.

Instalar Joomla!

La instalación de Joomla! en nuestro espacio local de prueba es casi la misma que una instalación normal. Hay dos pequeñas diferencias.

For the database settings, the password and username are default. Most often the username is root and the password is also root or there is no password. If you still can't connect to the database, look in the manual for your local Web server for the username and password.

The last difference is the final step of the installation. Normally we must delete the installation folder to go further to the back-end or front-end of Joomla!. For a test installation we can skip this part and go directly to the back-end or front-end. Don't remove the installation folder. It can be very useful when we have to install Joomla again.

Hacer Cambios

Ahora es el momento de hacer nuestros cambios en los archivos de Joomla!. Todos los cambios que hagamos, van a ser registrados y supervisados por Git. En cualquier momento puedes escribir el comando git status para ver que archivos fueron modificados o están sin seguimiento. Sin seguimiento, significa que el archivo en esa ubicación es nuevo para Git.

Si has cometido un error o quieres restablecer un archivo puedes utilizar este comando:

git checkout path/to/file

Si desea quitar todos los cambios realizados puedes utilizar los siguientes comandos:

git checkout .
git clean -f -d

El primer comando restablece todos los archivos. El segundo comando elimina archivos y carpetas sin seguimiento.

Poner el cambio a nuestra bifurcación

Después de hacer nuestros cambios, tenemos que subirlos a nuestro repositorio en GitHub. Después de eso, se puede hacer una Solicitud de Extracción con nuestros cambios.

Subir los cambios que se llama push en términos Git. Antes de que podamos hacer eso, tenemos que hacer algo muy importante. Debemos crear una nueva rama para que nuestros cambios (Una rama es una versión de nuestro proyecto, ¿recuerdas?). Si no lo hacemos y ponemos nuestro cambio directamente en la presentación de la rama, la primera vez no será un problema. Pero si hemos hecho cambios una segunda vez y el cambio que hemos realizado la primera vez no se combinan, todos los cambios serán registrados como nuevos cambios.

Así que el primer comando que se va a ejecutar es crear una nueva rama. Para evitar el problema descrito más arriba. Reemplaza el nombre de la nueva rama con el nombre de la nueva rama. Este nombre debe ser corto, sólo puede contener letras minúsculas y números. NO contiene espacios. En lugar de espacios usa - (menos)

git checkout -b name-new-branch

El siguiente comando le dice a git, que todos los cambios son buenos y están listos para utilizarse.

git add --all

El siguiente comando agrega nuestro cambio a la rama. Por favor, reemplaza el mensaje con una breve descripción de los cambios. Esta descripción será el título de la solicitud de extracción que vamos a hacer.

git commit -m "description"

El último comando push (carga) los cambios de nuestra bifurcación. Por favor reemplaza el nombre de la nueva rama con el nombre de la rama creada un par de pasos antes.

git push origin name-new-branch

Comparar las bifurcaciones y hacer una solicitud de extracción

Después de subir nuestro cambio a GitHub, ir a la bifurcación del CMS Joomla!.

Información Extra

Ya que la presentación de la versión de Joomla! puede cambiar en cualquier momento, es muy útil tener la posibilidad de mantener nuestra bifurcación actualizada. Podemos hacerlo mediante la adición de un mando a distancia para nuestro proyecto bifurcado:

git remote add upstream https://github.com/joomla/joomla-cms.git

Ahora hemos añadido una llamada remota llamado "upstream". Con el siguiente comando Git busca nuevas contribuciones (commits) en la presentación de la rama que no tenemos en nuestra bifurcación. Si se encuentra alguna, se va a añadir a nuestra bifurcación:

git pull upstream staging

Los cambios por ahora sólo se ha realizado en nuestra bfurcación local. Para subirlos a GitHub utiliza el siguiente comando:

git push