Como usar Git(Hub)

Si quiere ayudar a crear Sponge, tiene una increíble adición a la API o quiere mejorar nuestros Docs, entonces necesitará familiarizarse con git y GitHub. Si está familiarizado con bifurcaciones, ramificaciones, problemas, solicitudes de extracción y confirmaciones, entonces omita este tema. Si no tiene idea de lo que estamos hablamos, entonces continúe leyendo.

Nota

This guide assumes that you’ve read Instalando Git and that you’ve already setup your machine with a Git client of your choice.

El Concepto Básico de Git y GitHub

Git permite a muchos desarrolladores diferentes crear una pieza única de software al mismo tiempo. GitHub es un sitio web donde desarrolladores pueden colaborar y compartir sus trabajos con otros. GiyHub se basa en Git para la gestión de dicho trabajo.

Truco

Si usted no está familiarizado con el vocabularios de Git y GitHub, eche un vistazo a la página del glosario en GitHub.

En este caso el repositorio se llama SpongePowered, tiene dos ramas denominadas master y feature 1 y también algunas confirmaciones en ambas ramas.

Pongamos estos términos en contexto, comenzando con el Repositorio. El repositorio (abreviado: repo) es un lugar donde un proyecto almacena sus archivos. Los repositorios SpongePowered se localizan en GitHub. Sin embargo, este repo tiene algunas restricciones de acceso para preservarlo de cambios no deseados o maliciosos. No puede simplemente hacer cambios por usted mismo, ya que el repo es de Solo Lectura para los usuarios regulares. Ahora puede preguntarse como se supone que puede presentar propuestas y cambios. Bueno, ahí es donde entran en juegos los forks. Puede hacer una copia a los repositorios de SpongePowered y hacer sus cambios allí. Cuando haya terminado, lo abre como una solicitud de extracción (PR) en nuestro repositorio. Sus adiciones y cambios propuestos pueden ser revisados y el personal le dirá si algo está mal o necesita mejoras y eventualmente unirá el PR final.

Este es un breve resumen del procedimiento descrito anteriormente, antes de entrar en detalle:

Bifurcación del repo de su elección
Clonarlo en su máquina local
Crea una nueva rama
Haga los cambios deseados
Probar si todo funciona
Confirmar los cambios
Sincronizarlos a GitHub
Proponer los cambios en un PR al Repo SpongePowered
Modificar a su PR si es necesario
Su PR se convierte en Master por el personal

¡Detalles por favor!

1. Bifurcando un Repo

Nota

Este paso solo es requerido si no tiene derechos de inserción en el repo en el que está haciendo cambios. Si está trabajando en su propio repo, una bifurcación no es requerida. Omita este paso y clonar directamente. Si está realizando cambios a Sponge y usted no es personal, este paso es requerido.

Ahora que conoce el concepto básico, discutamos los detalles. Primero necesita bifurcar el repositorio al que quiere hacerle cambios. Esto puede hacerlo en GitHub.com, donde encontrará un botón de Bifurcación en la parte superior de la página de repositorios. Después de presionarlo, GitHub hará algún trabajo y presentará un clon del repo orginal. Notará que el clon está ahora localizado en YourGitHubAccount/ClonedRepoName. Bien, primer paso completado.

Nota

All branches from the original repository will get forked too, you receive an exact clone of the forked repo.

2. Clonación de la Bifurcación en su Máquina Local

Now you need to get this fork to your local machine to make your changes. Open the Git Client of your choice (Instalando Git) and clone your fork to your local machine. The client will ask you for a folder to store everything in. Second step finished, well done!

Nota

Most steps can be done via GUI of your choice. If you’re experienced with a command line interface, then you can use it too. Each step will show you the required commands to achieve the desired result.

Alternatively, you can do this via CLI (command line interface, CMD or powershell on windows). Note that you need to create the folder everything is getting cloned to yourself before typing this command:

git clone git://github.com/YourGitHubAccount/ClonedRepoName.git

3. Creando una Nueva Rama

Ahora que tiene una copia local de su bifurcación, es hora de crear una rama para trabajar. Las ramas fueron diseñadas para ser capaces de desarrollar y probar diferentes características o adiciones al mismo tiempo, sin causar problemas y errores debido a las interferencias de las adiciones. Se recomienda enérgicamente que no realice cambios en la rama master. En su lugar, cree una nueva rama usted mismo (con un nombre razonable) y realice sus cambios allí.

Esto implica que necesitamos crear una rama primero, ¡así que vamos! Puede hacerlo a través de su cliente (debe haber un botón crear rama en algún lugar), o puede usar el CLI con git:

git checkout -b [name_of_your_new_branch]

This will create a branch with the name of your choice and switch to it. All changes you’re about to make will be on this branch. If you need to switch to another branch (for example master), just reuse this command. Third step done! Good job so far! To get an overview of your branches, just have a look at your git client or use:

git branch

Ahora es momento de realizar sus cambios. Utilice el editor o IDE de su elección para hacer esto.

4. Comprobar si sus Cambios Funcionan

Para SpongeAPI y las implementaciones tiene que ejecutar gradle compileJava. Continúe al siguiente paso si finaliza sin errores. Si no lo hace, realice las correcciones apropiadas y vuelva a intentarlo.

Para SpongeDocs puede enviar su PR. Se construirá automáticamente y mostrará posibles errores. Otra opción es construir localmente los Docs. Eche un vistazo a Readme.md en los Docs para obtener más instrucciones.

5. Confirmar los Cambios

When you’re done, you need to bundle them into a single package (a commit) and get them into the branch. Again, your git client will help you out. Add a meaningful name to your commit and a short description if needed. This can be done via CLI too:

Primero reúna todos los archivos y carpetas que quiera colocar en un commit:

