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

Esta guía asume que usted ha leído: Instalando Git y que ya ha configurado su máquina con un cliente Git de su elección.

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

Todas las ramas del repositorio original se también se bifurcan, usted recibe un clon exacto del repo bifurcado.

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

Ahora necesita llevar esta bifurcación a su máquina loca para hacer los cambios. Abra el Cliente de Git de su elección (Instalando Git) y ``clonar``su bifurcación en su máquina local. El cliente le preguntará por una carpeta para almacenar todo. Segundo paso terminado, ¡bien hecho!

Nota

La mayoría de los pasos pueden hacerse a través de la GUI de su elección. Si tiene experiencia con una interfaz de línea de comando, entonces puede utilizarla también. Cada paso le mostrará los comandos requeridos para conseguir el resultado deseado.

Alternativamente puede hacer esto a través de CLI (Interfaz de Línea de Comando, CMD o powershell en Windows). Tenga en cuenta que necesita crear una carpeta en la que todo se clona antes de escribir este comando:

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]

Esto creará una rama con el nombre de su elección y cambiará a ella. Todos los cambios que realizará van a estar en esta rama. Si necesita cambiar a otra rama (por ejemplo master), simplemente vuelva a utilizar este comando. ¡Tercer paso hecho! ¡Buen trabajo hasta ahora! Para obtener una visión general de sus ramas, simplemente debe echar un vistazo a su cliente de git o usar:

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

Cuando esté terminado, necesita agruparlos en un único paquete (un commit) y colocarlos en la rama. Otra vez su cliente de git le ayudará. Agregue un nombre significativo a su confirmación y una breve descripción si es necesario. Esto también puede hacerse a través de CLI:

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

Puede ir a la página de sus bifurcaciones en GitHub.com (debe haber un aviso en en la parte superior de su página de bifurcación que lo guíe), o puede utilizar su cliente GitHub para crear una solicitud de extracción. El oficial GitHub para clientes Win usa la esquina superior derecha de la ventana para esto.

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

Digamos que finalizó sus adiciones al repo, y supongamos que ha realizado 137 commits mientras lo hace. Sus historial de commit ciertamente se verá desordenado. Sería una pena que todos estuvieran registrados en el repo, ¿no es así? Demasiados commits triviales también desordenan el historial de commits del proyecto. Afortunadamente Git tiene una buena herramienta para evitar esto, es denominada un rebase. El rebasamiento puede tomar sus 137 pequeños commits y solo convertirlos en un gran commit. Asombroso, ¿cierto? En lugar de reinventar la rueda, le daremos un enlace a un tutorial de combinación muy breve y fácil de comprender:

Gitready: Combinando con Rebase

Esto es lo que hace, muy bien visualizado:

Configuración de un mando a distancia

Naturalmente el repo original es la fuente directa de su bifurcación y su bifurcación es la fuente de su clon local. Sin embargo el repo original no es la fuente directa de su clon. Este no es un problema en primera instancia, pero le impide actualizar su clon a los últimos cambios en su repo original. Si su configuración del repo original es un mando a distancia (leer: «fuente») de su clon, podrá tomar todos los cambios realizados en este repo y aplicarlos en su clon local. Mire a continuación para ver como funciona la toma y las actualizaciones.

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.

Un rebase exitoso requiere varios pasos:

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!