Este documento es una guía simple y básica para llevarte de "¿Qué es Git en el mundo?" a "¡Todo el mundo debería usar mi nueva hoja de personaje!" lo más rápido posible, sin tratar de enseñarte todas las complejidades que el sistema es capaz de hacer. Git es un software de control de versiones, pero esta guía ignorará por completo cómo puedes usarlo para rastrear tus cambios y se centrará únicamente en mover tus actualizaciones a los repositorios maestros de Roll20. La sección "Más información" contiene enlaces a guías sobre cómo funciona Git/GitHub que son generales en su naturaleza.
¿Qué es Git/GitHub?
Git es un software que instalas localmente en tu computadora y que se encarga del control de versiones por ti. GitHub es un servicio de alojamiento para repositorios de Git. Entonces no son lo mismo: Git es la herramienta, GitHub es el servicio para proyectos que usan Git. Comparación breve.
Hay varias formas diferentes de usar Git. Git es muy poderoso, pero para aprovechar al máximo sus capacidades, debes aprender a usar la línea de comandos (cómic xkcd). La sección "Más información" al final tiene lecturas adicionales sobre la línea de comandos para aquellos interesados. Sin embargo, todo lo que este documento te guiará a través se puede hacer utilizando solo la interfaz gráfica de GitHub Desktop (muy buena para mantener sincronizado el disco duro de tu computadora con tu repositorio - Ver "Clonar tu repositorio" a continuación) y las herramientas web de GitHub, ambas herramientas simplificadas para usar Git subyacente.
Configuración de GitHub
Crea tu cuenta
Para usar GitHub, necesitas tener una cuenta en su sitio web. Puedes crear una cuenta de pago o puedes crear una cuenta gratuita. A menos que planees crear una gran cantidad de proyectos que no quieras compartir con el mundo, no hay razón para crear una cuenta de pago: la única diferencia entre los diferentes niveles de precios es la cantidad de repositorios privados que se te permite tener. Todos, incluidas las cuentas gratuitas, tienen un número ilimitado de repositorios públicos.
Te ocuparás de los Repositorios maestros de Roll20 para roll20-character-sheets y/o roll20-api-scripts que son repositorios públicos. También crearás una bifurcación de estos repositorios, que también podrían ser públicos, así que para tus usos en Roll20, una cuenta gratuita es todo lo que necesitas.
BIFURCAR el Repositorio oficial de Roll20
Untenedores una copia de un repositorio. Bifurcar un repositorio te permite experimentar libremente con cambios sin afectar al proyecto original.
Bifurcar es fácil de hacer utilizando las herramientas web de GitHub. Haz clic en el botón Fork en el repositorio oficial ubicado enhttps://github.com/Roll20/roll20-character-sheetsohttps://github.com/Roll20/roll20-api-scriptssegún corresponda. Esto creará una copia de ese repositorio en tu cuenta, al cual tendrás permiso para realizar cambios como desees. Ustedpuedebifurcar el repositorio tantas veces como quiera, pero sólo necesitabifurcarlo una vez. Este nuevo repositorio tendrá una dirección idéntica al original, excepto que en lugar de estar en la raíz "Roll20", tendrá una raíz con el nombre de tu cuenta de Roll20.
Si estás trabajando con otro usuario en la misma hoja o script, puede ser una buena idea ir a la configuración de tu nuevo repositorio y agregarlos como colaboradores. Los detalles de cómo agregar un colaborador o trabajar con un colaborador están más allá del alcance de este tutorial, sin embargo.
Si estás familiarizado con el sistema de control de versiones Git, no necesitarás ninguna otra información para completar el envío de tu hoja de personaje. ¡Todos los demás, sigan leyendo!
CLONA tu repositorio
Clonaciónun repositorio también hace una copia, pero un repositorio clonado se utiliza como copia de trabajo y se encuentra en el disco duro de su ordenador local como carpetas y archivos normales. Git mantiene un enlace, por defecto llamado "origin", entre las carpetas y el repositorio del cual se clonó.
Para el usuario principiante de Git, se recomienda encarecidamente descargar e instalar ya seaGitHub para WindowsoGitHub para Macsegún corresponda para tu sistema operativo. En adelante, se referirán a ellos en este documento como "GitHub Desktop" o "la aplicación de escritorio". Además de ser una forma sencilla de instalar y configurar el control de versiones de Git en tu computadora, las aplicaciones de escritorio de GitHub facilitan la vinculación con tu cuenta de usuario de GitHub. Te avisará cada vez que los archivos en tu computadora estén desactualizados con respecto a tu repositorio en GitHub y te permitirá sincronizarlos fácilmente.
Cuando ejecutes por primera vez la aplicación de GitHub, te pedirá que inicies sesión en tu cuenta de GitHub. Luego, haz clic en el signo más grande en la parte superior izquierda para clonar tu repositorio. Cuando clones el repositorio, se te pedirá que selecciones una ubicación para poner los archivos. Asegúrate de seleccionar una ubicación que puedas encontrar fácilmente, ¡necesitarás saber dónde está! Si obtienes una computadora nueva, la instalación de la aplicación de escritorio de GitHub y la clonación de tu repositorio son los únicos pasos que deben repetirse.
La aplicación de escritorio también tiene la interfaz más fácil para gestionar ramas. Cuando cambias de rama dentro de la aplicación de escritorio, agregará / eliminará / cambiará archivos para que coincidan con el último commit hecho desde la rama a la que has cambiado.
Si no estás utilizando la aplicación de GitHub, puedes encontrar la URL de clonación para tu repositorio en la página de tu repo. GitHub ofrece tanto URL de clonación SSH como HTTPS, así como una URL de checkout de Subversion. Los detalles de clonar tu repo manualmente están más allá del alcance de esta guía, sin embargo.
Flujo de trabajo de bifurcación de GitHub
La configuración anterior solo se realiza una vez. La siguiente sección describe los procedimientos que se recomienda seguir cada vez que desees enviar una actualización a Roll20.
Sincroniza tus archivos con Roll20
Si acabas de bifurcar y clonar tu repositorio hace unos minutos, todavía está sincronizado. Pero si regresas a tu repositorio después de muchas semanas o meses, algunas de las hojas de personajes o scripts de Mod (API) habrán sido actualizados. Existe la posibilidad de que el que desees modificar esté entre ellos. En ese caso, debes asegurarte de que estás trabajando con la última versión de los archivos que vas a modificar. No necesitas crear otra bifurcación, ni necesitas clonar tu repositorio de nuevo. Debes actualizar tu bifurcación con el maestro. Lee la guía enlazada a continuación sobre cómo sincronizar
En lugar de hacer una sincronización, ya sea necesaria o no, es posible que desees verificar primero si necesitas sincronizar el proyecto(s) en el que vas a trabajar. Una forma sencilla de verificar es ver los archivos en el repositorio de Roll20 y ver la última fecha de modificación. Otra es abrir los archivos allí y ejecutar una utilidad "diff"sobre ellos y su versión más reciente. Verifica si hay solicitudes de extracción pendientes para los archivos que vas a actualizar. Si los archivos específicos que vas a modificar no han cambiado desde la última vez que sincronizaste, realizar una sincronización completa de todo es opcional.
Otra opción es simplemente obtener todas las actualizaciones del repositorio principal de Roll20. Esto te permitirá obtener todas las actualizaciones que otras personas hayan hecho en los repositorios de roll20 desde la última vez que los sincronizaste (incluyendo un montón de hojas de personajes o scripts de Mod (API) que quizás no te interesen). Este enlace tiene una guía para sincronizar tu repositorio con el Original. Cuando hayas terminado con esto, los archivos en el repositorio principal de Roll20, tu propio repositorio y tu disco duro deberían ser los mismos. Asegúrate también de actualizar tu campaña de roll20.
Haz una rama
Se recomienda crear una nueva rama para cada proyecto separado (hoja de personaje o script de Mod (API)) y para cada actualización separada. Por ejemplo, si vas a actualizar dos scripts de Mod (API) diferentes al mismo tiempo, crea una rama para cada script. Si unas semanas más tarde decides hacer cambios adicionales en el mismo script, haz una nueva rama para la actualización más reciente. Como regla general, haz una nueva rama para cada solicitud de extracción.
La aplicación de escritorio también tiene la interfaz más fácil para administrar las ramas. En el menú superior, simplemente elige "Rama / Nueva rama". Cuando cambias de rama dentro de la aplicación de escritorio (La segunda línea te permite cambiar el repositorio en el que estás trabajando y cambiar la rama actual), agregará / eliminará / cambiará archivos en tu disco duro para que coincidan con el último commit realizado desde la rama a la que has cambiado.
COMMITA tus cambios y HAZ PUSH a tus commits
Cuandoconfirmascambios, guardas un registro de todo lo que has cambiado, así como una descripción legible por humanos de lo que has hecho en tu computadora local.
Luegohaces PUSHa tus commits en tu repositorio.
Una vez que tienes una copia de trabajo de tu repositorio clonado, puedes hacer cambios en él. Esto incluye la creación de una nueva carpeta para tu hoja de personaje o script de Mod (API) y agregar el código fuente, o hacer modificaciones a los archivos que ya están allí.
Muchas personas, al desarrollar scripts o hojas de personaje de Roll20, hacen todas las ediciones reales en un editor de texto (por ejemplo, notepad++). Simplemente puedes abrir los archivos en tu disco duro (los creados en el paso 'clonar') en cualquier editor de texto y hacer los cambios en el editor. Cuando desees ejecutar el código en Roll20, presiona ctrl/a y ctrl/c para seleccionar todo el texto y copiarlo al portapapeles. Luego pégalo en el campo correcto de la campaña de Roll20. Si se necesitan cambios adicionales (por ejemplo, depuración), a menudo es más fácil realizar un ciclo de edición, copia, pegado y prueba.
Cuando le ordenas al editor de texto que guarde tus cambios, finalmente escribirá tus cambios en el archivo que has estado editando, y GitHub Desktop detectará que el archivo que has editado ha cambiado y mostrará el nombre del archivo que ha cambiado en su panel izquierdo, y en el panel derecho mostrará un resumen de lo que detecta como diferente entre el guardado actual y el último commit que se hizo. Sin embargo, estos cambios solo han sido detectados, GitHub no ha hecho ningún registro de estos cambios hasta que los commits. Los expertos en Git recomiendan hacer commits con frecuencia, ya que hacer commits te da una copia de seguridad fuera del sitio de tu trabajo y un registro de cada commit.
No puedes hacer un commit sin un Resumen, pero la Descripción es opcional.
Hacer commits es muy simple. La aplicación de escritorio ya ha hecho todo el trabajo de identificar qué se debe hacer commit. Ingresa un título para los cambios y opcionalmente ingresa una descripción más larga, haz el commit presionando el botón "commit to (branch)". Asegúrate de hacer tus commits en tu rama de trabajo, no en tu rama principal. Hacer commits frecuentes te proporciona un historial detallado de los cambios que estás haciendo, en lugar de un solo commit con todo una vez que hayas terminado. Ten en cuenta que hay un límite de longitud para el Resumen. Sin embargo, si excedes el límite, tu mensaje se desbordará automáticamente en la Descripción más larga. Podrás ver esto cuando el texto en el campo de Resumen se vuelva gris.
Tan pronto como hagas el commit, la aplicación de escritorio de GitHub debería mostrar un aviso grande que diga No hay cambios locales. También debería sugerirte que hagas push de tu commit al origen. Alternativamente, podría sugerirte que "Publiques la rama". Sin embargo, hacer commit de tus cambios solo los guarda en tu computadora. Para llevar esos cambios a GitHub, necesitas hacer push hacia tu origen, el repositorio que se encuentra almacenado en línea. Simplemente presiona el botón "Push Origin" o "Publish Branch". Alternativamente, en cualquier momento en que el origen y el clon estén desactualizados, debería haber un botón muy mal etiquetado en la parte superior derecha que tenga un número y una flecha. Eso debería, entre otras cosas, sincronizar todo entre tu repositorio y el clon, por lo que podrías hacer push de eso en su lugar. En la parte superior de la herramienta de escritorio, el elemento del menú desplegable "Repository - Push" también realizará el trabajo.
Continúa editando y haciendo commits hasta que tus cambios estén completos y hayas probado y depurado el código listo para ser enviado para que el resto de roll20 lo disfrute. Ahora estás listo para solicitar que los administradores del sitio roll20 "pull" tus cambios al repositorio principal oficial de roll20.
Crea una solicitud de PULL
Como su nombre sugiere, unpulles lo opuesto a un push. En lugar de que un repositorio copiado envíe commits al original, el original solicita commits de la copia.
En la página web de tu repositorio, hay un botón verde que dice "Comparar, revisar, crear una solicitud de pull" cuando pasas el cursor sobre él. Este botón te llevará a una página donde puedes crear una solicitud de pull. Si hay alguna diferencia entre tu repositorio ("head") y la versión del repositorio de Roll20 ("base"), se mostrarán aquí. (Ten en cuenta que puedes cambiar qué usar tanto como el head como la base haciendo clic en el botón "Editar" cercano.) Dado que tus cambios están todos en tu rama de trabajo, no en tu rama principal, quieres que tu solicitud de pull provenga de tu rama de trabajo.
Como no tiene permisos de colaborador en el repositorio de Roll20, no puede realizar la acción pull usted mismo, pero puede solicitar aque otra persona realice el pull. Presiona el gran botón verde etiquetado como "Crear solicitud de extracción" y se abrirá una solicitud de extracción en el repositorio base. Las personas con permiso para hacerlo (es decir, los desarrolladores de Roll20) pueden examinar la solicitud de extracción, así como el contenido de los cambios propuestos, y luego fusionar la solicitud en el repositorio oficial.
Por claridad, incluye el nombre de la hoja para la que has realizado cambios en la solicitud de extracción, por ejemplo, "[Dungeondivers 3rd Edition] fixed broken Might roll".
Para envíos de hojas de personajes, recuerda incluir sheet.json y una imagen previa, revisa el readme para más información. Para envíos de scripts de Mod (API), recuerda incluir script.json, revisa el readme para más información. Suponiendo que todo esté correcto, tu hoja o script debería agregarse al archivo approved.yaml y estar disponible para todos los usuarios.
Una vez a la semana, Roll20 procesa todas las solicitudes de hojas disponibles. Cuando esto ocurre, recibirás un correo electrónico de GitHub. Este correo electrónico te informará si se dejó un comentario en tu solicitud sobre un problema que se descubrió con tu envío O si tu hoja se fusionó como se esperaba y tu solicitud se cerró (porque se completó exitosamente).
Hacer cambios en tu solicitud de extracción
Si creas una solicitud de extracción y luego haces commit & y haces algunos cambios adicionales en tu repositorio/rama antes de que se fusionen la solicitud de extracción, esos nuevos cambios se actualizarán/incluirán automáticamente en la solicitud de extracción original; no es necesario hacer una segunda extracción.
Limpieza
NO elimines ninguna rama hasta que todas las solicitudes de extracción de esa rama estén completas y cerradas. En realidad, nunca hay prisa por eliminar una rama en absoluto. No dañan nada siempre y cuando recuerdes usar cada rama solo una vez.
El software de GitHub recomendará que fusiones tu rama de vuelta a master. Este es un paso que se necesita con otros flujos de trabajo, pero no en el Flujo de trabajo de bifurcación que estamos usando. En su lugar, recomendamos sincronizar tu bifurcación con el original de roll20 como primer paso para prepararte para tu próxima actualización. Esto traerá las actualizaciones que acabas de hacer (así como cualquier cambio que haya hecho otra persona) a tu bifurcación.
Por lo tanto, no hay ninguna limpieza que necesite hacerse.
Más información
- Consejos sobre cómo usar Github(Hilo del foro de Roll20)
- Flujo de trabajo de GitHub (visualización)(no es el flujo que usamos, pero una buena visualización) yFlujo de trabajo de bifurcación(lo que usamos)
- Git - La guía simple (herramienta de línea de comandos)por Roger Dudler
Git y Github para poetas Tutorial en Youtube
Vídeos de 10-20 minutos de duración para personas sin conocimientos técnicos que enseñan los conceptos básicos de Git y Github, mostrando cómo trabajar con Github en el navegador, pero también tienen una introducción al uso de la línea de comandos. Está hecho en 2016 pero no parece estar fechado en un vistazo rápido(marzo 2019)
- 1.2 Ramas12 min
Git y Github para poetas (más allá de lo básico)
- 1.4 Problemas de GitHub 12 min
- 1.10 Remotos de Git 14 min