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.

Repo Overview

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:

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

¡Detalles por favor!

1. Forking a 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.

Repo forking

2. Cloning the Fork to Your local Machine

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
Repo cloning

3. Creating a New Branch

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
Branches

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

4. Test if Your Changes Work

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. Commit the Changes

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í!

Committing

6. Sync to 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
Pushing commits

7. Propose the Changes in a PR to the SpongePowered Repo

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.

PRs

8. Amend Your PR if Necessary

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. Your PR Gets Pulled

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:

Squashing commits

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.

Setting up a remote

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. Fetch the Changes on the Remote Repo

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. Merge Remote Changes locally

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:

Rebasing 1

3. Rebase Local Branch against Updated Master

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í:

Rebasing 2

4. Push Everything to your Fork

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
Rebasing 3

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