git: 9c013aa68f - main - [doc-es][articles/committers-guide]: sync with master
- Go to: [ bottom of page ] [ top of archives ] [ this month ]
Date: Tue, 25 Jul 2023 06:47:59 UTC
The branch main has been updated by fernape:
URL: https://cgit.FreeBSD.org/doc/commit/?id=9c013aa68fcfe48f83960e97ad2967c45004c1b2
commit 9c013aa68fcfe48f83960e97ad2967c45004c1b2
Author: Fernando Apesteguía <fernape@FreeBSD.org>
AuthorDate: 2023-07-25 06:42:18 +0000
Commit: Fernando Apesteguía <fernape@FreeBSD.org>
CommitDate: 2023-07-25 06:47:43 +0000
[doc-es][articles/committers-guide]: sync with master
---
.../es/articles/committers-guide/_index.adoc | 1450 +-
.../content/es/articles/committers-guide/_index.po | 16412 ++++++++++---------
2 files changed, 8958 insertions(+), 8904 deletions(-)
diff --git a/documentation/content/es/articles/committers-guide/_index.adoc b/documentation/content/es/articles/committers-guide/_index.adoc
index d9f68a13d1..e8f4275b66 100644
--- a/documentation/content/es/articles/committers-guide/_index.adoc
+++ b/documentation/content/es/articles/committers-guide/_index.adoc
@@ -2,11 +2,11 @@
authors:
-
author: 'The FreeBSD Documentation Project'
-copyright: '1999-2021 The FreeBSD Documentation Project'
+copyright: '1999-2022 The FreeBSD Documentation Project'
description: 'Información de introducción para los committers de FreeBSD'
tags: ["FreeBSD Committer's Guide", "Guide", "Community"]
title: 'Guía para los Committers'
-trademarks: ["freebsd", "coverity", "ibm", "intel", "general"]
+trademarks: ["freebsd", "coverity", "git", "github", "gitlab", "ibm", "intel", "general"]
weight: 25
---
@@ -46,7 +46,7 @@ Resumen
Este documento proporciona información para la comunidad de committers de FreeBSD. Todos los committers nuevos deben leer este documento antes de empezar, y se recomienda encarecidamente a los committers actuales que lo revisen de vez en cuando.
-Casi todos los desarrolladores de FreeBSD tienen derecho de acceso a uno o más repositorios. Sin embargo, algunos desarrolladores no lo tienen, y cierta información aquí expuesta también les afecta. (Por ejemplo, algunas personas sólo tienen derecho a trabajar con la base de datos de reporte de problemas). Por favor lea <<non-committers>> para más información.
+Casi todos los desarrolladores de FreeBSD tienen derecho de acceso a uno o más repositorios. Sin embargo, algunos desarrolladores no lo tienen, y cierta información aquí expuesta también les afecta. (Por ejemplo, algunas personas sólo tienen derecho a trabajar con la base de datos de reporte de problemas.) Por favor lea <<non-committers>> para más información.
Este documento también puede ser de interés para los miembros de la comunidad de FreeBSD que quieran saber más sobre el funcionamiento del proyecto.
@@ -74,19 +74,19 @@ toc::[]
|`smtp.FreeBSD.org:587` (consulta también <<smtp-setup>>).
|`_src/_` Repositorio Git
-|`ssh://git@gitrepo.FreeBSD.org/src.git` (consulta también <<git-getting-started-base-layout>>).
+|`ssh://git@gitrepo.FreeBSD.org/src.git`
|`_doc/_` Repositorio Git
-|`ssh://git@gitrepo.FreeBSD.org/doc.git` (consulta también <<git-getting-started-doc-layout>>).
+|`ssh://git@gitrepo.FreeBSD.org/doc.git`
|`_ports/_` Repositorio Git
-|`ssh://git@gitrepo.FreeBSD.org/ports.git` (consulta también <<git-getting-started-ports-layout>>).
+|`ssh://git@gitrepo.FreeBSD.org/ports.git`
|_Listas de Correo Internas_
-|developers (técnicamente llamada all-developers) doc-developers, doc-committers, ports-developers, ports-committers, src-developers, src-committers. (Cada repositorio del proyecto tiene su propia lista de correo terminada en -developers y -committers. Se pueden encontrar archivos para estas listas en los ficheros [.filename]#/local/mail/repository-name-developers-archive# y [.filename]#/local/mail/repository-name-committers-archive# en el cluster `FreeBSD.org`.)
+|developers (técnicamente llamada all-developers) doc-developers, doc-committers, ports-developers, ports-committers, src-developers, src-committers. (Cada repositorio del proyecto tiene su propia lista de correo terminada en -developers y -committers. Se pueden encontrar archivos para estas listas en los ficheros [.filename]#/local/mail/repository-name-developers-archive# y [.filename]#/local/mail/repository-name-committers-archive# en `freefall.FreeBSD.org`.)
|_Informes mensuales del Core Team_
-|[.filename]#/home/core/public/monthly-reports# en el clúster `FreeBSD.org`.
+|[.filename]#/home/core/public/reports# en el clúster `FreeBSD.org`.
|_Informes mensuales del Ports Management Team_
|[.filename]#/home/portmgr/public/monthly-reports# en el clúster `FreeBSD.org`.
@@ -171,13 +171,13 @@ Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? o
You need a Passphrase to protect your secret key.
....
-<.> Claves de 2048 bits con una expiración de tres años proporcionan una protección adecuada actualmente (2013-12). http://danielpocock.com/rsa-key-sizes-2048-or-4096-bits[] describe la situación en más detalle.
+<.> Claves de 2048 bits con una expiración de tres años proporcionan una protección adecuada actualmente (202-10).
<.> Tres años de vida útil para una clave hacen que sea lo suficientemente corta como para hacer que quede obsoleta por el avance de la potencia de los ordenadores, pero lo suficientemente larga como para reducir los problemas de administración de claves.
<.> Utiliza tu nombre real aquí, preferiblemente coincidente con el nombre de tu documento de identificación oficial para ayudar a otros a verificar tu identidad. En la sección `Comment` se puede introducir texto que ayude a otros a identificarte.
+
-Después de introducir la dirección de correo electrónico, se solicita una contraseña. Los métodos para crear una contraseña segura son bastante polémicos. En lugar de sugerir una única forma, aquí hay algunos enlaces a sitios que describen varios métodos: http://world.std.com/~reinhold/diceware.html[], http://www.iusmentis.com/security/passphrasefaq/[], http://xkcd.com/936/[], http://en.wikipedia.org/wiki/Passphrase[].
+Después de introducir la dirección de correo electrónico, se solicita una contraseña. Los métodos para crear una contraseña segura son bastante polémicos. En lugar de sugerir una única forma, aquí hay algunos enlaces a sitios que describen varios métodos: https://world.std.com/~reinhold/diceware.html[], https://www.iusmentis.com/security/passphrasefaq/[], https://xkcd.com/936/[], https://en.wikipedia.org/wiki/Passphrase[].
====
Protege la clave privada y la contraseña. Si la clave privada o la contraseña fueran comprometidas o reveladas, notifícalo de forma inmediata a mailto:accounts@FreeBSD.org[accounts@FreeBSD.org] y revoca la clave.
@@ -249,7 +249,7 @@ Se anima a los committers a buscar la revisión de su trabajo como parte del pro
=== Política para la actividad de los Committers en otros árboles
* Todos los committers pueden modificar [.filename]#src/share/misc/committers-*.dot#, [.filename]#src/usr.bin/calendar/calendars/calendar.freebsd#, y [.filename]#ports/astro/xearth/files#.
-* Los committers de documentación pueden realizar commits en la documentación de [.filename]#src#, como las páginas man, READMEs, bases de datos de fortune, archivos de calendario y correcciones de comentarios sin la aprobación de un src committer, teniendo en cuenta las normas requeridas para la correcta realización de los commits.
+* Los committers de documentación pueden realizar commits en la documentación de [.filename]#src#, como las páginas del manual, READMEs, bases de datos de fortune, archivos de calendario y correcciones de comentarios sin la aprobación de un src committer, teniendo en cuenta las normas requeridas para la correcta realización de los commits.
* Cualquier committer puede realizar cambios en cualquier otro árbol con un "Approved by" de un committer que no esté tutelado y dispone del commit bit apropiado. Los committers con mentor pueden proporcionar un comentario "Reviewed by" pero no un "Approved by".
* Los committers pueden adquirir commit bit adicionales mediante el proceso habitual de encontrar a un mentor que lo proponga a core, doceng o portmgr, según sea el caso. Una vez aprobados, se añadirán al "acceso" y se producirá el periodo normal de tutoría, que implicará una continuación de "Approved by" durante algún tiempo.
@@ -309,8 +309,14 @@ El objetivo de esta sección es resaltar aquellas partes de Git que se necesitan
Esta sección describe el acceso de lectura-escritura para que los committers hagan push de los commits de los desarrolladores o colaboradores.
+[[git-mini-daily-use]]
===== Uso diario
+[NOTE]
+====
+In the examples below, replace `${repo}` with the name of the desired FreeBSD repository: `doc`, `ports`, or `src`.
+====
+
* Clona el repositorio:
+
[source, shell]
@@ -355,7 +361,7 @@ freebsd https://git.freebsd.org/${repo}.git (fetch)
freebsd git@gitrepo.freebsd.org:${repo}.git (push)
....
+
-De nuevo, date cuenta de que `gitrepo.freebsd.org` cambiará a la forma canónica `repo.freebsd.org` en el futuro.
+De nuevo, date cuenta de que `gitrepo.freebsd.org` ha sido convertido a su forma canónica `repo.freebsd.org`.
* Instala el hook para la plantilla del mensaje de commit:
+
@@ -385,28 +391,37 @@ De forma alternativa, puedes añadir un árbol de trabajo (worktree) para la ram
git worktree add -b admin ../${repo}-admin internal/admin
....
-Para visualizar la rama `internal/admin` en la web: https://cgit.freebsd.org/${repo}/log/?h=internal/admin
+Para visualizar la rama `internal/admin` en la web: `https://cgit.freebsd.org/${repo}/log/?h=internal/admin`
-Para hacer push, especifica el refspec completo:
+For pushing, specify the full refspec:
[source, shell]
....
git push freebsd HEAD:refs/internal/admin
....
-O establece `push.default` a `freebsd` que hará que `git push` empuje la rama actual de vuelta a su upstream por defecto, lo que es más conveniente para nuestro flujo de trabajo:
-
-[source, shell]
-....
-git config push.default freebsd
-....
-
==== Mantenerse Actualizado Con el Árbol src de FreeBSD
[[keeping_current]]
Primer paso: clonar un árbol. Esto descarga el árbol completo. Hay dos formas de hacerlo. La mayoría de la gente quiere hacer un clonado profundo del repositorio. Sin embargo, hay momentos en los que quieres hacer un clonado superficial.
-===== Nombres de las ramas
-Los nombres de las ramas en el nuevo repositorio Git son similares a los nombres antiguos. Para las ramas estables, existe stable/X donde X es el número mayor de release (como 11 o 12). La rama principal en el nuevo repositorio es 'main'. La rama principal en el antiguo mirror de GitHub era 'master', pero ahora es 'main'. Ambas reflejan los valores por defecto de Git en el momento en que fueron creadas. La rama 'main' es la rama por defecto si omites las opciones '-b branch' o '--branch branch' abajo.
+===== Nombres de las Ramas
+FreeBSD-CURRENT utiliza la rama `main`.
+
+`main` es la rama por defecto.
+
+Para FreeBSD-STABLE, los nombres de las ramas incluyen `stable/12` y `stable/13`.
+
+Para FreeBSD-RELEASE, los nombres de las ramas de ingeniería de versiones incluyen `releng/12.4` y `releng/13.2`.
+
+https://www.freebsd.org/releng/[] muestra:
+
+* ramas `main` y `stable/⋯` abiertas
+* ramas `releng/⋯` , cada una de las cuales es congelada cuando se etiqueta una versión.
+
+Ejemplos:
+
+* etiqueta https://cgit.freebsd.org/src/tag/?h=release/13.1.0[release/13.1.0] en la rama https://cgit.freebsd.org/src/log/?h=releng/13.1[releng/13.1]
+* etiqueta https://cgit.freebsd.org/src/tag/?h=release/13.2.0[release/13.2.0] en la rama https://cgit.freebsd.org/src/log/?h=releng/13.2[releng/13.2].
===== Repositorios
Por favor consulta <<admin,Detalles Administrativos>> para la última información sobre dónde obtener las fuentes de FreeBSD. El $URL que se muestra abajo se puede obtener en esa página.
@@ -417,9 +432,9 @@ Nota: El proyecto no utiliza submódulos ya que no encajan en nuestro flujo de t
Un clonado profundo se trae el árbol entero, así como las ramas y toda la historia. Es lo más fácil de hacer. También te permite usar la característica de los árboles de trabajo para tener todas tus ramas activas en directorios separados pero con una sola copia del repositorio.
[source, shell]
....
-% git clone -o freebsd $URL -b branch [dir]
+% git clone -o freebsd $URL -b branch [<directory>]
....
-es como haces un clonado profundo. 'branch' debería ser una de las ramas listadas en la sección anterior. Es opcional si es la rama principal. 'dir' es un directorio opcional donde dejar el clon (por defecto será el nombre del repo que estás clonando (src, doc, etc)).
+-- creará un clonado profundo. `branch` debería ser una de las ramas listadas en la sección anterior. Si no se proporciona `branch` se usará la rama por defecto (`main`). Si no se proporciona `<directory>` se usará como nombre del nuevo directorio el que coincida con el nombre del repositorio ([.filename]#doc#, [.filename]#ports# o [.filename]#src#).
Querrás un clonado profundo si estás interesado en el histórico, planeas hacer cambios locales, o planeas trabajar en más de una rama. Es la forma más fácil también de mantenerse actualizado. Si estás interesado en el histórico pero vas a trabajar sólo con una rama y andas corto de espacio, también puedes usar --single-branch para descargar la rama (aunque algunos commits de merge no referenciarán la rama desde la que se mergearon lo que podría ser importante para algunos usuarios interesados en versiones detalladas del histórico).
@@ -432,7 +447,7 @@ Un clonado superficial sólo copia el código más actual, pero nada o poco del
% git clone -o freebsd -b branch --depth 1 $URL [dir]
....
-Esto clona el repositorio, pero sólo la versión más reciente. El resto del histórico no se descarga. Si cambiaras de opinión más tarde, puedes hacer 'git fetch --unshallow' para obtener el histórico antiguo.
+Esto clona el repositorio, pero sólo la versión más reciente. El resto del histórico no se descarga. Si cambiaras de opinión más tarde, puedes hacer `git fetch --unshallow` para obtener el histórico antiguo.
[WARNING]
====
@@ -463,11 +478,11 @@ Para actualizar ambos tipos de árbol utilizan los mismos comandos. Esto se trae
....
actualizará el árbol. En Git, un merge tipo 'fast forward' es aquel que sólo necesita establecer el puntero a una rama nueva y no necesita recrear los commits. Haciendo siempre un merge/pull de tipo 'fast forward', te asegurarás de que tienes una copia exacta del árbol de FreeBSD. Esto será importante si quieres mantener parches locales.
-Lee más abajo para saber cómo gestionar cambios locales. Lo más sencillo es utilizar --autostash con el comando 'git pull', pero hay disponibles opciones más sofisticadas.
+Lee más abajo para saber cómo gestionar cambios locales. Lo más sencillo es utilizar `--autostash` con el comando `git pull`, pero hay disponibles opciones más sofisticadas.
==== Seleccionando una Versión Específica
-En Git, 'git checkout' se trae tanto ramas como versiones específicas. Las versiones de Git son hashes largos en lugar de números secuenciales.
+En Git, `git checkout` se trae tanto ramas como versiones específicas. Las versiones de Git son hashes largos en lugar de números secuenciales.
Cuando te traes una versión específica, simplemente especifica en la línea de comando el hash que quieres (el comando git log te ayudará a decidir cuál es el hash que quieres):
[source, shell]
@@ -495,20 +510,20 @@ donde la última línea es generada a partir del hash que te has traído y la pr
==== Bisección
A veces, algo va mal. La última versión funcionó pero la última a la que te has actualizado no. Un desarrollador podría pedirte que bisecciones el problema para localizar qué commit causó la regresión.
-Git hacer fácil biseccionar cambios con un potente comando 'git bisect'. Aquí hay una breve introducción a cómo usarlo. Para más información, puedes ver https://www.metaltoad.com/blog/beginners-guide-git-bisect-process-elimination o https://git-scm.com/docs/git-bisect para más detalles. La página de manual de git-bisect es buena describiendo lo que puede salir mal, qué hacer cuando las versiones no compilan, cuándo quieres usar otros términos diferentes de 'bueno' y 'malo', etc, nada de lo cual se cubrirá aquí.
+Git hacer fácil biseccionar cambios con un potente comando `git bisect`. Aquí hay una breve introducción a cómo usarlo. Para más información, puedes ver https://www.metaltoad.com/blog/beginners-guide-git-bisect-process-elimination o https://git-scm.com/docs/git-bisect para más detalles. La página de manual de git-bisect es buena describiendo lo que puede salir mal, qué hacer cuando las versiones no compilan, cuándo quieres usar otros términos diferentes de 'bueno' y 'malo', etc, nada de lo cual se cubrirá aquí.
-`git bisect start --first-parent` comenzará el proceso de bisección. Después necesitarás decirle un rango para que trabaje. 'git bisect good XXXXXX' le dirá la revisión que funciona y 'git bisect bad XXXXX' le dirá la revisión mala. La revisión mala casi siempre será HEAD (un tag especial para lo que te has traído). La versión buena será la última que te trajiste. El argumento `--first-parent` es necesario para que llamadas siguientes a `git bisect` no intenten traerse una rama externa que carece de las fuentes completas de FreeBSD.
+`git bisect start --first-parent` comenzará el proceso de bisección. Después necesitarás decirle un rango para que trabaje. `git bisect good XXXXXX` le dirá la revisión que funciona y `git bisect bad XXXXX` le dirá la revisión mala. La revisión mala casi siempre será HEAD (un tag especial para lo que te has traído). La versión buena será la última que te trajiste. El argumento `--first-parent` es necesario para que llamadas siguientes a `git bisect` no intenten traerse una rama externa que carece de las fuentes completas de FreeBSD.
[TIP]
====
-Si quieres saber la última versión que te trajiste, deberías usar 'git reflog':
+Si quieres saber la última versión que te trajiste, deberías usar `git reflog`:
[source, shell]
....
5ef0bd68b515 (HEAD -> main, freebsd/main, freebsd/HEAD) HEAD@{0}: pull --ff-only: Fast-forward
a8163e165c5b (upstream/main) HEAD@{1}: checkout: moving from b6fb97efb682994f59b21fe4efb3fcfc0e5b9eeb to main
...
....
-me muestra moviendo el directorio de trabajo a la rama principal (a816...) y después actualizando desde el origen (a 5ef0...). En esta caso, malo sería HEAD (o 5rf0bd68) y bueno sería a8163e165. Como puedes ver en la salida, HEAD@{1} también funciona, pero no es a prueba de fallos si has hecho otras cosas en tu árbol después de actualizar, pero antes de que descubrieras que tenías que hacer bisección.
+me muestra moviendo el directorio de trabajo a la rama `main` (a816...) y después actualizando desde el origen (a 5ef0...). En esta caso, malo sería HEAD (o 5rf0bd68) y bueno sería a8163e165. Como puedes ver en la salida, HEAD@{1} también funciona, pero no es a prueba de fallos si has hecho otras cosas en tu árbol después de actualizar, pero antes de que descubrieras que tenías que hacer bisección.
====
Primero establece la versión 'good', luego la mala (aunque el orden no importa). Cuando establezcas la versión mala, te dará algunas estadísticas sobre el proceso:
@@ -521,7 +536,7 @@ Bisecting: 1722 revisions left to test after this (roughly 11 steps)
[c427b3158fd8225f6afc09e7e6f62326f9e4de7e] Fixup r361997 by balancing parens. Duh.
....
-Después deberías compilar/instalar esa versión. Si es buena, teclearías 'git bisect good' si no 'git bisect bad'. Si la versión no compila, teclea 'git bisect skip'. Recibirás un mensaje similar al de arriba para cada paso. Una vez que hayas terminado, informa al desarrollador de la versión mala (o arregla el fallo tú mismo y envía un parche). 'git bisect reset' terminará el proceso y te devolverá a donde empezaste (normalmente a la punta de main). De nuevo, el manual de git-bisect (enlazado arriba) es un buen recurso para cuando las cosas van mal o en casos inusuales.
+Después deberías compilar/instalar esa versión. Si es buena, teclearías `git bisect good` si no `git bisect bad`. Si la versión no compila, teclea `git bisect skip`. Recibirás un mensaje similar al de arriba para cada paso. Una vez que hayas terminado, informa al desarrollador de la versión mala (o arregla el fallo tú mismo y envía un parche). `git bisect reset` terminará el proceso y te devolverá a donde empezaste (normalmente a la punta de `main`). De nuevo, el manual de git-bisect (enlazado arriba) es un buen recurso para cuando las cosas van mal o en casos inusuales.
[[git-gpg-signing]]
==== Firmando los commits, tags, y pushes, con GnuPG
@@ -573,7 +588,7 @@ El árbol de ports funciona de la misma forma. Los nombres de las ramas son dife
La interfaz web cgit del repositorio para ser usada desde navegadores web está en https://cgit.FreeBSD.org/ports/. El repositorio Git de producción está en https://git.FreeBSD.org/ports.git y en ssh://anongit@git.FreeBSD.org/ports.git (o anongit@git.FreeBSD.org:ports.git).
-También hay un mirror en GitHub, lee extref:{handbook}/mirrors[Mirrors externos, mirrors] para un resumen. La rama 'current' es 'main'. Las ramas trimestrales se llaman 'yyyyQn' para el año 'yyyy' y el trimestre 'n'.
+También hay un mirror en GitHub, lee extref:{handbook}/mirrors[Mirrors externos, mirrors] para un resumen. La rama más actual es 'main'. Las ramas _trimestrales_ se llaman `yyyyQn` para el año 'yyyy' y el trimestre 'n'.
[[port-commit-message-formats]]
===== Formatos de mensaje de commits
@@ -602,20 +617,20 @@ Si hay campos de metadatos se debería utilizar otra línea en blanco, de forma
====
==== Gestionando Cambios Locales
-Esta sección trata de controlar cambios locales. Si no tienes cambios locales, puedes dejar de leer (es la última sección y está bien saltársela).
+This section addresses tracking local changes. If you have no local changes you can skip this section.
Un punto que es importante para todos ellos: todos los cambios son locales hasta que se hace push. A diferencia de Subversion, Git utiliza un modelo distribuido. Para la mayoría de los usuarios y los casos, hay poca diferencia. Sin embargo, si tienes cambios locales, puedes usar la misma herramienta para gestionarlos que la que usara para traerte los cambios de FreeBSD. Todos los cambios para los que no has hecho push son locales y se pueden cambiar fácilmente (git rebase, discutido más abajo hace esto).
===== Manteniendo cambios locales
-La forma más sencilla de mantener cambios locales (especialmente si son triviales) es usar 'git stash'. En su forma más simple, utilizas 'git stash' para grabar los cambios (lo que los empuja a la pila del stash). La mayoría de la gente utiliza esto para guardar cambios antes de actualizar un árbol como se describe arriba. Después utilizan 'git stash apply' para reaplicarlos al árbol. El stash es una pila de cambios que se puede examinar con 'git stash list'. La página del manual de git-stash (https://git-scm.com/docs/git-stash) tiene todos los detalles.
+La forma más sencilla de mantener cambios locales (especialmente si son triviales) es usar `git stash`. En su forma más simple, utilizas `git stash` para grabar los cambios (lo que los empuja a la pila del stash). La mayoría de la gente utiliza esto para guardar cambios antes de actualizar un árbol como se describe arriba. Después utilizan `git stash apply` para reaplicarlos al árbol. El stash es una pila de cambios que se puede examinar con `git stash list`. La página del manual de git-stash (https://git-scm.com/docs/git-stash) tiene todos los detalles.
-Este método va bien cuando tienes pequeños cambios en el árbol. Cuando tienes algo no trivial, probablemente sea mejor mantener una rama local y rebasarla. Guardar los cambios (stashing) también es algo integrado en el comando 'git pull': simplemente añade '--autostash' en la línea de comando.
+Este método va bien cuando tienes pequeños cambios en el árbol. Cuando tienes algo no trivial, probablemente sea mejor mantener una rama local y rebasarla. Guardar los cambios (stashing) también es algo integrado en el comando `git pull`: simplemente añade `--autostash` en la línea de comando.
===== Manteniendo una rama local
[[keeping_a_local_branch]]
Es mucho más fácil mantener una rama local con Git que con Subversion. En Subversion necesitas mergear el commit, y resolver los conflictos. Esto es manejable, pero puede llevar a un histórico complicado que es difícil de mover al origen (upstream) si fuera necesario, o difícil de replicar si lo necesitas. Git también permite mergear, con los mismos problemas. Esa es una forma de gestionar la rama, pero es la menos flexible.
-Además de hacer merging, Git soporta el concepto de rebase que evita estos problemas. El comando 'git rebase' rehace todos los commits de una rama en un lugar nuevo de la rama padre. Cubriremos los casos más comunes que surgen al usarlo.
+Además de hacer merging, Git soporta el concepto de rebase que evita estos problemas. El comando `git rebase` rehace todos los commits de una rama en un lugar nuevo de la rama padre. Cubriremos los casos más comunes que surgen al usarlo.
====== Crear una rama
@@ -644,7 +659,7 @@ index 7378268867ef..cfc3f4342531 100644
% git commit ls.c
....
-El commit te llevará a un editor para que describas lo que has hecho. Una vez hecho esto, tienes tu propia rama **local** en el repo de Git. Compila e instala como harías normalmente, siguiendo las instrucciones del manual. Git es diferente a otros sistemas de control de versiones en cuanto que tienes que decirle explícitamente qué ficheros quieres incluir en el commit. He optado por hacerlo en la linea de comando pero también puedes hacerlo con 'git add' que se cubre en muchos de los tutoriales más detallados.
+El commit te llevará a un editor para que describas lo que has hecho. Una vez hecho esto, tienes tu propia rama **local** en el repo de Git. Compila e instala como harías normalmente, siguiendo las instrucciones del manual. Git es diferente a otros sistemas de control de versiones en cuanto que tienes que decirle explícitamente qué ficheros quieres incluir en el commit. He optado por hacerlo en la linea de comando pero también puedes hacerlo con `git add` que se cubre en muchos de los tutoriales más detallados.
====== Momento de actualizar
@@ -677,91 +692,59 @@ Could not apply 646e0f9cda11... no color ls
....
que da miedo. Si abres un editor, verás que es una resolución de conflicto típica de 3 vías con la que podrías estar familiarizado de otros sistemas de control de código (el resto de ls.c se ha omitido):
[source, shell]
+ <<<<<<< HEAD
+ #ifdef COLORLS_NEW
+ #include <terminfo.h>
+ =======
+ #undef COLORLS
+ #ifdef COLORLS
+ #include <termcap.h>
+ >>>>>>> 646e0f9cda11... no color ls
....
-<<<<<<< HEAD
-#ifdef COLORLS_NEW
-#include <terminfo.h>
-=======
-#undef COLORLS
-#ifdef COLORLS
-#include <termcap.h>
->>>>>>> 646e0f9cda11... no color ls
-....
-El código nuevo está primero, y tu código segundo. El arreglo correcto aquí es añadir simplemente #undef COLORLS_NEW ante de @ifdef y después borrar los cambios antiguos:
-[source, shell]
+El código nuevo está primero, y tu código segundo.
+El arreglo correcto aquí es añadir simplemente #undef COLORLS_NEW ante de @ifdef y después borrar los cambios antiguos:
+[source,shell]
....
-#undef COLORLS_NEW
-#ifdef COLORLS_NEW
-#include <terminfo.h>
+#undef COLORLS_NEW #ifdef COLORLS_NEW #include <terminfo.h>
....
-guarda el fichero. El rebase fue interrumpido, así que tienes que completarlo:
-[source, shell]
+guarda el fichero.
+El rebase fue interrumpido, así que tienes que completarlo:
+[source,shell]
....
-% git add ls.c
-% git rebase --continue
+% git add ls.c % git rebase --continue
....
-que le dice a Git que ls.c ha sido arreglado y que puede continuar con el rebase. Puesto que hubo un conflicto, se te dirigirá al editor para actualizar el mensaje de commit si es necesario. Si el mensaje sigue siendo preciso, simplemente sal del editor.
+que le dice a Git que ls.c ha sido arreglado y que puede continuar con el rebase.
+Puesto que hubo un conflicto, se te dirigirá al editor para actualizar el mensaje de commit si es necesario.
+Si el mensaje sigue siendo preciso, simplemente sal del editor.
-Si te atascas durante el rebase, no te asustes. git rebase --abort te llevará de nuevo a un estado limpio. Sin embargo, es importante empezar con un árbol sin modificar. Una nota: el 'git reflog' mencionado arriba es útil aquí ya que tendrá una lista de todos los commits (intermedios) que puedes ver, inspeccionar o seleccionar con cherry-pick.
+Si te atascas durante el rebase, no te asustes. git rebase --abort te llevará de nuevo a un estado limpio.
+Sin embargo, es importante empezar con un árbol sin modificar.
+Una nota: el `git reflog` mencionado arriba es útil aquí ya que tendrá una lista de todos los commits (intermedios) que puedes ver, inspeccionar o seleccionar con cherry-pick.
-Para saber más sobre esto, https://www.freecodecamp.org/news/the-ultimate-guide-to-git-merge-and-git-rebase/ proporciona un tratamiento bastante amplio. Es un buen recursos para problemas que puedan surgir de forma ocasional pero que son muy oscuros para esta guía.
+Para saber más sobre esto, https://www.freecodecamp.org/news/the-ultimate-guide-to-git-merge-and-git-rebase/ proporciona un tratamiento bastante amplio.
+Es un buen recursos para problemas que puedan surgir de forma ocasional pero que son muy oscuros para esta guía.
===== Cambiando a una Rama Diferente de FreeBSD
-Si quieres cambiar de stable/12 a la rama current. Si tienes un clonado profundo, lo siguiente es suficiente:
-[source, shell]
+Si quieres cambiar de stable/12 a la rama current. Si tienes un clonado profundo, lo siguiente es suficiente: [source,shell]
....
-% git checkout main
-% # build and install here...
+% git checkout main % # build and install here...
....
-Sin embargo, si tienes una rama local, hay algún problema. Primero, rebase sobreescribirá el histórico de forma que querrás hacer algo para salvarlo. Segundo, saltar entre ramas suele causar más conflictos. Si imaginamos que el ejemplo anterior era relativo a stable/12, entonces para moverlo a main, sugeriría lo siguiente:
-[source, shell]
+Sin embargo, si tienes una rama local, hay algún problema.
+Primero, rebase sobreescribirá el histórico de forma que querrás hacer algo para salvarlo.
+Segundo, saltar entre ramas suele causar más conflictos.
+Si imaginamos que el ejemplo anterior era relativo a stable/12, entonces para moverlo a `main`, sugeriría lo siguiente:
+[source,shell]
....
% git checkout no-color-ls
% git checkout -b no-color-ls-stable-12 # create another name for this branch
% git rebase -i stable/12 no-color-ls --onto main
....
-Lo anterior se trae no-color-ls. Luego le da un nombre nuevo (no-color-ls-stable-12) en caso de que necesites volver a ella. Después rebase sobre la rama main. Esto encontrará todos los commits de la rama no-color-ls actual (hacia atrás hasta donde se encuentra con la rama stable/12) y después los aplicará de nuevo sobre la rama main creando una nueva rama no-color-ls allí (para lo cual te hice crear un nombre tipo place holder).
-
-===== Migrando desde un clon de Git existente
-Si tienes trabajo basado en una conversión previa de Git o una conversión local git-svn, migrar al nuevo repositorio puede suponer algunos problemas porque Git no tiene conocimiento acerca de la conexión entre ambos.
-
-Cuando sólo tienes unos pocos cambios locales, la forma más fácil sería escoger esos cambios y llevarlos a la nueva base:
-[source, shell]
-....
-% git checkout main
-% git cherry-pick old_branch..your_branch
-....
-O alternativamente, haz lo mismo con un rebase:
-[source, shell]
-....
-% git rebase --onto main master your_branch
-....
-
-Si haces muchos cambios, probablemente quieras hacer un merge. La idea es crear un punto de merge que consolida el histórico de old_branch, y el nuevo repositorio de FreeBSD (main).
-
-Puedes averiguarlo buscando un mismo commit que se encuentre en ambos padres:
-[source, shell]
-....
-% git show old_branch
-....
-Verás un mensaje de commit, ahora búscalo en la rama nueva:
-[source, shell]
-....
-% git log --grep="commit message on old_branch" freebsd/main
-....
-ayudaría a localizar el commit hash en la rama nueva, crea una rama de ayuda (en el ejemplo lo llamamos 'stage') a partir del hash:
-[source, shell]
-....
-% git checkout -b stage _hash_found_from_git_log_
-....
-Luego realiza un merge de la rama vieja:
-[source, shell]
-....
-% git merge -s ours -m "Mark old branch as merged" old_branch
-....
-Con esto, es posible mergear tu rama de trabajo o la rama principal en cualquier orden sin problema. Eventualmente, cuando estés listo para hacer commit de tu trabajo de vuelta a main, puedes hacer un rebase a main, o hacer un commit tipo squash combinando todo en un solo commit.
+Lo anterior se trae no-color-ls.
+Luego le da un nombre nuevo (no-color-ls-stable-12) en caso de que necesites volver a ella.
+Después rebase sobre la rama `main`.
+Esto encontrará todos los commits de la rama no-color-ls actual (hacia atrás hasta donde se encuentra con la rama stable/12) y después los aplicará de nuevo sobre la rama main creando una nueva rama no-color-ls allí (para lo cual te hice crear un nombre tipo place holder).
[[mfc-with-git]]
=== Procedimientos MFC (Merge From Current)
@@ -771,127 +754,113 @@ El flujo de trabajo de MFC se puede resumir como `git cherry-pick -x` más `git
==== MFC de un sólo commit
-[source, shell]
+[source,shell]
....
-% git checkout stable/X
-% git cherry-pick -x $HASH --edit
+% git checkout stable/X % git cherry-pick -x $HASH --edit
....
-Para commits MFC, por ejemplo una importación externa, necesitarías especificar un padre para cherry-pick. Normalmente, sería el "primer padre" de la rama de la que estás haciendo cherry-pick, así que:
+Para commits MFC, por ejemplo una importación externa, necesitarías especificar un padre para cherry-pick.
+Normalmente, sería el "primer padre" de la rama de la que estás haciendo cherry-pick, así que:
-[source, shell]
+[source,shell]
....
-% git checkout stable/X
-% git cherry-pick -x $HASH -m 1 --edit
+% git checkout stable/X % git cherry-pick -x $HASH -m 1 --edit
....
Si algo va mal, necesitarás abortar el cherry-pick con `git cherry-pick --abort` o arreglarlo y hacer un `git cherry-pick --continue`.
-Una vez terminado el cherry-pick, empuja con `git push`. Si recibes un error por haber perdido una carrera por el commit, utiliza `git pull --rebase` y prueba a empujarlo de nuevo.
+Una vez terminado el cherry-pick, empuja con `git push`.
+Si recibes un error por haber perdido una carrera por el commit, utiliza `git pull --rebase` y prueba a empujarlo de nuevo.
==== MFC a una rama RELENG
Se necesita más cuidado para hacer MFCs a ramas para las cuales se necesita aprobación. El proceso es el mismo tanto para un merge típico como para un commit directo excepcional.
-* Haz merge o un commit directo a la rama `stable/X` apropiada antes de mergear a la rama `releng/X.Y`.
-* Utiliza el hash de la rama `stable/X` para el MFC a la rama `releng/X.Y`.
-* Deja ambas lineas "cherry picked from" en el mensaje de commit.
+* Integra o hace commit directamente a la rama `stable/X` apropiada antes de integrarlo en la rama `releng/X.Y`.
+* Utiliza el hash que está en la rama `stable/X` para el MFC a la rama `releng/X.Y`.
+* Deja ambas líneas "cherry picked from" en el mensaje de commit.
* Asegúrate de añadir la línea `Approved by:` cuando estés en el editor.
-[source, shell]
+[source,shell]
....
-% git checkout releng/13.0
-% git cherry-pick -x $HASH --edit
+% git checkout releng/13.0 % git cherry-pick -x $HASH --edit
....
Si se te olvida añadir la línea `Approved by:`, puedes hacer un `git commit --amend` para editar el mensaje de commit antes de empujar los cambios.
==== MFC de varios commits
-[source, shell]
+[source,shell]
....
-% git checkout -b tmp-branch stable/X
-% for h in $HASH_LIST; do git cherry-pick -x $h; done
-% git rebase -i stable/X
-# mark each of the commits after the first as 'squash'
-# Update the commit message to reflect all elements of commit, if necessary.
-# Be sure to retain the "cherry picked from" lines.
-% git push freebsd HEAD:stable/X
+% git checkout -b tmp-branch stable/X % for h in $HASH_LIST; do git cherry-pick -x $h; done % git rebase -i stable/X # mark each of the commits after the first as 'squash' # Actualiza el mensaje de commit para reflejar todos los cambios del mismo, si fuera necesario. # Asegúrate de mantener las líneas "cherry picked from". % git push freebsd HEAD:stable/X
....
Si el push falla por perder la carrera del commit, haz rebase y prueba de nuevo:
-[source, shell]
+[source,shell]
....
-% git checkout stable/X
-% git pull
-% git checkout tmp-branch
-% git rebase stable/X
-% git push freebsd HEAD:stable/X
+% git checkout stable/X % git pull % git checkout tmp-branch % git rebase stable/X % git push freebsd HEAD:stable/X
....
Una vez que el MFC se ha completado, puedes borrar la rama temporal:
-[source, shell]
+[source,shell]
....
-% git checkout stable/X
-% git branch -d tmp-branch
+% git checkout stable/X % git branch -d tmp-branch
....
==== Haciendo MFC de una importación externa
-Las importaciones externas son lo único en el árbol que crean un commit tipo merge en la línea principal. Seleccionar commits tipo merge en stable/XX representa una dificultad adicional porque hay dos padres para un commit tipo merge. En general, querrás la diferencia del primer padre ya que es la diferencia con la línea principal (aunque podría haber algunas excepciones).
+Las importaciones externas son lo único en el árbol que crean un commit tipo merge en la rama `main`. Seleccionar commits tipo merge en stable/XX representa una dificultad adicional porque hay dos padres para un commit tipo merge. En general, querrás la diferencia del primer padre ya que es la diferencia con `main` (aunque podría haber algunas excepciones).
-[source, shell]
+[source,shell]
....
% git cherry-pick -x -m 1 $HASH
....
-es normalmente lo que quieres. Esto le dirá a cherry-pick que aplique el diff correcto.
+es normalmente lo que quieres.
+Esto le dirá a cherry-pick que aplique el diff correcto.
-Hay algunos pocos casos (con suerte) donde es posible que la línea principal haya sido mergeada hacia atrás por el script de conversión. Si ese fuera el caso (y todavía no hemos encontrado ninguno), cambiarías lo de arriba por '-m 2' para escoger el padre adecuado. Simplemente haz
-[source, shell]
+Hay algunos pocos casos (con suerte) donde es posible que la rama `main` haya sido mergeada hacia atrás por el script de conversión.
+Si ese fuera el caso (y todavía no hemos encontrado ninguno), cambiarías lo de arriba por '-m 2' para escoger el padre adecuado.
+Simplemente haz:
+[source,shell]
....
-% git cherry-pick --abort
-% git cherry-pick -x -m 2 $HASH
+% git cherry-pick --abort % git cherry-pick -x -m 2 $HASH
....
para hacerlo. El `--abort` limpiará el primer intento fallido.
==== Rehaciendo un MFC
-Si haces un MFC y va terriblemente mal y quieres empezar de nuevo, lo más fácil es usar `git reset --hard` así:
-[source, shell]
+Si haces un MFC y va terriblemente mal y quieres empezar de nuevo, lo más fácil es usar `git reset --hard` así: [source,shell]
....
% git reset --hard freebsd/stable/12
....
-aunque si tienes algunas revisiones que quieres mantener, y otras que no, es mejor usar 'git rebase -i '.
+aunque si tienes algunas revisiones que quieres mantener, y otras que no,es mejor usar `git rebase -i`.
==== Consideraciones cuando se hace un MFC
Cuando se hace commit the commits the código fuente a las ramas stable y releng, tenemos los siguientes objetivos:
-* Marcar claramente los commits directos y diferenciarlos de commits que traen un cambio desde otra rama.
-* Evitar introducir cambios que rompan algo en stable y releng.
-* Permitir a los desarrolladores determinar qué cambios han sido o no traídos de una u otra rama.
+* Señala claramente los commits directos de aquellos que introducen un cambio desde otra rama.
+* Evita introducir errores en las ramas stable y releng.
+* Permite a los desarrolladores determinar qué cambias han sido o no traídos desde otra rama.
Con Subversion, usábamos las siguientes prácticas para conseguir estos objetivos:
-* Usar las etiquetas 'MFC' y 'MFS' para marcar los cambios mergeados desde otra rama.
-* Compactar commits que arreglan problemas en un commit principal cuando se mergea un cambio.
-* Registrar mergeinfo de forma que `svn mergeinfo --show-revs` funcione.
+* Usar las etiquetas `MFC` y `MFS` para marcar los commits que integran cambios desde otra rama.
+* Compactar los commits de correcciones en el commit principal cuando se integra un cambio.
+* Grabar mergeinfo de forma que `svn mergeinfo --show-revs` funcionara.
-Con Git, necesitaremos usar diferentes estrategias para conseguir los mismos objetivos. Este documento trata de definir las mejores prácticas para conseguir estos objetivos con Git cuando se mergean cambios de código fuente. En general, tratamos de usar el soporte nativo de Git para conseguir los objetivos en lugar de forzar a realizar las prácticas construidas sobre el modelo de Subversion.
+Con Git, necesitaremos usar diferentes estrategias para conseguir los mismos objetivos.
+Este documento trata de definir las mejores prácticas para conseguir estos objetivos con Git cuando se mergean cambios de código fuente.
+En general, tratamos de usar el soporte nativo de Git para conseguir los objetivos en lugar de forzar a realizar las prácticas construidas sobre el modelo de Subversion.
-Una nota general: debido a las diferencias técnicas con Git, no utilizaremos los "merge commits" de Git (creados mediante `git merge`) en las ramas stable o releng. En su lugar, cuando este documento habla de "merge commits", significa el commit original hecho en `main` que es replicado o "aterrizado" (landed) en una rama stable, o un commit de una rama stable que es replicado a una rama releng con alguna variación de `git cherry-pick`.
+Una nota general: debido a las diferencias técnicas con Git, no utilizaremos los "merge commits" de Git (creados mediante `git merge`) en las ramas stable o releng.
+En su lugar, cuando este documento habla de "merge commits", significa el commit original hecho en `main` que es replicado o "aterrizado" (landed) en una rama stable, o un commit de una rama stable que es replicado a una rama releng con alguna variación de `git cherry-pick`.
==== Encontrando Hashes Seleccionables para MFC
-Git proporciona algo de soporte para esto mediante los comandos `git cherry` y `git log --cherry`. Estos comandos comparan los diffs en crudo de los commits (pero no otros metadatos como los mensajes de log) para determinar si dos commits son idénticos. Esto funciona bien cuando cada commit de head se lleva como un sólo commit a la rama stable, pero falla si múltiples commits de main se compactan juntos como un sólo commit en la rama stable.
-
-Hay algunas opciones para resolver esto:
-
-1. Podríamos prohibir el compactado de commits y en su lugar requerir que los committers preparen todos los commits tipo fixup / follow-up a stable en un solo push. Esto alcanzaría el objetivo de estabilidad en las ramas stable y releng ya que los pushes son atómicos y los usuarios que hace un pull simple nunca acabarán teniendo un árbol que tiene el commit principal sin los arreglos (fixups). `git bisect` también es capaz de lidiar con este modelo vía `git bisect skip`.
-
-2. Podríamos adoptar un estilo consistente para describir los MFCs y escribir nuestras propias herramientas que envuelvan `git cherry` para determinar la lista de commits seleccionables. Una aproximación sencilla podría ser usar la sintaxis de `git cherry-pick -x`, pero requiere que un commit compactado liste todos los hashes (uno por línea) al final del mensaje de commit. Los desarrolladores podrían hacer esto utilizando `git cherry-pick -x` para cada commit individual en una rama y después usar `git rebase` para compactar los commits en uno solo, pero recogiendo las anotaciones de `-x` al final del log del commit.
+Git proporciona algo de soporte para esto mediante los comandos `git cherry` y `git log --cherry`. Estos comandos comparan los diffs en crudo de los commits (pero no otros metadatos como los mensajes de log) para determinar si dos commits son idénticos. Esto funciona bien cuando cada commit de `main` se lleva como un sólo commit a la rama stable, pero falla si múltiples commits de `main` se compactan juntos como un sólo commit en la rama stable. El proyecto utiliza mucho `git cherry-pick -x` preservando todas las líneas para evitar estas dificultades y funciona con herramientas automatizadas.
==== Estándares para los mensajes de commit
===== Marcar MFCs
@@ -906,263 +875,16 @@ Cuando se mergean varios commits, mantén todas las líneas "cherry picked from"
Un área que no estaba documentada de forma clara con Subversion (ni con CVS) era cómo formatear los metadatos en los mensajes de log para los commits tipo MFC. ¿Debería incluir los metadatos del commit original sin modificar o se debería modificar para reflejar la información acerca del propio commit MFC?
-Históricamente la práctica ha variado, aunque parte de la variación es por campo. Por ejemplo, MFCs relativos a un PR normalmente incluyen el campo PR en el MFC de forma que los commits MFC se incluyen en el log de autoría del sistema de reportes de error (bug tracker). Con otros campos está menos claro. Por ejemplo, Phabricator muestra la diferencia entre el último commit etiquetado a una revisión, de forma que incluir URLs de Phabricator reemplaza el commit `main` con los commits "aterrizados". La lista de revisores tampoco está clara. Si un revisor ha aprobado un cambio a `main`, ¿significa eso que han aprobado el commit MFC? ¿Es cierto si el código es idéntico o con sólo cambios triviales? Claramente no es cierto para trabajos más extensivos. Incluso para código idéntico ¿qué pasa si el commit no tiene conflicto pero introduce un cambio en el ABI? Un revisor podría haber dado el visto bueno para un commit en `main` debido al rompimiento del ABI pero podría no
aprobar el mergeado del mismo commit tal cual. Cada uno tiene que usar su mejor juicio hasta que acordemos unas directrices claras.
+Históricamente la práctica ha variado, aunque parte de la variación es por campo. Por ejemplo, MFCs relativos a un PR normalmente incluyen el campo PR en el MFC de forma que los commits MFC se incluyen en el log de autoría del sistema de reportes de error (bug tracker). Con otros campos está menos claro. Por ejemplo, Phabricator muestra la diferencia entre el último commit etiquetado a una revisión, de forma que incluir URLs de Phabricator reemplaza el commit principal con los commits "aterrizados". La lista de revisores tampoco está clara. Si un revisor ha aprobado un cambio a `main`, ¿significa eso que han aprobado el commit MFC? ¿Es cierto si el código es idéntico o con sólo cambios triviales? Claramente no es cierto para trabajos más extensivos. Incluso para código idéntico ¿qué pasa si el commit no tiene conflicto pero introduce un cambio en el ABI? Un revisor podría haber dado el visto bueno para un commit en `main` debido al rompimiento del ABI pero podría
no aprobar el mergeado del mismo commit tal cual. Cada uno tiene que usar su mejor juicio hasta que acordemos unas directrices claras.
Para MFCs que están regulados por re@, se añaden nuevos campos de metadatos como la etiqueta Approved by para commits aprobados. Estos nuevos metadatos se tendrán que añadir con `git commit --amend` o similar después de que el commit original haya sido revisado y aprobado. También podríamos querer reservar algunos campos en los metadatos de los commtis MFC como las URLs de Phabricator para uso futuro por parte de re@.
-Preservar los metadatos existentes proporciona un flujo de trabajo sencillo. Los desarrolladores sólo tienen que usar `git cherry-pick-x` sin tener que editar el mensaje de log.
+Preservar los metadatos existentes proporciona un flujo de trabajo sencillo. Los desarrolladores usan `git cherry-pick-x` sin tener que editar el mensaje de log.
Si por el contrario escogemos ajustar los metadatos en los MFCs, los desarrolladores tendrán que editar los mensajes de log de forma explícita mediante el uso de `git cherry-pick --edit` o `git commit --amend`. Sin embargo, comparado con svn, al menos el mensaje de commit existente se puede precargar y los campos de metadatos se pueden añadir o eliminar sin tener que reescribir el mensaje de commit entero.
La conclusión es que los desarrolladores seguramente tengan que refinar los mensajes de commit para los MFCs que no sean triviales.
-==== Ejemplos
-
-===== Mergeando un Solo Commit de Subversion
-
-Aquí se explica el proceso de mergear un commit a stable/12 que fue añadido originalmente en head en Subversion. En este caso, el commit original es r368685.
-
-El primer paso es mapear el commit de Subversion a un hash de Git. Una vez que te has traído refs/notes/commits, puedes pasar el número de revisión a `git log --grep`:
-
-[source, shell]
-....
-% git log main --grep 368685
-commit ce8395ecfda2c8e332a2adf9a9432c2e7f35ea81
-Author: John Baldwin <jhb@FreeBSD.org>
-Date: Wed Dec 16 00:11:30 2020 +0000
-
- Use the 't' modifier to print a ptrdiff_t.
-
- Reviewed by: imp
- Obtained from: CheriBSD
- Sponsored by: DARPA
- Differential Revision: https://reviews.freebsd.org/D27576
-
-Notes:
- svn path=/head/; revision=368685
-....
-
-Luego, haz MFC del commit a `stable/12`:
-
-[source, shell]
-....
-git checkout stable/12
-git cherry-pick -x ce8395ecfda2c8e332a2adf9a9432c2e7f35ea81 --edit
-....
-
-Git invocará el editor. Úsalo para eliminar los metadatos que sólo aplicaban al commit original (URL de Phabricator y Reviewed by). Después de que el editor salve el mensaje de log actualizado, Git completa el commit:
-
-[source, shell]
-....
-[stable/12 3e3a548c4874] Use the 't' modifier to print a ptrdiff_t.
- Date: Wed Dec 16 00:11:30 2020 +0000
- 1 file changed, 1 insertion(+), 1 deletion(-)
-....
-
-El contenido del commit del que se ha hecho MFC se puede examinar vía `git show`:
-
-[source, shell]
-....
-% git show
-commit 3e3a548c487450825679e4bd63d8d1a67fd8bd2d (HEAD -> stable/12)
-Author: John Baldwin <jhb@FreeBSD.org>
-Date: Wed Dec 16 00:11:30 2020 +0000
-
- Use the 't' modifier to print a ptrdiff_t.
-
- Obtained from: CheriBSD
- Sponsored by: DARPA
-
- (cherry picked from commit ce8395ecfda2c8e332a2adf9a9432c2e7f35ea81)
-
-diff --git a/sys/compat/linuxkpi/common/include/linux/printk.h b/sys/compat/linuxkpi/common/include/linux/printk.h
-index 31802bdd2c99..e6510e9e9834 100644
---- a/sys/compat/linuxkpi/common/include/linux/printk.h
-+++ b/sys/compat/linuxkpi/common/include/linux/printk.h
-@@ -68,7 +68,7 @@ print_hex_dump(const char *level, const char *prefix_str,
- printf("[%p] ", buf);
- break;
- case DUMP_PREFIX_OFFSET:
-- printf("[%p] ", (const char *)((const char *)buf -
-+ printf("[%#tx] ", ((const char *)buf -
- (const char *)buf_old));
- break;
- default:
-....
-
-El commit MFC ya se puede publicar con `git push`
-
-[source, shell]
-....
-% git push freebsd
-Enumerating objects: 17, done.
-Counting objects: 100% (17/17), done.
-Delta compression using up to 4 threads
-Compressing objects: 100% (7/7), done.
-Writing objects: 100% (9/9), 817 bytes | 204.00 KiB/s, done.
-Total 9 (delta 5), reused 1 (delta 1), pack-reused 0
-To gitrepo-dev.FreeBSD.org:src.git
- 525bd9c9dda7..3e3a548c4874 stable/12 -> stable/12
-....
-
-===== Mergear un Único Commit de Subversion con Conflicto
-
-Este ejemplo es similar al anterior excepto por que el commit en cuestión produce un conflicto al mergear. En este caso, el commit original es r368314.
-
-Como arriba, el primer paso es mapear el commit de Subversion a un hash de Git:
-
-[source, shell]
-....
-% git log main --grep 368314
-commit 99963f5343a017e934e4d8ea2371a86789a46ff9
-Author: John Baldwin <jhb@FreeBSD.org>
-Date: Thu Dec 3 22:01:13 2020 +0000
-
- Don't transmit mbufs that aren't yet ready on TOE sockets.
-
- This includes mbufs waiting for data from sendfile() I/O requests, or
- mbufs awaiting encryption for KTLS.
-
- Reviewed by: np
- MFC after: 2 weeks
- Sponsored by: Chelsio Communications
- Differential Revision: https://reviews.freebsd.org/D27469
-
-Notes:
- svn path=/head/; revision=368314
-....
-
-Luego, haz MFC del commit a `stable/12`:
-
-[source, shell]
-....
-% git checkout stable/12
-% git cherry-pick -x 99963f5343a017e934e4d8ea2371a86789a46ff9 --edit
-Auto-merging sys/dev/cxgbe/tom/t4_cpl_io.c
-CONFLICT (content): Merge conflict in sys/dev/cxgbe/tom/t4_cpl_io.c
-warning: inexact rename detection was skipped due to too many files.
-warning: you may want to set your merge.renamelimit variable to at least 7123 and retry the command.
-error: could not apply 99963f5343a0... Don't transmit mbufs that aren't yet ready on TOE sockets.
-hint: after resolving the conflicts, mark the corrected paths
-hint: with 'git add <paths>' or 'git rm <paths>'
-hint: and commit the result with 'git commit'
-....
-
-En este caso, el commit se ha encontrado con un conflicto en sys/dev/cxge/tom/t4_cpl_io.c ya que el kernel TLS no está presente en stable/12. Fíjate en que Git no invoca el editor para ajustar el mensaje de commit debido al conflicto. `git status` confirma que el fichero tiene conflictos:
-
-[source, shell]
-....
-% git status
-On branch stable/12
-Your branch is up to date with 'upstream/stable/12'.
-
-You are currently cherry-picking commit 99963f5343a0.
- (fix conflicts and run "git cherry-pick --continue")
- (use "git cherry-pick --skip" to skip this patch)
- (use "git cherry-pick --abort" to cancel the cherry-pick operation)
-
-Unmerged paths:
- (use "git add <file>..." to mark resolution)
- both modified: sys/dev/cxgbe/tom/t4_cpl_io.c
-
-no changes added to commit (use "git add" and/or "git commit -a")
-....
-
-Después de editar el fichero para resolver el conflicto, `git status` muestra el conflicto como resuelto:
-
-[source, shell]
-....
-% git status
-On branch stable/12
-Your branch is up to date with 'upstream/stable/12'.
-
-You are currently cherry-picking commit 99963f5343a0.
- (all conflicts fixed: run "git cherry-pick --continue")
- (use "git cherry-pick --skip" to skip this patch)
- (use "git cherry-pick --abort" to cancel the cherry-pick operation)
-
-Changes to be committed:
- modified: sys/dev/cxgbe/tom/t4_cpl_io.c
-....
-
-Ahora se puede completar el cherry-pick:
-
-[source, shell]
-....
-% git cherry-pick --continue
-....
-
-Como hubo un conflicto, Git invoca el editor para ajustar el mensaje de commit. Elimina los campos de metadatos del commit original de head y guarda el mensaje de log actualizado.
-
-Ahora se puede examintar el contenido del commit MFC vía `git show`:
-
-[source, shell]
-....
-% git show
-commit 525bd9c9dda7e7c7efad2d4570c7fd8e1a8ffabc (HEAD -> stable/12)
-Author: John Baldwin <jhb@FreeBSD.org>
-Date: Thu Dec 3 22:01:13 2020 +0000
-
- Don't transmit mbufs that aren't yet ready on TOE sockets.
-
- This includes mbufs waiting for data from sendfile() I/O requests, or
- mbufs awaiting encryption for KTLS.
-
- Sponsored by: Chelsio Communications
-
- (cherry picked from commit 99963f5343a017e934e4d8ea2371a86789a46ff9)
-
-diff --git a/sys/dev/cxgbe/tom/t4_cpl_io.c b/sys/dev/cxgbe/tom/t4_cpl_io.c
-index 8e8c2b8639e6..43861f10b689 100644
---- a/sys/dev/cxgbe/tom/t4_cpl_io.c
-+++ b/sys/dev/cxgbe/tom/t4_cpl_io.c
-@@ -746,6 +746,8 @@ t4_push_frames(struct adapter *sc, struct toepcb *toep, int drop)
- for (m = sndptr; m != NULL; m = m->m_next) {
- int n;
-
-+ if ((m->m_flags & M_NOTAVAIL) != 0)
-+ break;
- if (IS_AIOTX_MBUF(m))
- n = sglist_count_vmpages(aiotx_mbuf_pages(m),
- aiotx_mbuf_pgoff(m), m->m_len);
-@@ -821,8 +823,9 @@ t4_push_frames(struct adapter *sc, struct toepcb *toep, int drop)
-
- /* nothing to send */
- if (plen == 0) {
-- KASSERT(m == NULL,
-- ("%s: nothing to send, but m != NULL", __func__));
-+ KASSERT(m == NULL || (m->m_flags & M_NOTAVAIL) != 0,
-+ ("%s: nothing to send, but m != NULL is ready",
-+ __func__));
- break;
- }
-
-@@ -910,7 +913,7 @@ t4_push_frames(struct adapter *sc, struct toepcb *toep, int drop)
- toep->txsd_avail--;
-
- t4_l2t_send(sc, wr, toep->l2te);
-- } while (m != NULL);
-+ } while (m != NULL && (m->m_flags & M_NOTAVAIL) == 0);
-
- /* Send a FIN if requested, but only if there's no more data to send */
- if (m == NULL && toep->flags & TPF_SEND_FIN)
-....
-
-El commit MFC ya se puede publicar con `git push`
-
-[source, shell]
-....
-git push freebsd
-Enumerating objects: 13, done.
-Counting objects: 100% (13/13), done.
-Delta compression using up to 4 threads
-Compressing objects: 100% (7/7), done.
-Writing objects: 100% (7/7), 819 bytes | 117.00 KiB/s, done.
-Total 7 (delta 6), reused 0 (delta 0), pack-reused 0
-To gitrepo.FreeBSD.org:src.git
- f4d0bc6aa6b9..525bd9c9dda7 stable/12 -> stable/12
-....
-
[[vendor-import-git]]
=== Importaciones Externas con Git
@@ -1172,10 +894,7 @@ Esta sección describe en detalle el procedimiento para hacer importaciones de t
Todas las ramas de terceros y etiquetas comienzan con `vendor/`. Estas ramas y etiquetas son visibles por defecto.
-[NOTE]
-====
-Este capítulo sigue la convención de que el origen `freebsd` es el nombre del origen del repositorio Git oficial de FreeBSD. Si usas otra convención, en los ejemplos de abajo reemplaza `freebsd` con el nombre que uses en su lugar.
-====
+[NOTE] ==== Este capítulo sigue la convención de que el origen `freebsd` es el nombre del origen del repositorio Git oficial de FreeBSD. Si usas otra convención, en los ejemplos de abajo reemplaza `freebsd` con el nombre que uses en su lugar. ====
Exploraremos un ejemplo para actualizar el mtree de NetBSD que está en nuestro árbol. La rama externa para esto es `vendor/NetBSD/mtree`.
@@ -1183,7 +902,7 @@ Exploraremos un ejemplo para actualizar el mtree de NetBSD que está en nuestro
Los árboles externos normalmente tienen sólo un subconjunto del software de terceros que es apropiado para FreeBSD. Estos árboles son muy pequeños en comparación con el árbol de FreeBSD. Los worktrees de Git son por lo tanto bastante pequeños y rápidos y el método preferido a usar. Asegúrate de que el directorio que escojas debajo (el `../mtree`) no existe.
-[source, shell]
+[source,shell]
....
% git worktree add ../mtree vendor/NetBSD/mtree
....
@@ -1194,7 +913,7 @@ Prepara un árbol limpio, completo con las fuentes externas. Importa todo pero m
Este ejemplo asume que las fuentes de NetBSD se han traído de su mirror de GitHub en `~/git/NetBSD`. Date cuenta de que "upstream" podría haber añadido o eliminado ficheros, por lo que queremos asegurarnos de que los borrados también se propagan. Normalmente package:net/rsync[] está instalado así que lo usaremos.
-[source, shell]
+[source,shell]
....
% cd ../mtree
% rsync -va --del --exclude=".git" ~/git/NetBSD/usr.sbin/mtree/ .
@@ -1209,15 +928,19 @@ Este ejemplo asume que las fuentes de NetBSD se han traído de su mirror de GitH
% git tag -a vendor/NetBSD/mtree/20201211
....
-Nota: Ejecuto los comandos `git diff` y `git status` para asegurarme de que no hay nada raro. También usé `-m` de forma ilustrativa, pero tú deberías componer un mensaje apropiado en un editor (usando una plantilla para el mensaje de commit).
+Nota: Ejecuto los comandos `git diff` y `git status` para asegurarme de que no hay nada raro.
+También usé `-m` de forma ilustrativa, pero tú deberías componer un mensaje apropiado en un editor (usando una plantilla para el mensaje de commit).
-También es importante crear una etiqueta anotada utilizando `git tag -a`, de lo contrario el push será rechazado. Sólo se permite hacer push de etiquetas anotadas. Las etiquetas anotadas te dan una oportunidad de introducir un mensaje de commit. Introduce la versión que estás importando así como cualquier característica que resalte o arreglos que lleve la versión.
+También es importante crear una etiqueta anotada utilizando `git tag -a`, de lo contrario el push será rechazado.
+Sólo se permite hacer push de etiquetas anotadas.
+Las etiquetas anotadas te dan una oportunidad de introducir un mensaje de commit.
+Introduce la versión que estás importando así como cualquier característica que resalte o arreglos que lleve la versión.
==== Actualizando la Copia de FreeBSD
En este momento puedes empujar la importación a `vendor` en nuestro propio repo.
-[source, shell]
+[source,shell]
....
% git push --follow-tags freebsd vendor/NetBSD/mtree
....
@@ -1228,13 +951,14 @@ En este momento puedes empujar la importación a `vendor` en nuestro propio repo
Ahora necesitas actualizar el mtree en FreeBSD. Las fuentes están en `contrib/mtree` ya que es software de terceros.
-[source, shell]
+[source,shell]
....
-% cd ../src
-% git subtree merge -P contrib/mtree vendor/NetBSD/mtree
+% cd ../src % git subtree merge -P contrib/mtree vendor/NetBSD/mtree
....
-Esto generaría un commit merge para el subárbol `contrib/mtree` contra la rama local `vendor/NetBSD/mtree`. Si hubiera conflictos, necesitarías arreglarlos antes de hacer el commit. Incluye detalles en el mensaje de commit acerca de los cambios que se están mergeando.
+Esto generaría un commit merge para el subárbol `contrib/mtree` contra la rama local `vendor/NetBSD/mtree`.
+Si hubiera conflictos, necesitarías arreglarlos antes de hacer el commit.
+Incluye detalles en el mensaje de commit acerca de los cambios que se están mergeando.
==== Rebasando to cambio contra lo último del árbol de fuentes de FreeBSD
@@ -1242,66 +966,84 @@ Puesto que la política actual no recomienda utilizar meges, si el `main` de Fre
Los `git rebase` o `git pull --rebase` habituales no saben cómo rebasar un commit tipo merge **como un commit merge**, así que tendrías que recrear el commit.
-La forma más fácil de hacer esto sería crear una rama paralela con los **contenidos** del árbol mergeado:
+Se deberían seguir los siguientes pasos para facilitar recrear el commit tipo merge como si `git rebase --merge-commits` hubiese funcionado adecuadamente:
+
+* Muévete al directorio raíz del repositorio
+* Crea una rama `XXX` con el **contenido** del árbol mergeado.
+* Actualiza este lado de la rama `XXX` para mergearla y tenerla actualizada respecto a la rama `main` de FreeBSD.
+** En el peor caso, tendrías que resolver conflictos, si hubiera alguno, pero esto debería ser raro.
+** Resuelve los conflictos, y compacta varios commits en uno si es necesario (si no hay conflictos, no hay necesidad de compactar)
+* Haz checkout de `main`
+* crea una rama `YYY` (permite deshacer los cambios si algo va mal)
+* Rehaz el merge del subárbol
+* En lugar de resolver conflictos en el subárbol mergeado, haz un checkout del contenido de XXX encima de él.
+** El último `.` es importante, igual que lo es estar en el directorio raíz del repositorio.
+** En lugar de cambiar a la rama XXX, pone el contenido de XXX sobre el repositorio.
+* Haz commit del repositorio con el mensaje de commit anterior (el ejemplo asume que sólo hay un merge en la rama XXX).
+* Asegúrate de que las ramas son iguales.
+* Haz las revisiones que necesites, incluyendo involucrar a otros si crees que es necesario.
+* Empuja el commit, si has 'perdido la carrera' otra vez, simplemente haz otra vez estos pasos (lee más abajo para una receta)
+* Borra las ramas una vez que el commit está en el repositorio. Son desechables.
+
+Los comandos que uno usaría, siguiendo el ejemplo de mtree, sería como esto (el símbolo `#` marca un comentario para ayudar y enlazar los comandos con las descripciones de arriba):
-[source, shell]
+[source,shell]
....
-% cd ../src
-% git fetch freebsd
-% git checkout -b merge_result
-% git merge freebsd/main
+% cd ../src # cambiar a la raíz del árbol
+% git checkout -b XXX # crea la rama XXX de usar y tirar para hacer el merge
+% git fetch freebsd # Obtiene los datos de upstream
+% git merge freebsd/main # Mergea los cambios y resuelve conflictos
+% git checkout -b YYY freebsd/main # Crea una nueva rama de usar y tirar YYY para rehacer
+% git subtree merge -P contrib/mtree vendor/NetBSD/mtree # Redo subtree merge
+% git checkout XXX . # La rama XXX tiene la resolución del conflicto
+% git commit -c XXX~1 # -c reutiliza el mensaje de commit del commit anterior al rebase
+% git diff XXX YYY # Debería estar vacío
+% git show YYY # Sólo debería tener los cambios que quieres, y ser un commit merge desde la rama del vendor
....
-Típicamente, no habría aquí más conflictos de merge (porque los desarrolladores tienden a trabajar en diferentes componentes). En el peor caso, tendrías que resolver los conflictos de merge, si hay alguno, pero esto debería ser muy raro.
-
-Ahora, tráete `freebsd/main` de nuevo como `new_merge`, y rehaz el merge:
-
-[source, shell]
+Nota: si algo va mal con el commit, puedes resetear la rama `YYY` para comenzar de nuev volviendo a ejecutar el comando checkout que la creó con -B :
+[source,shell]
....
-% git checkout -b new_merge freebsd/main
-% git subtree merge -P contrib/mtree vendor/NetBSD/mtree
+% git checkout -B YYY freebsd/main # Crea una nueva rama YYY de usar y tirar si empezar desde cero es más sencillo
....
-En lugar de resolver los conflictos, haz esto:
-
-[source, shell]
-....
-% git checkout merge_result .
-....
+==== Empujando los cambios
-Que sobrescribirá los ficheros en conflicto con la versión que se encuentra en `merge_result`.
+Una vez que crees que tienes un conjunto de diferencias que es bueno, puedes empujarlo a un fork de GitHub o Gitlab para que otros lo revisen. Una cosa buena de Git es que te permite publicar borradores de tu trabajo para que otros lo revisen. Mientras que Phabricator es bueno para revisión de contenido, publicar una rama externa actualizada y los commits tipo merge permite a otros comprobar los detalles tal y como aparecerán eventualmente en el repositorio.
-Examina el árbol contra `merge_result` para asegurarte de que no se te ha pasado ningún fichero borrado:
+Después de la revisión, cuando estás seguro de que es un buen cambio, puedes empujarlo al repo de FreeBSD:
-[source, shell]
+[source,shell]
*** 21050 LINES SKIPPED ***