git add <file>
git add <folder>

Ahora que los archivos se agregaron a su lista de cambios que quiere incluir en el commit, solo haga

git commit

Abrirá una ventana de texto, donde puede agregar un mensaje si lo desea. Eche un vistazo a la imagen a continuación. Notará que sus commits son almacenadas localmente y no en su bifurcación en GitHub.

Nota

Puede tener múltiples commits en un PR. Solo tiene que ir adelante y cambiar todo lo que necesite y confirme los cambios. Puede fusionar los commits en un solo commit luego.

Así que ahora, se realiza el sexto paso. ¡Vamos allí!

6. Sincronizar a GitHub

Ahora necesitamos obtener los cambios de su bifurcación en GitHub. Todo lo que ha realizado hasta ahora solo se almacena localmente en este momento. Como siempre, puede utilizar su cliente de git para hacerlo (hay un botón en algún lugar en su GUI), o puede hacerlo a través de CLI:

git push <remote> <branch>

En este caso debería ser:

git push origin feature/YourFeature

7. Proponer los cambios en un PR al Repo SpogePowered

You can either go to your forks page on GitHub.com (there should be a notice at the top of your forks page to guide you), or you can use your GitHub client to create a pull-request. The official GitHub for Win client uses the top right corner of the window for this.

8. Modificar su PR si es necesario

Si queremos que realice cambios en su PR, solo haga más commits en la rama creada anteriormente. Los commits adicionales se agregarán a su PR automáticamente.

9. Su PR es incorporado

Eso es. ¡Estamos listos! ¡Gran trabajo!

Git Avanzado

Combinando con Rebase

Let’s say you have finished your additions to the repo, and let’s pretend that you made 137 commits while getting it done. Your commit history will certainly look cluttered. It would be a shame if they were all recorded into the repo, wouldn’t it? Too many trivial commits also clutters the project commit history. Fortunately, Git has a nice tool to circumvent this, it’s called a rebase. Rebasing can take your 137 small commits and just turn them into one big commit. Awesome, isn’t it? Instead of reinventing the wheel, we’ll just pass you a link to a very short and easily understandable squashing tutorial:

Gitready: Combinando con Rebase

Esto es lo que hace, muy bien visualizado:

Configuración de un mando a distancia

Naturally the original repo is the direct parent of your fork and your fork is the direct parent of your local clone. However, the original repo isn’t the direct parent of your clone. This isn’t a problem in the first place, but it prevents you from updating your clone to the latest changes on the original repo. If you setup the original repo as a remote (read: «parent») of your clone, you’ll be able to grab all changes made to this repo and apply it to your local clone. Look below to see how grabbing and updating works.

Muy bien. Este paso se realiza a través de CLI ya que las mayoría de las GUIs faltan en esta funcionalidad (bastante avanzada):

git remote add upstream https://github.com/ORIGINAL_OWNER/ORIGINAL_REPOSITORY.git

Si no está seguro si funcionó el intento o si quiere verificar que mandos a distancia están configurados actualmente, puede comprobarlo a través de:

git remote -v

la salida debería verse así:

origin    https://github.com/YOUR_USERNAME/YOUR_FORK.git (fetch)
origin    https://github.com/YOUR_USERNAME/YOUR_FORK.git (push)
upstream  https://github.com/ORIGINAL_OWNER/ORIGINAL_REPOSITORY.git (fetch)
upstream  https://github.com/ORIGINAL_OWNER/ORIGINAL_REPOSITORY.git (push)

Nota

Si ve la advertencia fatal: La rama actual SuNombreDeRama no tiene rama ascendente., entonces la rama puede no estar en la ascendencia remota. Esto puede pasar si esta es la primera vez que está integrando un commit para la nueva rama. Para integrar la rama actual y configurar la ascendencia remota, utilice integrar git --configurar-origen ascendente SuNombreDeRama.

Rebasamiento

Digamos que realizó algunos cambios a su rama deseada, pero al mismo tiempo alguien más actualizó el repo. Esto significa que su bifurcación y su clon están desactualizados. Esto no es un gran problema, pero para evitar problemas al fusionar sus adiciones más adelante, se le aconseja encarecidamente que rebase sus cambios contra las últimas modificaciones en el repo original. Si no ha configurado todavía el repo remoto, hágalo antes de intentar el rebase.

A successful rebase requires several steps:

1. Obtener los cambios en el Repo Remoto

Primero necesita obtener los cambios en el repositorio remoto. Esto se hace (otra vez) a través de CLI:

git fetch upstream

Esto agregará todos los cambios de la ascendencia remota y los coloca en una rama temporal ascendencia/master.

2. Combinar los cambios remotos localmente

Ahora necesitamos que seleccione nuestra rama local master:

git checkout master

Después de eso combinaremos los cambios que se incluyen en upstream/master en nuestra rama local master:

git merge upstream/master

Muy bien, esto es lo que hemos hecho hasta ahora:

3. La Rama Local de Rebase contra el Master Actualizado

El siguiente paso es el rebase de la rama local en la que está trabajando contra el master local. Necesitamos cambiar su rama de trabajo (aquí: feature/yourfeature) y luego realizar un rebase. Esto se hace a través de:

git checkout feature/yourfeature
git rebase master

Esto rebobinará su rama, agregará los commits del master y luego aplicará sus propios cambios. El resultado se ve así:

4. Integre todo a su Bifurcación

La última cosa que necesitamos hacer es integrar todo a la bifurcación. Si ya ha creado un PR, se actualizará automáticamente:

git checkout master
git push -f
git checkout feature/yourfeature
git push -f

¡Lo hizo, increíble! ¡Buen trabajo y bien hecho y gracias por volar Rebase-Air!