From 0af3e9c0360761d996503d243a589943f2614d1b Mon Sep 17 00:00:00 2001 From: GWC Date: Sat, 17 Aug 2019 20:49:44 -0300 Subject: [PATCH] Review on '06-github' sections finished --- .../sections/1-setting-up-account.asc | 24 +++--- book/06-github/sections/2-contributing.asc | 79 +++++++++---------- book/06-github/sections/3-maintaining.asc | 70 ++++++++-------- .../sections/4-managing-organization.asc | 12 +-- book/06-github/sections/5-scripting.asc | 58 +++++++------- 5 files changed, 121 insertions(+), 122 deletions(-) diff --git a/book/06-github/sections/1-setting-up-account.asc b/book/06-github/sections/1-setting-up-account.asc index da637518..9512c7d2 100644 --- a/book/06-github/sections/1-setting-up-account.asc +++ b/book/06-github/sections/1-setting-up-account.asc @@ -11,7 +11,7 @@ image::images/signup.png[Formulario para darse de alta en GitHub.] Lo siguiente que verás es la página de precios para planes mejores, pero lo puedes ignorar por el momento. GitHub te enviará un correo para verificar la -dirección que les has dado. Confirma la dirección ahora, es bastante importante +dirección que les has dado. Confirmar la dirección ahora, es bastante importante (como veremos después). [NOTE] @@ -19,7 +19,7 @@ dirección que les has dado. Confirma la dirección ahora, es bastante important GitHub proporciona toda su funcionalidad en cuentas gratuitas, con la limitación de que todos tus proyectos serán públicos (todos los usuarios tendrán acceso de lectura). -Los planes de pago de GitHub te permite tener algunos proyectos privados, +Los planes de pago de GitHub te permiten tener algunos proyectos privados, pero esto es algo que no veremos en este libro. ==== @@ -34,11 +34,11 @@ Desde ya, puedes acceder a los repositorios Git utilizando el protocolo `https://`, identificándote con el usuario y la contraseña que acabas de elegir. Sin embargo, para simplificar el clonado de proyectos públicos, no -necesitas crearte la cuenta. Es decir, la cuenta solo la necesitas cuando +necesitas crearte la cuenta. Es decir, la cuenta sólo la necesitas cuando comienzas a hacer cosas como bifurcar (fork) proyectos y enviar tus propios cambios más tarde. -Si prefieres usar SSH, necesitas configurar una clave pública. Si aun no +Si prefieres usar SSH, necesitas configurar una clave pública. Si aún no la tienes, mira cómo generarla en <>.) Abre tu panel de control de la cuenta utilizando el enlace de la parte superior derecha de la ventana: @@ -57,10 +57,10 @@ clave pública) en el área de texto, y pulsa sobre ``Add key''. [NOTE] ==== -Asegúrate darle a tu clave un nombre que puedas recordar. Puedes, por ejemplo, +Asegúrate de darle a tu clave un nombre que puedas recordar. Puedes, por ejemplo, añadir claves diferentes, con nombres como "Clave Portátil" o "Cuenta de -trabajo" de modo que si tienes que revocar alguna clave más tarde, te resultará -más fácil decidir cuál es. +trabajo", de modo que si tienes que revocar alguna clave más tarde, te resultará +más fácil saber cuál es. ==== [[r_personal_avatar]] @@ -75,24 +75,24 @@ ti con una imagen de tu elección. En primer lugar selecciona la opción image::images/your-profile.png[Enlace ``Profile''.] Nosotros eligiremos como ejemplo una copia del logo de Git que tengamos en -el disco duro y luego tendremos opción de recortarlo al subirlo. +el disco duro y luego tendremos la opción de recortarlo al subirlo. .Recortar tu icono image::images/avatar-crop.png[Recortar tu icono.] -Desde ahora, quien vea tu perfil o tus contribuciones a repositorios verá +Desde ahora, quien vea tu perfil o tus contribuciones a repositorios, verá tu nuevo icono junto a tu nombre. Si da la casualidad que ya tienes tu icono en el popular servicio Gravatar (conocido por su uso en las cuentas de Wordpress), este icono será detectado -y no tendrás que hacer, si quieres, este paso. +y no tendrás que hacer este paso, si no lo deseas. ==== Tus direcciones de correo La forma con la que GitHub identifica tus contribuciones a Git es mediante la dirección de correo electrónico. Si tienes varias direcciones diferentes en tus contribuciones (commits) y quieres que GitHub sepa que son de tu -cuenta, necesitas añadirlas todas en la sección Emails de la sección +cuenta, necesitas añadirlas todas en el apartado Emails de la sección de administración. [[r_add_email_addresses]] @@ -112,7 +112,7 @@ con esa dirección, la identificará asociándola a tu usuario. Finalmente, y para mayor seguridad, deberías configurar la Autentificación de Dos Pasos o ``2FA''. Este tipo de autentificación se está haciendo más popular para reducir el riesgo de que te roben la cuenta. Al activarla, -GitHub te pedirá identificarte de dos formas, de forma que si una de ellas +GitHub te pedirá identificarte de dos formas, de manera que si una de ellas resulta comprometida, el atacante no conseguirá acceso a tu cuenta. Puedes encontrar la configuración de ``2FA'' en la opción Security de los diff --git a/book/06-github/sections/2-contributing.asc b/book/06-github/sections/2-contributing.asc index 17bc358c..9e239699 100755 --- a/book/06-github/sections/2-contributing.asc +++ b/book/06-github/sections/2-contributing.asc @@ -9,23 +9,23 @@ para ayudarte a participar en proyectos existentes. Si quieres participar en un proyecto existente, en el que no tengas permisos de escritura, puedes bifurcarlo (hacer un ``fork''). Esto consiste en crear una copia completa del repositorio totalmente bajo tu control: -se encontrará en tu cuenta y podrás escribir en él sin limitaciones. +se almacenará en tu cuenta y podrás escribir en él sin limitaciones. [NOTE] ==== Históricamente, el término ``fork'' podía tener connotaciones algo negativas, ya que significaba que alguien realizaba una copia del código fuente del proyecto -y las comenzaba a modificar de forma independiente al proyecto original, -tal vez para crear un proyecto competidor y dividir a su comunidad de +y las comenzaba a modificar de forma independiente al proyecto original. +Tal vez, para crear un proyecto competidor y dividir a su comunidad de colaboradores. En GitHub, el ``fork'' es simplemente una copia del repositorio -donde puedas escribir, haciendo públicos tus propios cambios, como una manera +donde puedes escribir, haciendo públicos tus propios cambios, como una manera abierta de participación. ==== De esta forma, los proyectos no necesitan añadir colaboradores con acceso de escritura (push). La gente puede bifurcar un proyecto, enviar sus propios cambios a su copia y luego remitir esos cambios al repositorio original para -su aprobación, creando lo que se llama un Pull Request, que veremos más +su aprobación; creando lo que se llama un Pull Request, que veremos más adelante. Esto permite abrir una discusión para la revisión del código, donde propietario y participante pueden comunicarse acerca de los cambios y, en última instancia, @@ -49,7 +49,7 @@ cuenta y con tu propia copia del código fuente. GitHub está diseñado alrededor de un flujo de trabajo de colaboración específico, centrado en las solicitudes de integración (``pull request''). Este flujo es válido tanto si colaboras con un pequeño equipo en un -repositorio compartido como si lo haces en una gran red de participantes con +repositorio compartido, como si lo haces en una gran red de participantes con docenas de bifurcaciones particulares. Se centra en el workflow <> cubierto en <>. @@ -65,8 +65,7 @@ commits. la rama con tus cambios o bien rechazándolos. Este es, básicamente, el flujo de trabajo del Responsable de Integración visto -en <>, pero en lugar de usar el correo para comunicarnos -y revisar los cambios, lo que se hace es usar las herramientas web de GitHub. +en <>, pero en lugar de usar el correo para comunicarnos y revisar los cambios, lo que se hace es usar las herramientas web de GitHub. Veamos un ejemplo de cómo proponer un cambio en un proyecto de código abierto hospedado en GitHub, utilizando esta forma de trabajar. @@ -159,7 +158,7 @@ hacer una buena descripción para que el autor sepa realmente qué estamos aportando y lo valore adecuadamente. También veremos la lista de commits de la rama que están ``por delante'' de la -rama `master` (en este caso, la única) y un diff unificado de los cambios que +rama `master` (en este caso, la única) y un ``diff unificado'' de los cambios que se aplicarían si se fusionasen con el proyecto original. .Página de creación del Pull Request @@ -171,7 +170,7 @@ junto a un enlace donde está toda la información. [NOTE] ==== -Aunque los Pull Request se utilizan en proyectos públicos como este donde el +Aunque los Pull Request se utilizan en proyectos públicos como este, donde el ayudante tiene un conjunto de cambios completos para enviar, también se utiliza en proyectos internos al principio del ciclo de desarrollo: puedes crear el Pull Request con una rama propia y seguir enviando commits a dicha rama después @@ -187,8 +186,8 @@ la idea pero prefiere esperar un poco. La discusión, en los workflow de <>, tiene lugar por correo electrónico, mientras que en GitHub tiene lugar en línea. El propietario -del proyecto puede revisar el diff y dejar un comentario pulsando en -cualquier línea del diff. +del proyecto puede revisar el ``diff'' y dejar un comentario pulsando en +cualquier línea del ``diff''. .Comentando una línea concreta del diff image::images/blink-04-pr-comment.png[Comentario de línea del PR] @@ -213,15 +212,15 @@ conversación. .Página de discusión del Pull Request image::images/blink-05-general-comment.png[Página de discusión del PR] -El participante puede ver ahora qué tiene que hacer para ver aceptado su -cambio. Con suerte sera poco trabajo. Mientras que con el correo electrónico +El participante puede ver ahora qué tiene que hacer para que sea aceptado su +cambio. Con suerte será poco trabajo. Mientras que con el correo electrónico tendrías que revisar los cambios y reenviarlos a la lista de correo, en GitHub puedes, simplemente, enviar un nuevo commit a la rama y subirla (push). Si el participante hace esto, el coordinador del proyecto será notificado nuevamente y, cuando visiten la página, verán lo que ha cambiado. De hecho, al ver que un cambio en una línea de código tenía ya un comentario, GitHub -se da cuenta y oculta el diff obsoleto. +se da cuenta y oculta el ``diff'' obsoleto. [[r_pr_final]] .Pull Request final @@ -230,9 +229,9 @@ image::images/blink-06-final.png[PR final] Es interesante notar que si pulsas en ``Files Changed'' dentro del Pull Request, verás el ``diff unificado'', es decir, los cambios que se introducirían en la rama principal si la otra rama fuera fusionada. En -términos de git, lo que hace es mostrarte la salida del comando +términos de Git, lo que hace es mostrarte la salida del comando `git diff master ... `. Mira en <> para saber -más sobre este tipo de diff. +más sobre este tipo de ``diff''. Otra cosa interesante es que GitHub también comprueba si el Pull Request se fusionaría limpiamente (de forma automática) dando entonces un botón @@ -256,7 +255,7 @@ finalmente la petición es cerrada (rechazada) o fusionada. Observa que también puedes abrir un Pull Request entre dos ramas del mismo repositorio. Si estás trabajando en una característica con alguien y ambos tenéis acceso de escritura al repositorio, puedes subir una rama al mismo -y abrir un Pull Request con ella de fusión con `master` para poder formalizar +y abrir un Pull Request de fusión con `master` para poder formalizar el proceso de revisión de código y discusión. Para esto no se requieren bifurcaciones (forks). ==== @@ -274,7 +273,7 @@ Requests sean colas de parches perfectos que se pueden aplicar limpiamente en orden, como sucede con los proyectos basados en listas de correo. Casi todos los proyectos de GitHub consideran las ramas de Pull Requests como conversaciones evolutivas acerca de un cambio propuesto, culminando en un -diff unificado que se aplica fusionando. +``diff'' unificado que se aplica fusionando. Esto es importante, ya que normalmente el cambio se sugiere bastante antes de que el código sea suficientemente bueno, lo que lo aleja bastante del modelo @@ -287,7 +286,7 @@ commit en la rama para enviar la diferencia que materializa esas sugerencias, haciendo avanzar la conversación con el contexto del trabajo previo intacto. Por ejemplo, si miras de nuevo en <>, verás que el colaborador -no reorganiza su commit y envía un nuevo Pull Request. En lugar, lo que hace es +no reorganiza su commit y envía un nuevo Pull Request. En su lugar, lo que hace es añadir nuevos commits y los envía a la misma rama. De este modo, si vuelves a mirar el Pull Request en el futuro, puedes encontrar fácilmente todo el contexto con todas las decisiones tomadas. Al pulsar el botón ``Merge'', @@ -296,7 +295,7 @@ fácil localizar para revisar la conversación original, si es necesario. ===== Manteniéndonos actualizados -Si el Pull Request se queda anticuado o por cualquier otra razón no puede +Si el Pull Request se queda anticuado, o por cualquier otra razón no puede fusionarse limpiamente, lo normal es corregirlo para que el responsable pueda fusionarlo fácilmente. GitHub comprobará esto y te dirá si cada Pull Request tiene una fusión trivial posible o no. @@ -314,11 +313,11 @@ la rama con el contenido de la rama `master` (normalmente esta es la rama desde donde se hizo la bifurcación), o bien puedes fusionar la rama objetivo en la tuya. -Muchos desarrolladores eligen la segunda opción, por las mismas razones que +Muchos desarrolladores eligen la segunda opción, por las mismas razones que dijimos en la sección anterior. Lo que importa aquí es la historia y la fusión final, por lo que reorganizar no es mucho más que tener una -historia más limpia y, sin embargo, es de lejos más complicado de hacer y -con más posibilidad de error. +historia más limpia y, sin embargo, es por lejos más complicado de hacer y +con mayores posibilidades de error. Si quieres fusionar en la rama objetivo para hacer que tu Pull Request sea fusionable, deberías añadir el repositorio original como un nuevo remoto, @@ -328,7 +327,7 @@ solicitud de integración. Por ejemplo, supongamos que en el ejemplo ``tonychacon'' que hemos venido usando, el autor original hace un cambio que crea un conflicto con el Pull -Request. Seguiremos entonces los siguientes pasos. +Request. Seguiremos entonces los siguientes pasos: [source,console] ---- @@ -378,7 +377,7 @@ image::images/pr-02-merge-fix.png[PR corregido] Una de las cosas interesantes de Git es que puedes hacer esto continuamente. Si tienes un proyecto con mucha historia, puedes fácilmente fusionarte la -rama objetivo (`master`) una y otra vez cada vez que sea necesario, evitando +rama objetivo (`master`) cada vez que sea necesario, evitando conflictos y haciendo que el proceso de integración de tus cambios sea muy manejable. @@ -387,7 +386,7 @@ hacerlo, pero se recomienda no forzar el push sobre la rama del Pull Request. Si otras personas se la han bajado y hacen más trabajo en ella, provocarás los problemas vistos en <>. En su lugar, envía la rama reorganizada a una nueva rama de GitHub y abre con ella un nuevo Pull Request, -con referencia al antiguo, cerrando además éste. +con referencia al antiguo, cerrando además éste último. ===== Referencias @@ -407,7 +406,7 @@ una bifurcación que haya creado ese usuario, o incluso puede usarse la forma repositorio diferente. Veamos un ejemplo. Supongamos que hemos reorganizado la rama del ejemplo -anterior, creado un nuevo pull request para ella y ahora queremos hacer una +anterior, creado un nuevo Pull Request para ella y ahora queremos hacer una referencia al viejo Pull Request desde el nuevo. También queremos hacer referencia a una incidencia en la bifurcación del repositorio, y una incidencia de un proyecto totalmente distinto. Podemos rellenar la descripción @@ -417,7 +416,7 @@ justo como vemos en <>. .Referencias cruzadas en un Pull Request. image::images/mentions-01-syntax.png[Referencias a PR] -Cuando enviamos este pull request, veremos todo como en +Cuando enviamos este Pull Pequest, veremos todo como en <>. [[r_pr_references_render]] @@ -429,7 +428,7 @@ a la información que necesitamos realmente. Ahora, si Tony regresa y cierra el Pull Request original, veremos que GitHub crea un evento en la línea de tiempo del Pull Request. Esto significa -que cualquier que visite este Pull Request y vea que está cerrado, puede +que cualquiera que visite este Pull Request y vea que está cerrado, puede fácilmente enlazarlo al que lo hizo obsoleto. El enlace se mostrará tal como en <>. @@ -438,18 +437,18 @@ como en <>. image::images/mentions-03-closed.png[PR cerrado] Además de los números de incidencia, también puedes hacer referencia a un -commit específico usando la firma SHA-1. Puedes utilizar la cadena SHA-1 +``commit'' específico usando la firma SHA-1. Puedes utilizar la cadena SHA-1 completa (de 40 caracteres) y al detectarla GitHub en un comentario, la -convertirá automáticamente en un enlace directo al commit. Nuevamente, +convertirá automáticamente en un enlace directo al ``commit''. Nuevamente, puedes hacer referencia a commits en bifurcaciones o en otros repositorios del mismo modo que hicimos con las incidencias. ==== Markdown -En enlazado a otras incidencias es solo el comienzo de las cosas interesantes +El enlazado a otras incidencias es sólo el comienzo de las cosas interesantes que se pueden hacer con cualquier cuadro de texto de GitHub. En las descripciones de las incidencias y los Pull Requests, así como en los -comentarios, y otros cuadros de texto, se puede usar lo que se conoce +comentarios y otros cuadros de texto, se puede usar lo que se conoce como ``formato Markdown de GitHub''. El formato Markdown es como escribir en texto plano pero que luego se convierte en texto con formato. @@ -471,7 +470,7 @@ La primera característica añadida, especialmente interesante para los Pull Requests, son las listas de tareas. Una lista de tareas es una lista de cosas con su marcador para indicar que han terminado. En un Pull Requests o una incidencia nos sirven para anotar la lista de cosas -pendientes para considerar terminado el trabajo relacionado con esa +pendientes a realizar para considerar terminado el trabajo relacionado con esa incidencia. Puedes crear una lista de tareas así: @@ -492,13 +491,13 @@ image::images/markdown-02-tasks.png[Ejemplo de lista de tareas] Esto se suele usar en Pull Requests para indicar qué cosas hay que hacer en la rama antes de considerar que el Pull Request está listo para fusionarse. -La parte realmente interesante es que puedes pulsar los marcadores para +La parte realmente interesante, es que puedes pulsar los marcadores para actualizar el comentario indicando qué tareas se finalizaron, sin necesidad de editar el texto markdown del mismo. Además, GitHub mostrará esas listas de tareas como metadatos de las páginas que las muestran. Por ejemplo, si tienes un Pull Request con tareas y -miras la página resumen de todos los Pull Request, podrás ver cuánto trabajo +miras la página de resumen de todos los Pull Request, podrás ver cuánto trabajo queda pendiente. Esto ayuda a la gente a dividir los Pull Requests en subtareas y ayuda a otras personas a seguir la evolución de la rama. Se puede ver un ejemplo de esto en <>. @@ -557,7 +556,7 @@ Un ejemplo de cita: How big are these slings and in particular, these arrows? ---- -Una vez introducida, el comentario se vería como en <>. +Una vez introducido, el comentario se vería como en <>. [[r_md_quote]] .Rendered quoting example. @@ -565,10 +564,10 @@ image::images/markdown-05-quote.png[Rendered quoting] ====== Emojis (emoticonos) -Finalmente, también puedes usar emoji (emoticonos) en tus comentarios. Se +Finalmente, también puedes usar emojis (emoticonos) en tus comentarios. Se utiliza mucho en las discusiones de las incidencias y Pull Requests de GitHub. Incluso tenemos un asistente de emoji: si escribes un comentario y tecleas el -carácter `:`, verás cómo aparecen iconos para ayudarte a completar el +caracter `:`, verás cómo aparecen iconos para ayudarte a completar el que quieras poner. [[r_md_emoji_auto]] diff --git a/book/06-github/sections/3-maintaining.asc b/book/06-github/sections/3-maintaining.asc index 35c98fa0..fd8d71b8 100755 --- a/book/06-github/sections/3-maintaining.asc +++ b/book/06-github/sections/3-maintaining.asc @@ -56,13 +56,13 @@ necesitarás añadirlas como ``colaboradores''. Si Ben, Jeff y Louise se crean cuentas en GitHub, y quieres darles acceso de escritura a tu repositorio, los tienes que añadir al proyecto. Al hacerlo le darás permiso de ``push'', que significa que tendrán tanto -acceso de lectura como de escritura, en el proyecto y en el repositorio Git. +acceso de lectura como de escritura en el proyecto y en el repositorio Git. .Enlace a ajustes del repositorio. image::images/reposettingslink.png[Enlace a ajustes del repositorio.] Selecciona ``Collaborators'' del menú del lado izquierdo. Simplemente, teclea -el usuario en la caja, y pulsa en ``Add collaborator.'' +el usuario en la caja y pulsa en ``Add collaborator.'' Puedes repetir esto las veces que necesites para dar acceso a otras personas. Si necesitas quitar un acceso, pulsa en la ``X'' del lado derecho del usuario. @@ -76,10 +76,10 @@ colaboradores con acceso de escritura, veamos qué pasa cuando alguien te hace un Pull Request. Los Pull Requests pueden venir de una rama en una bifurcación del repositorio, -o pueden venir de una rama pero del mismo repositorio. La única diferencia -es que, en el primer, caso procede de gente que no tiene acceso de escritura +o pueden venir de una rama del mismo repositorio. La única diferencia +es que, en el primer caso procede de gente que no tiene acceso de escritura a tu proyecto y quiere integrar en el tuyo cambios interesantes, mientras que -en el segundo caso procede de gente con acceso al repositorio. +en el segundo caso procede de gente con acceso de escritura al repositorio. En los siguientes ejemplos, supondremos que eres ``tonychacon'' y has creado un nuevo proyecto para Arduino llamado ``fade''. @@ -96,7 +96,7 @@ aspecto similar a <>. image::images/maint-01-email.png[Notificación por correo de nuevo Pull Request] Hay algunas cosas a destacar en este correo. En primer lugar, te dará -un pequeño diffstat (es decir, una lista de archivos cambiados y en qué +un pequeño 'diffstat' (es decir, una lista de archivos cambiados y en qué medida). Además, trae un enlace al Pull Request y algunas URL que puedes usar desde la línea de comandos. @@ -106,8 +106,8 @@ rápidamente en <>. Si lo deseas, p cambiar a una rama y luego ejecutar el comando para fusionar los cambios del Pull Request. -Las otras URL interesantes son las de `.diff` y `.patch`, que como su nombre -indican, proporcionan diff unificados y formatos de parche del Pull Request. +Las otras URL interesantes son las de `.diff` y `.patch`, que como su nombre lo +indica, proporcionan ``diff unificados'' y formatos de parche del Pull Request. Técnicamente, podrías fusionar con algo como: [source,console] @@ -124,13 +124,13 @@ utilizando donde quieras el formato Markdown. Cada vez que alguien comenta, recibirás nuevas notificaciones por correo, lo que te permite vigilar todo lo que pasa. Cada correo tendrá un enlace -a la actividad que ha tenido lugar, y además puedes responder al comentario +a la actividad que ha tenido lugar y, además, puedes responder al comentario simplemente contestando al correo. .Las respuestas a correos se incluyen en el hilo de discusión. image::images/maint-03-email-resp.png[Respuesta a correo-e] -Una vez que el código está como quieres y quieres fusionarlo, puedes copiar +Una vez que el código está como quieres y deseas fusionarlo, puedes copiar el código y fusionarlo localmente, mediante la sintaxis ya conocida de `git pull `, o bien añadiendo el fork como nuevo remoto, bajándotelo y luego fusionándolo. @@ -139,7 +139,7 @@ Si la fusión es trivial, también puedes pulsar el botón ``Merge'' en GitHub. Esto realizará una fusión ``sin avance rápido'', creando un commit de fusión incluso si era posible una fusión con avance rápido. Esto significa que cada vez que pulses el botón Merge, se creará un commit de fusión. Como verás -en <>, GitHub te da toda esta información si pulsas el el enlace +en <>, GitHub te da toda esta información si pulsas en el enlace de ayuda. [[r_merge_button]] @@ -215,9 +215,9 @@ construir esa referencia, y deja un puntero al commit que quieres bajo `.git/FETCH_HEAD`. Puedes realizar operaciones como `git merge FETCH_HEAD` aunque el mensaje del commit será un poco confuso. Además, si estás revisando un montón de -pull requests, se convertirá en algo tedioso. +Pull Requests, se convertirá en algo tedioso. -Hay también una forma de obtener _todos_ los pull requests, y mantenerlos +Hay también una forma de obtener _todos_ los Pull Requests, y mantenerlos actualizados cada vez que conectas al remoto. Para ello abre el archivo `.git/config` y busca la línea `origin`. Será similar a esto: @@ -255,9 +255,9 @@ $ git fetch # … ---- -Ya tienes todos los pull request en local de forma parecida a las ramas; son +Ya tienes todos los Pull Request en local de forma parecida a las ramas; son solo-lectura y se actualizan cada vez que haces un fetch. Pero hace muy fácil -probar el código de un pull request en local: +probar el código de un Pull Request en local: [source,console] ---- @@ -267,9 +267,9 @@ Branch pr/2 set up to track remote branch pr/2 from origin. Switched to a new branch 'pr/2' ---- -La referencia `refs/pull/#/merge` de GitHub representa el commit que resultaría -si pulsamos el botón ``merge''. Esto te permite probar la fusión del pull -request sin llegar a pulsar dicho botón. +La referencia `refs/pull/#/merge` de GitHub representa el ``commit'' que resultaría +si pulsamos el botón ``merge''. Esto te permite probar la fusión del Pull +Request sin llegar a pulsar dicho botón. ===== Pull Requests sobre Pull Requests @@ -297,9 +297,9 @@ Pull Request o en otrá bifurcación del proyecto. ==== Menciones y notificaciones GitHub tiene un sistema de notificaciones que resulta útil cuando necesitas -pedir ayuda o necesitas la opinión de otros usuarios o equipos concretos. +pedir ayuda, o necesitas la opinión de otros usuarios o equipos concretos. -En cualquier comentario, si comienzas una palabra comenzando con el carácter +En cualquier comentario, si comienzas una palabra anteponiendo el carácter `@`, intentará auto-completar nombres de usuario de personas que sean colaboradores o responsables en el proyecto. @@ -312,12 +312,12 @@ pero normalmente el autocompletado lo hará más rápido. Una vez que envías un comentario con mención a un usuario, el usuario citado recibirá una notificación. Es decir, es una forma de implicar más gente en una conversación. Esto es muy común en los Pull Requests para invitar a terceros -a que participen en la revisión de una incidencia o un pull request. +a que participen en la revisión de una incidencia o un Pull Request. -Si alguien es mencionado en un Pull request o incidencia, quedará además +Si alguien es mencionado en un Pull Request o incidencia, quedará además ``suscrito'' y recibirá desde este momento las notificaciones que genere -su actividad. Del mismo modo, el usuario que crea la incidencia o el Pull request -queda automáticamente suscrito para recibir las notificaciones, disponiendo +su actividad. Del mismo modo, el usuario que crea la incidencia o el Pull Request +queda automáticamente ``suscrito'' para recibir las notificaciones, disponiendo todos de un botón ``Unsubscribe'' para dejar de recibirlas. .Quitar suscripción de un pull request o incidencia. @@ -340,7 +340,7 @@ y puedes elegir tener una de ellas, ambas o ninguna. ====== Notificaciones Web Las notificaciones web se muestran en la página de Github. Si las tienes activas -verás un pequeño punto azul sobre el icono de notificaciones en la parte +verás un pequeño punto azul sobre el icono de 'Notificaciones' en la parte superior de la pantalla, en <>. @@ -350,20 +350,20 @@ image::images/maint-08-notifications-page.png[Centro de notificaciones] Si pulsas en él, verás una lista de todos los elementos sobre los que se te notifica, agrupados por proyecto. Puedes filtrar para un proyecto específico -pulsando en el nombre en el lado izquierdo. También puedes reconocer (marcar como +pulsando en su nombre en el lado izquierdo. También puedes reconocer (marcar como leída) una notificación pulsando en el icono de check en una notificación, o reconocerlas _todas_ pulsando en el icono de check de todo el grupo. Hay también un botón ``mute'' para silenciarlas, que puedes pulsar para no recibir nuevas notificaciones de ese elemento en el futuro. -Todas estas utilidades son útiles para manejar un gran número de notificaciones. +Todas estas características son útiles para manejar un gran número de notificaciones. Muchos usuarios avanzados de GitHub suelen desactivar las notificaciones por correo y manejarlas todas mediante esta pantalla. ====== Notificaciones por correo Las notificaciones por correo electrónico son la otra manera de gestionar -notificaciones con GitHub. Si las tienes activa, recibirás los correos de cada +notificaciones con GitHub. Si las tienes activas, recibirás los correos de cada notificación. Vimos ya algún ejemplo en <> y <>. Los correos también serán agrupados correctamente en conversaciones, con lo que estará bien que uses un cliente de correo que maneje las @@ -393,15 +393,15 @@ los datos que necesitamos para identificar usuario, proyecto y demás en formato `///`. Si se tratase de una incidencia, la palabra ``pull'' habría sido reemplazada por ``issues''. -Las cabeceras `List-Post` y `List-Unsubscribe` sirven a clientes de correo -capaces de interpretarlas ayudarnos a solicitar dejar de recibir nuevas +Las cabeceras `List-Post` y `List-Unsubscribe` permiten a clientes de correo +capaces de interpretarlas, ayudarnos a solicitar dejar de recibir nuevas notificaciones de ese tema. Esto es similar a pulsar el botón ``mute'' que vimos en la versión web, o en ``Unsubscribe'' en la página de la incidencia o el Pull Request. También merece la pena señalar que si tienes activadas las notificaciones tanto -en la web como por correo, y marcas como leído el correo, en la web también se -marcará como leído siempre que permitas las imágenes en el cliente de correo. +en la web como por correo, y marcas como leído el correo en la web también se +marcará como leído, siempre que permitas las imágenes en el cliente de correo. ==== Archivos especiales @@ -412,7 +412,7 @@ en el repositorio. En primer lugar tenemos el archivo `README`, que puede estar en varios formatos. Puede estar con el nombre `README`, `README.md`, `README.asciidoc` y alguno más. -Cuando GitHub detecta la presencia del proyecto, lo muestra en la página +Cuando GitHub detecta su presencia en el proyecto, lo muestra en la página principal, con el _renderizado_ que corresponda a su formato. En muchos casos este archivo se usa para mostrar información relevante a @@ -430,7 +430,7 @@ o enlaces en él para facilitar su comprensión. ==== CONTRIBUTING -El otro archivo que GitHub reconoce es el archivo `CONTRIBUTING`. Si tienes +El otro archivo que GitHub reconoce es `CONTRIBUTING`. Si tienes un archivo con ese nombre y cualquier extensión, GitHub mostrará algo como <> cuando se intente abrir un Pull Request. @@ -463,7 +463,7 @@ al principio (``checked-out'') cuando alguien clona el repositorio. ===== Transferencia de un proyecto Si quieres transferir la propiedad de un proyecto a otro usuario u -organización de GitHub, hay una opción para ello al final de ``Options'' llamada +organización en GitHub, hay una opción para ello al final de ``Options'' llamada ``Transfer ownership''. [[r_transfer_project]] diff --git a/book/06-github/sections/4-managing-organization.asc b/book/06-github/sections/4-managing-organization.asc index 208f4bd7..feeca28b 100755 --- a/book/06-github/sections/4-managing-organization.asc +++ b/book/06-github/sections/4-managing-organization.asc @@ -30,12 +30,12 @@ los repositorios sean de código abierto (y por tanto, públicos). Como propietario de la organización, cuando bifurcas un repositorio podrás hacerlo a tu elección en el espacio de la organización. Cuando -creas nuevos repositorios puedes también elegir el espacio donde se +creas nuevos repositorios puedes también elegir el espacio donde se crearán: la organización o tu cuenta personal. Automáticamente, además, quedarás como vigilante (watcher) de los repositorios que crees en la organización. -Al igual que en <>, puedes subir un icono para +Al igual que en <>, puedes subir un icono para personalizar un poco la organización, que aparecerá entre otros sitios en la página principal de la misma, que lista todos los repositorios y puede ser vista por cualquiera. @@ -66,9 +66,9 @@ image::images/orgs-01-page.png[] Para gestionar tus equipos, puedes pulsar en la barra ``Teams'' del lado derecho en la página <>. Esto te llevará a -una página con la que puedes añadir los miembros del equipo, +una página en la que puedes añadir los miembros del equipo, añadir repositorios al equipo o gestionar los ajustes y niveles -de acceso del mismo. Cada equipo puede tener acceso sólo lectura, +de acceso del mismo. Cada equipo puede tener acceso de solo lectura, de escritura o administrativo al repositorio. Puedes cambiar el nivel pulsando en el botón ``Settings'' en <>. @@ -82,12 +82,12 @@ invitación. Además, hay menciones de equipo (por ejemplo, `@acmecorp/frontend`) que servirán para que todos los miembros de ese equipo sean suscritos al hilo. Esto resulta útil si quieres -involucrar a un equipo en algo al no tener claro a quién concreto +involucrar a un equipo en algo al no tener claro a quién en concreto preguntar. Un usuario puede pertenecer a cuantos equipos desee, por lo que no uses equipos solamente para temas de control de acceso a repositorios, -sino que puedes usarlo para formar equipos especializados y dispares +sino que puedes usarlos para formar equipos especializados y dispares como `ux`, `css`, `refactoring`, `legal`, etc. ==== Auditorías diff --git a/book/06-github/sections/5-scripting.asc b/book/06-github/sections/5-scripting.asc index d617a356..c584cb23 100755 --- a/book/06-github/sections/5-scripting.asc +++ b/book/06-github/sections/5-scripting.asc @@ -10,14 +10,14 @@ sentidos. En esta sección veremos cómo se usan los 'enganches' ==== Enganches -Las secciones Hooks y Services de la página de administración del -repositorio en Github es la forma más simple de hacer que GitHub +Las secciones Hooks y Services, de la página de administración del +repositorio en Github, es la forma más simple de hacer que GitHub interactúe con sistemas externos. ===== Servicios En primer lugar, echaremos un ojo a los Servicios. Ambos, enganches -y servicios pueden configurarse desde la sección Settings del +y servicios, pueden configurarse desde la sección Settings del repositorio, el mismo sitio donde vimos que podíamos añadir colaboradores al proyecto o cambiar la rama predeterminada. Bajo la opción ``Webhooks and Services'' veremos algo similar @@ -31,7 +31,7 @@ Hay docenas de servicios que podemos elegir, muchos de ellos para integrarse en otros sistemas de código abierto o comerciales. Muchos son servicios de integración continua, gestores de incidencias y fallos, salas de charla y sistemas -de documentación. Veremos cómo levantar un servicio sencillo, +de documentación. Veremos cómo levantar un servicio sencillo: el enganche con el correo electrónico. Si elegimos ``email'' en la opción ``Add Service'' veremos una pantalla de configuración similar a <>. @@ -44,7 +44,7 @@ En este caso, si pulsamos en el botón ``Add service'', la dirección de correo especificada recibirá un correo cada vez que alguien envía cambios (push) al repositorio. Los servicios pueden dispararse con muchos otros tipos de eventos, aunque la mayoría -solo se usan para los eventos de envío de cambios (push) y hacer +sólo se usan para los eventos de envío de cambios (push) y hacer algo con los datos del mismo. Si quieres integrar algún sistema concreto con GitHub, debes @@ -76,10 +76,10 @@ La configuración de un enganche web es bastante simple. Casi siempre basta con incluir una URL y una clave secreta, y pulsar en ``Add webhook''. Hay algunas opciones sobre qué eventos quieres que disparen el envío de datos (de forma predeterminada el único evento considerado es el evento -`push`, de cuando alguien sube algo a cualquier rama del repositorio). +`push`, que se dispara cuando alguien sube algo a cualquier rama del repositorio). Veamos un pequeño ejemplo de servicio web para manejar un enganche web. -Usaremos el entorno Sinatra de Ruby puesto que es conciso y podrás +Usaremos el entorno Sinatra de Ruby, puesto que es conciso y podrás entender con facilidad qué estamos haciendo. Pongamos que queremos recibir un correo cada vez que alguien sube algo @@ -122,13 +122,13 @@ end Aquí estamos tomando el bloque JSON que GitHub entrega y mirando quién hizo el envío, qué rama se envió y qué archivos se modificaron en cada -commit realizado en este push. Entonces, comprobamos si se cumple nuestro +``commit'' realizado en este push. Entonces, comprobamos si se cumple nuestro criterio y enviamos un correo si es así. Para poder probar algo como esto, tienes una consola de desarrollador en la -misma pantalla donde configuraste el enganche, donde se puede ver las últimas +misma pantalla donde configuraste el enganche, donde se pueden ver las últimas veces que GitHub ha intentado ejecutar el enganche. Para cada uno, puedes -mirar qué información se ha enviado, y si fue recibido correctamente, junto +mirar qué información se ha enviado y si fué recibido correctamente, junto con las cabeceras correspondientes de la petición y de la respuesta. Esto facilita mucho las pruebas de tus enganches. @@ -149,11 +149,11 @@ https://developer.github.com/webhooks/ (((GitHub, API))) Servicios y enganches nos sirven para recibir notificaciones ``push'' sobre eventos que suceden en tus repositorios. Pero, ¿qué pasa si necesitas más -información acerca de estos eventos? ¿y si necesitas automatizar algo como +información acerca de estos eventos?, ¿y si necesitas automatizar algo como añadir colaboradores o etiquetar incidencias? Aquí es donde entra en juego la API de GitHub. GitHub tiene montones de -llamadas de API para hacer casi cualquier cosa que puedes hacer via web, +llamadas de API para hacer casi cualquier cosa que puedes hacer vía web, de forma automatizada. En esta sección aprenderemos cómo autentificar y conectar a la API, cómo comentar una incidencia y cómo cambiar el estado de un Pull Request mediante la API. @@ -161,7 +161,7 @@ de un Pull Request mediante la API. ==== Uso Básico Lo más básico que podemos hacer es una petición GET a una llamada que no -necesite autentificación. Por ejemplo, información solo lectura de un +necesite autentificación. Por ejemplo, información de solo lectura de un proyecto de código abierto. Por ejemplo, si queremos conocer información acerca del usuario ``schacon'', podemos ejecutar algo como: @@ -184,7 +184,7 @@ $ curl https://api.github.com/users/schacon Hay muchísimas llamadas como esta para obtener información sobre organizaciones, proyectos, incidencias, commits, es decir, todo lo que podemos ver públicamente en la web de GitHub. Se puede usar la API para -otras cosas como ver un archivo Markdown cualquier o encontrar una +otras cosas como ver un archivo Markdown cualquiera o encontrar una plantilla de `.gitignore`. [source,javascript] @@ -233,14 +233,14 @@ ese momento. Ahora podrás identificarte en el script con el token, en lugar del usuario y la contraseña. Esto está bien porque puedes limitar el ámbito de lo que se quiere hacer y porque el token se puede anular. -También tiene la ventana de incrementar la tasa de accesos. Sin la +También tiene la ventaja de incrementar la tasa de accesos. Sin la autentificación podrás hacer 60 peticiones a la hora. Con una identificación el número de accesos permitidos sube a 5,000 por hora. Realicemos entonces un comentario en una de nuestras incidencias. Por ejemplo, queremos dejar un comentario en la incidencia #6. Para ello, hacemos una petición HTTP POST a `repos///issues//comments` con el -token que acabamos de generar como cabecera Authorization. +token que acabamos de generar como cabecera 'Authorization'. [source,javascript] ---- @@ -272,25 +272,25 @@ en <>. image::images/scripting-06-comment.png[Comentario via API] Puedes usar la API para hacer todo lo que harías en el sitio web: crear y -ajustar hitos, asignar gente a incidencias o pull requests, crear y cambiar -etiquetas, acceder a datos de commit, crear nuevos commits y ramas, abrir, cerrar +ajustar hitos, asignar gente a incidencias o Pull Requests, crear y cambiar +etiquetas, acceder a datos de ``commit'', crear nuevos commits y ramas, abrir, cerrar o fusionar Pull Requests, crear y editar equipos, comentar líneas de cambio en Pull Requests, buscar en el sitio y mucho más. ==== Cambio de estado de un Pull Request Un ejemplo final que veremos es realmente útil si trabajas con Pull Requests. -Cada commit tiene uno o más estados asociados con ellos, y hay una API +Cada ``commit'' tiene uno o más estados asociados con él, y hay una API para alterar y consultar ese estado. Los servicios de integración continua y pruebas hacen uso de esta API para actuar cuando alguien envía código al repositorio, probando el mismo y -devolviendo como resultado si el commit pasó todas las pruebas. Además, -se podría comprobar si el mensaje del commit tiene un formato adecuado, si +devolviendo como resultado si el ``commit'' pasó todas las pruebas. Además, +se podría comprobar si el mensaje del ``commit'' tiene un formato adecuado, si el autor siguió todas las recomendaciones para autores, si fue firmado, etc. Supongamos que tenemos un enganche web en el repositorio que llama a un servicio -web que comprueba si en el mensaje del commit aparece la cadena `Signed-off-by`. +web que comprueba si en el mensaje del ``commit'' aparece la cadena `Signed-off-by`. [source,ruby] ---- @@ -336,14 +336,14 @@ end ---- Creemos que esto es fácil de seguir. En este controlador del enganche, miramos -en cada commit enviado, y buscamos la cadena 'Signed-off-by' en el mensaje de -commit, y finalmente hacemos un HTTP POST al servicio de API +en cada ``commit'' enviado, y buscamos la cadena 'Signed-off-by' en el mensaje de +``commit'', y finalmente hacemos un HTTP POST al servicio de API `/repos///statuses/` con el resultado. En este caso, puedes enviar un estado ('success', 'failure', 'error'), una -descripción de qué ocurrió, un URL objetivo donde el usuario puede +descripción de qué ocurrió, una URL objetivo donde el usuario puede ir a buscar más información y un ``contexto'' en caso de que haya múltiples -estados para un commit. Por ejemplo, un servicio de test puede dar un estado, +estados para un ``commit''. Por ejemplo, un servicio de test puede dar un estado, y un servicio de validación puede dar por su parte su propio estado; el campo ``context'' serviría para diferenciarlos. @@ -355,9 +355,9 @@ configurado, verías algo como <>. image::images/scripting-07-status.png[Estado del commit] Podrás ver entonces una pequeña marca de color verde, que nos indica que -el commit tiene la cadena ``Signed-off-by'' en el mensaje y un aspa roja +el ``commit'' tiene la cadena ``Signed-off-by'' en el mensaje y un aspa roja en aquellos donde el autor olvidase hacer esa firma. También verías -que el Pull Request toma el estado del último commit en la rama y te avisa +que el Pull Request toma el estado del último ``commit'' en la rama y te avisa de si es un fallo. Esto es realmente útil si usas la API para pruebas, y así evitar hacer una fusión accidental de unos commits que han fallado las pruebas. @@ -372,6 +372,6 @@ y .NET. Se puede ir a http://github.com/octokit[] para más información sobre esto, que te ayudarán a manejar peticiones y respuestas a la API de GitHub. Con suerte estas utilidades te ayudarán a personalizar y modificar GitHub para -trabajar mejor con tu forma concreta de trabajar. Para una documentación +integrarlo mejor con tu forma concreta de trabajar. Para una documentación completa de la API así como ayudas para realizar tareas comunes, puedes consultar en https://developer.github.com[].