Mercurial > hgbook
view es/undo.tex @ 574:22184eb4c965
finished the translation of the section "information for writers of hooks"
updated project status
author | Javier Rojas <jerojasro@devnull.li> |
---|---|
date | Wed, 31 Dec 2008 11:31:04 -0500 |
parents | 626c16b87174 |
children | 9da096de3c52 |
line wrap: on
line source
\chapter{Encontrar y arreglar sus equivocaciones} \label{chap:undo} Errar es humano, pero tratar adecuadamente las consecuencias requiere un sistema de control de revisiones de primera categoría. En este capítulo, discutiremos algunas técnicas que puede usar cuando encuentra que hay un problema enraizado en su proyecto. Mercurial tiene unas características poderosas que le ayudarán a isolar las fuentes de los problemas, y a dar cuenta de ellas apropiadamente. \section{Borrar la historia local} \subsection{La consignación accidental} Tengo el problema ocasional, pero persistente de teclear más rápido de lo que pienso, que aveces resulta en consignar un conjunto de cambios incompleto o simplemente malo. En mi caso, el conjunto de cambios incompleto consiste en que creé un nuevo fichero fuente, pero olvidé hacerle \hgcmd{add}. Un conjunto de cambios``simplemente malo'' no es tan común, pero sí resulta muy molesto. \subsection{Hacer rollback una transacción} \label{sec:undo:rollback} En la sección~\ref{sec:concepts:txn}, mencioné que Mercurial trata modificación a un repositorio como una \emph{transacción}. Cada vez que consigna un conjunto de cambios o lo jala de otro repositorio, Mercurial recuerda lo que hizo. Puede deshacer, o hacer \emph{roll back}\ndt{El significado igual que en los ambientes de sistemas manejadores de bases de datos se refiere a la atomicidad e integridad al devolver un conjunto de acciones que permitan dejar el repositorio en un estado consistente previo}, exactamente una de tales acciones usando la orden \hgcmd{rollback}. (Ver en la sección~\ref{sec:undo:rollback-after-push} una anotación importante acerca del uso de esta orden.) A continuación una equivocación que me sucede frecuentemente: consignar un cambio en el cual he creado un nuevo fichero, pero he olvidado hacerle \hgcmd{add}. \interaction{rollback.commit} La salida de \hgcmd{status} después de la consignación confirma inmediatamente este error. \interaction{rollback.status} La consignación capturó los cambios en el fichero \filename{a}, pero no el nuevo fichero \filename{b}. Si yo publicara este conjunto de cambios a un repositorio compartido con un colega, es bastante probable que algo en \filename{a} se refiriera a \filename{b}, el cual podría no estar presente cuando jalen mis cambios del repositorio. Me convertiría el sujeto de cierta indignación. Como sea, la suerte me acompaña---Encontré mi error antes de publicar el conjunto de cambios. Uso la orden \hgcmd{rollback}, y Mercurial hace desaparecer el último conjunto de cambios. \interaction{rollback.rollback} El conjunto de cambios ya no está en la historia del repositorio, y el directorio de trabajo cree que el fichero \filename{a} ha sido modificado. La consignación y el roll back dejaron el directorio de trabajo exactamente como estaba antes de la consignación; el conjunto de cambios ha sido eliminado totlamente. Ahora puedo hacer \hgcmd{add} al fichero \filename{b}, y hacer de nuevo la consignación. \interaction{rollback.add} \subsection{Erroneamente jalado} Mantener ramas de desarrollo separadas de un proyecto en distintos repositorios es una práctica común con Mercurial. Su equipo de desarrollo puede tener un repositorio compartido para la versión ``0.9'' y otra con cambios distintos para la versión ``1.0''. Con este escenario, puede imaginar las consecuencias si tuviera un repositorio local ``0.9'', y jalara accidentalmente los cambios del repositorio compartido de la versión ``1.0'' en este. En el peor de los casos, por falta de atención, es posible que publique tales cambios en el árbol compartido ``0.9'', confundiendo a todo su equipo de trabajo(pero no se preocupe, volveremos a este terrorífico escenario posteriormente). En todo caso, es muy probable que usted se de cuenta inmediatamente, dado que Mercurial mostrará el URL de donde está jalando, o que vea jalando una sospechosa gran cantidad de cambios en el repositorio. La orden \hgcmd{rollback} excluirá eficientemente los conjuntos de cambios que haya acabado de jalar. Mercurial agrupa todos los cambios de un \hgcmd{pull} a una única transacción y bastará con un \hgcmd{rollback} para deshacer esta equivocación. \subsection{Después de publicar, un roll back es futil} \label{sec:undo:rollback-after-push} El valor de \hgcmd{rollback} se anula cuando ha publicado sus cambios a otro repositorio. Un cambio desaparece totalmente al hacer roll back, pero \emph{solamente} en el repositorio en el cual aplica \hgcmd{rollback}. Debido a que un roll back elimina la historia, no hay forma de que la desaparición de un cambio se propague entre repositorios. Si ha publicado un cambio en otro repositorio---particularmente si es un repositorio público---esencialmente está ``en terreno agreste,'' y tendrá que reparar la equivocación de un modo distinto. Lo que pasará si publica un conjunto de cambios en algún sitio, hacer rollback y después volver a jalar del repositorio del cual había publicado, es que el conjunto de cambios reaparecerá en su repositorio. (Si está absolutamente segruro de que el conjunto de cambios al que desea hacer rollback es el cambio más reciente del repositorio en el cual publicó, \emph{y} sabe que nadie más pudo haber jalado de tal repositorio, puede hacer rollback del conjunto de cambios allí, pero es mejor no confiar en una solución de este estilo. Si lo hace, tarde o temprano un conjunto de cambios logrará colarse en un repositorio que usted no controle directamente(o del cual se ha olvidado), y volverá a hostigarle.) \subsection{Solamente hay un roll back} Mercurial almacena exactamente una transacción en su bitácora de transacciones; tal transacción es la más reciente de las que haya ocurrido en el repositorio. Esto significa que solamente puede hacer roll back a una transacción. Si espera poder hacer roll back a una transacción después al antecesor, observará que no es el comportamiento que obtendrá. \interaction{rollback.twice} Una vez que haya aplicado un rollback en una transacción a un repositorio, no podrá volver a hacer rollback hasta que haga una consignación o haya jalado. \section{Revertir un cambio equivocado} Si modifica un fichero y se da cuenta que no quería realmente cambiar tal fichero, y todavía no ha consignado los cambios, la orden necesaria es \hgcmd{revert}. Observa el conjunto de cambios padre del directorio y restaura los contenidos del fichero al estado de tal conjunto de cambios. (Es una forma larga de decirlo, usualmente deshace sus modificaciones.) Ilustremos como actúa la orden \hgcmd{revert} con un ejemplo pequeño. Comenzaremos modificando un fichero al cual Mercurial ya está siguiendo. \interaction{daily.revert.modify} Si no queremos ese cambio, podemos aplicar \hgcmd{revert} al fichero. \interaction{daily.revert.unmodify} La orden \hgcmd{revert} nos brinda un grado adicional de seguridad guardando nuestro fichero modificado con la extensión \filename{.orig}. \interaction{daily.revert.status} Este es un resumen de casos en los cuales la orden \hgcmd{revert} es de utilidad. Describiremos cada uno de ellos con más detalle en la sección siguiente. \begin{itemize} \item Si usted modifica un fichero, lo restaurará a su estado sin modificación previo. \item Si usted hace \hgcmd{add} a un fichero, revertirá el estado de ``adicionado'' del fichero, pero no lo tocará \item Si borra un fichero sin decirle a Mercurial, restaurará el fichero con sus contenidos sin modificación. \item Si usa la orden \hgcmd{remove} para eliminar un fichero, deshará el estado ``removido'' del fichero, y lo restaurará con sus contenidos sin modificación. \end{itemize} \subsection{Errores al administrar ficheros} \label{sec:undo:mgmt} La orden \hgcmd{revert} es útil para más que ficheros modificados. Le permite reversar los resultados de todas las órdenes de administración de ficheros que provee Mercurial---\hgcmd{add}, \hgcmd{remove}, y las demás. Si usted hace \hgcmd{add} a un fichero, y no deseaba que Mercurial le diera seguimiento, use \hgcmd{revert} para deshacer la adición. No se preocupe; Mercurial no modificará de forma alguna el fichero. Solamente lo ``desmarcará''. \interaction{daily.revert.add} De forma similar, Si le solicita a Mercurial hacer \hgcmd{remove} a un fichero, puede usar \hgcmd{revert} para restarurarlo a los contenidos que tenía la revisión padre del directorio de trabajo. \interaction{daily.revert.remove} Funciona de la misma manera para un fichero que usted haya eliminado manualmente, sin decirle a Mercurial (recuerde que en la terminología de Mercurial esta clase de fichero se llama ``faltante''). \interaction{daily.revert.missing} Si usted revierte un \hgcmd{copy}, el fichero a donde se copió permanece en su directorio de trabajo, pero sin seguimiento. Dado que una copia no afecta el fichero fuente de copiado de ninguna maner, Mercurial no hace nada con este. \interaction{daily.revert.copy} \subsubsection{Un caso ligeramente especial:revertir un renombramiento} Si hace \hgcmd{rename} a un fichero, hay un detalle que debe tener en cuenta. Cuando aplica \hgcmd{revert} a un cambio de nombre, no es suficiente proveer el nombre del fichero destino, como puede verlo en el siguiente ejemplo. \interaction{daily.revert.rename} Como puede ver en la salida de \hgcmd{status}, el fichero con el nuevo nombre no se identifica más como agregado, pero el fichero con el nombre-\emph{inicial} se elimna! Esto es contra-intuitivo (por lo menos para mí), pero por lo menos es fácil arreglarlo. \interaction{daily.revert.rename-orig} Por lo tanto, recuerde, para revertir un \hgcmd{rename}, debe proveer \emph{ambos} nombres, la fuente y el destino. % TODO: the output doesn't look like it will be removed! (A propósito, si elimina un fichero, y modifica el fichero con el nuevo nombre, al revertir ambos componentes del renombramiento, cuando Mercurial restaure el fichero que fue eliminado como parte del renombramiento, no será modificado. Si necesita que las modificaciones en el fichero destino del renombramiento se muestren, no olvide copiarlas encima.) Estos aspectos engorrosos al revertir un renombramiento se constituyen discutiblemente en un fallo de Mercurial. \section{Tratar cambios consignados} Considere un caso en el que ha consignado el cambio $a$, y otro cambio $b$ sobre este; se ha dado cuenta que el cambio $a$ era incorrecto. Mercurial le permite ``retroceder'' un conjunto de cambios completo automáticamente, y construir bloques que le permitan revertir parte de un conjunto de cambios a mano. Antes de leer esta sección, hay algo para tener en cuenta: la orden \hgcmd{backout} deshace cambios \emph{adicionando} a la historia, sin modificar o borrar. Es la herramienta correcta si está arreglando fallos, pero no si está tratando de deshacer algún cambio que tiene consecuencias catastróficas. Para tratar con esos, vea la sección~\ref{sec:undo:aaaiiieee}. \subsection{Retroceder un conjunto de cambios} La orden \hgcmd{backout} le permite ``deshacer'' los efectos de todo un conjunto de cambios de forma automatizada. Dado que la historia de Mercurial es inmutable, esta orden \emph{no} se deshace del conjunto de cambios que usted desea deshacer. En cambio, crea un nuevo conjunto de cambios que \emph{reversa} el conjunto de cambios que usted indique. La operación de la orden \hgcmd{backout} es un poco intrincada, y lo ilustraremos con algunos ejemplos. Primero crearemos un repositorio con algunos cambios sencillos. \interaction{backout.init} La orden \hgcmd{backout} toma un ID de conjunto de cambios como su argumento; el conjunto de cambios a retroceder. Normalmente \hgcmd{backout} le ofrecerá un editor de texto para escribir el mensaje de la consignación, para dejar un registro de por qué está retrocediendo. En este ejemplo, colocamos un mensaje en la consignación usando la opción \hgopt{backout}{-m} . \subsection{Retroceder el conjunto de cambios punta} Comenzamos retrocediendo el último conjunto de cambios que consignamos. \interaction{backout.simple} Puede ver que la segunda línea de \filename{myfile} ya no está presente. La salida de \hgcmd{log} nos da una idea de lo que la orden \hgcmd{backout} ha hecho. \interaction{backout.simple.log} Vea que el nuevo conjunto de cambios que \hgcmd{backout} ha creado es un hijo del conjunto de cambios que retrocedimos. Es más sencillo de ver en la figura~\ref{fig:undo:backout}, que presenta una vista gráfica de la historia de cambios. Como puede ver, la historia es bonita y lineal. \begin{figure}[htb] \centering \grafix{undo-simple} \caption{Retroceso de un cambio con la orden \hgcmd{backout}} \label{fig:undo:backout} \end{figure} \subsection{Retroceso de un cambio que no es la punta} Si desea retrocede un cambio distinto al último que ha consignado, use la opción \hgopt{backout}{--merge} a la orden \hgcmd{backout}. \interaction{backout.non-tip.clone} Que resulta en un retroceso de un conjunto de cambios ``en un sólo tiro'', una operación que resulta normalmente rápida y sencilla. \interaction{backout.non-tip.backout} Si ve los contenidos del fichero \filename{myfile} después de finalizar el retroceso, verá que el primer y el tercer cambio están presentes, pero no el segundo. \interaction{backout.non-tip.cat} Como lo muestra la historia gráfica en la figura~\ref{fig:undo:backout-non-tip}, Mercurial realmente consigna \emph{dos} cambios en estas situaciones (los nodos encerrados en una caja son aquellos que Mercurial consigna automaticamente). Antes de que Mercurial comience el proceso de retroceso, primero recuerda cuál es el padre del directorio de trabajo. Posteriormente hace un retroceso al conjunto de cambios objetivo y lo consigna como un conjunto de cambios. Finalmente, fusiona con el padre anterior del directorio de trabajo, y consigna el resultado de la fusión. % TODO: to me it looks like mercurial doesn't commit the second merge automatically! \begin{figure}[htb] \centering \grafix{undo-non-tip} \caption{Retroceso automatizado de un cambio a algo que no es la punta con la orden \hgcmd{backout}} \label{fig:undo:backout-non-tip} \end{figure} El resultado es que usted termina ``donde estaba'', solamente con un poco de historia adicional que deshace el efecto de un conjunto de cambios que usted quería evitar. \subsubsection{Use siempre la opción \hgopt{backout}{--merge}} De hecho, dado que la opción \hgopt{backout}{--merge} siempre hara lo ``correcto'' esté o no retrocediendo el conjunto de cambios punta (p.e.~no tratará de fusionar si está retrocediendo la punta, dado que no es necesario), usted debería usar \emph{siempre} esta opción cuando ejecuta la orden \hgcmd{backout}. \subsection{Más control sobre el proceso de retroceso} A pesar de que recomiendo usar siempre la opción \hgopt{backout}{--merge} cuando está retrocediendo un cambio, la orden \hgcmd{backout} le permite decidir cómo mezclar un retroceso de un conjunto de cambios. Es muy extraño que usted necestite tomar control del proceso de retroceso de forma manual, pero puede ser útil entender lo que la orden \hgcmd{backout} está haciendo automáticamente para usted. Para ilustrarlo, clonemos nuestro primer repositorio, pero omitamos el retroceso que contiene. \interaction{backout.manual.clone} Como en el ejemplo anterior, consignaremos un tercer cambio, después haremos retroceso de su padre, y veremos qué pasa. \interaction{backout.manual.backout} Nuestro nuevo conjunto de cambios es de nuevo un descendiente del conjunto de cambio que retrocedimos; es por lo tanto una nueva cabeza, \emph{no} un descendiente del conjunto de cambios que era la punta. La orden \hgcmd{backout} fue muy explícita diciéndolo. \interaction{backout.manual.log} De nuevo, es más sencillo lo que pasó viendo una gráfica de la historia de revisiones, en la figura~\ref{fig:undo:backout-manual}. Esto nos aclara que cuando usamos \hgcmd{backout} para retroceder un cambio a algo que no sea la punta, Mercurial añade una nueva cabeza al repositorio (el cambio que consignó está encerrado en una caja). \begin{figure}[htb] \centering \grafix{undo-manual} \caption{Retroceso usando la orden \hgcmd{backout}} \label{fig:undo:backout-manual} \end{figure} Después de que la orden \hgcmd{backout} ha terminado, deja un nuevo conjunto de cambios de ``retroceso'' como el padre del directorio de trabajo. \interaction{backout.manual.parents} Ahora tenemos dos conjuntos de cambios aislados. \interaction{backout.manual.heads} Reflexionemos acerca de lo que esperamos ver como contenidos de \filename{myfile}. El primer cambio debería estar presente, porque nunca le hicimos retroceso. El segundo cambio debió desaparecer, puesto que es el que retrocedimos. Dado que la gráfica de la historia muestra que el tercer camlio es una cabeza separada, \emph{no} esperamos ver el tercer cambio presente en \filename{myfile}. \interaction{backout.manual.cat} Para que el tercer cambio esté en el fichero, hacemos una fusión usual de las dos cabezas. \interaction{backout.manual.merge} Después de eso, la historia gráfica de nuestro repositorio luce como la figura~\ref{fig:undo:backout-manual-merge}. \begin{figure}[htb] \centering \grafix{undo-manual-merge} \caption{Fusión manual de un retroceso} \label{fig:undo:backout-manual-merge} \end{figure} \subsection{Por qué \hgcmd{backout} hace lo que hace} Esta es una descripción corta de cómo trabaja la orden \hgcmd{backout}. \begin{enumerate} \item Se asegura de que el directorio de trabajo es ``limpio'', esto es, que la salida de \hgcmd{status} debería ser vacía. \item Recuerda el padre actual del directorio de trabajo. A este conjunto de cambio lo llamaremos \texttt{orig} \item Hace el equivalente de un \hgcmd{update} para sincronizar el directorio de trabajo con el conjunto de cambios que usted quiere retroceder. Lo llamaremos \texttt{backout} \item Encuentra el padre del conjunto de cambios. Lo llamaremos \texttt{parent}. \item Para cada fichero del conjunto de cambios que el \texttt{retroceso} afecte, hará el equivalente a \hgcmdargs{revert}{-r parent} sobre ese fichero, para restaurarlo a los contenidos que tenía antes de que el conjunto de cambios fuera consignado. \item Se consigna el resultado como un nuevo conjunto de cambios y tiene a \texttt{backout} como su padre. \item Si especifica \hgopt{backout}{--merge} en la línea de comandos, se fusiona con \texttt{orig}, y se consigna el resultado de la fusión. \end{enumerate} Una vía alternativa de implementar la orden \hgcmd{backout} sería usar \hgcmd{export} sobre el conjunto de cambios a retroceder como un diff y después usar laa opción \cmdopt{patch}{--reverse} de la orden \command{patch} para reversar el efecto del cambio sin molestar el directorio de trabajo. Suena mucho más simple, pero no funcionaría bien ni de cerca. La razón por la cual \hgcmd{backout} hace una actualización, una consignación, una fusión y otra consignación es para dar a la maquinaria de fusión la mayor oportunidad de hacer un buen trabajo cuando se trata con todos los cambios \emph{entre} el cambio que está retrocediendo y la punta actual. Si está retrocediendo un conjunto de cambios que está a unas ~100 atrás en su historia del proyecto, las posibilidades de que una orden \command{patch} sea capaz de ser aplicada a un diff reverso, claramente no son altas, porque los cambios que intervienen podrían ``no coincidir con el contexto'' que \command{patch} usa para determinar si puede aplicar un parche (si esto suena como cháchara, vea una discusión de la orden \command{patch} en \ref{sec:mq:patch}). Adicionalmente, la maquinaria de fusión de Mercurial manejará ficheros y directorios renombrados, cambios de permisos, y modificaciones a ficheros binarios, nada de lo cual la orden \command{patch} puede manejar. \section{Cambios que nunca debieron ocurrir} \label{sec:undo:aaaiiieee} En la mayoría de los casos, la orden \hgcmd{backout} es exactamente lo que necesita para deshacer los efectos de un cambio. Deja un registro permanente y exacto de lo que usted hizo, cuando se consignó el conjunto de cambios original y cuando se hizo la limpieza. En ocasiones particulares, puede haber consignado un cambio que no debería estar de ninguna forma en el repositorio. Por ejemplo, sería muy inusual, y considerado como una equivocación, consignar los ficheros objeto junto con el código fuente. los ficheros objeto no tienen valor intrínseco y son \emph{grandes}, por lo tanto aumentan el tamaño del repositorio y la cantidad de tiempo que se emplea al clonar o jalar cambios. Antes de discutir las opciones que tiene si consignó cambio del tipo ``bolsa de papel deschable'' (el tipo que es tan malo que le gustaría colocarse una bolsa de papel desechable en su cabeza), permítame discutir primero unas aproximaciones que probablemente no funcionen. Dado que Mercurial trata de forma acumulativa la historia---cada cambio se coloca encima de todos los cambios que leo preceden---usualmente usted no puede hacer que unos cambios desastros desaparezcan. La única excepción es cuando usted ha acabado de consignar un cambio y este no ha sido publicado o jalado en otro repositorio. Ahí es cuando puede usar la orden \hgcmd{rollback} con seguridad, Como detallé en la sección~\ref{sec:undo:rollback}. Después de que usted haya publicado un cambio en otro repositorio, usted \emph{podría} usar la orden \hgcmd{rollback} para hacer que en su copia local desaparezca el cambio, pero no tendrá las consecuencias que desea. El cambio estará presente en un repositorio remoto, y reaparecerá en su repositorio local la próxima vez que jale Si una situación como esta se presenta, y usted sabe en qué repositorios su mal cambio se ha propagado, puede \emph{intentar} deshacerse del conjunto de cambios de \emph{todos} los repositorios en los que se pueda encontrar. Esta por supuesto, no es una solución satisfactoria: si usted deja de hacerlo en un solo repositorio, mientras esté eliminándolo, el cambio todavía estará ``allí afuera'', y podría propagarse más tarde. Si ha consignado uno o más cambios \emph{después} del cambio que desea desaparecer, sus opciones son aún más reducidas. Mercurial no provee una forma de ``cabar un hueco'' en la historia, dejando los conjuntos de cambios intactos. %Dejamos de traducir lo que viene a continuación, porque será %modificado por upstream... XXX This needs filling out. The \texttt{hg-replay} script in the \texttt{examples} directory works, but doesn't handle merge changesets. Kind of an important omission. \subsection{Cómo protegerse de cambios que han ``escapado''} Si ha consignado cambios a su repositorio local y estos han sido publicados o jalados en cualquier otro sitio, no es necesariamente un desastre. Puede protegerse de antemano de ciertas clases de conjuntos de cambios malos. Esto es particularmente sencillo si su equipo de trabajo jala cambios de un repositorio central. Al configurar algunos ganchos en el repositorio central para validar conjuntos de cambios(ver capítulo~\ref{chap:hook}), puede prevenir la publicación automáticamente de cierta clase de cambios malos. Con tal configuración, cierta clase de conjuntos de cambios malos tenderán naturalmente a``morir'' debido a que no pueden propagarse al repositorio central. Esto sucederá sin necesidad de intervención explícita. Por ejemplo, un gancho de cambios de entrada que verifique que un conjunto de cambios compila, puede prevenir que la gente ``rompa la compilación'' inadvertidamente. \section{Al encuentro de la fuente de un fallo} \label{sec:undo:bisect} Aunque es muy bueno poder retroceder el conjunto de cambios que originó un fallo, se requiere que usted sepa cual conjunto de cambios retroceder. Mercurial brinda una orden invaluable, llamada \hgcmd{bisect}, que ayuda a automatizar este proceso y a alcanzarlo muy eficientemente. La idea tras la orden \hgcmd{bisect} es que el conjunto de cambios que ha introducido un cambio de comportamiento pueda identificarse con una prueba binaria sencilla. No tiene que saber qué pieza de código introdujo el cambio, pero si requiere que sepa cómo probar la existencia de un fallo. La orden \hgcmd{bisect} usa su prueba para dirigir su búsqueda del conjunto de cambios que introdujo el código causante del fallo. A continuación un conjunto de escenarios que puede ayudarle a entender cómo puede aplicar esta orden. \begin{itemize} \item La versión más reciente de su programa tiene un fallo que usted recuerda no estaba hace unas semanas, pero no sabe cuándo fue introducido. En este caso, su prueba binaria busca la presencia de tal fallo. \item Usted arregló un fallo en un apurto, y es hora de dar por cerrado el caso en la base de datos de fallos de su equipo de trabajo. La base de datos de fallos requiere el ID del conjunto de cambios que permita dar por cerrado el caso, pero usted no recuerda qué conjunto de cambios arregló tal fallo. De nuevo la prueba binaria revisa la presencia del fallo. \item Su programa funciona correctamente, pero core ~15\% más lento que la última vez que lo midió. Usted desea saber qué conjunto de cambios introdujo esta disminución de desempeño. En este caso su prueba binaria mide el desempeño de su programa, para ver dónde es ``rápido'' y dónde es ``lento''. \item Los tamaños de los componentes del proyecto que usted lleva se expandieron recientemente, y sospecha que algo cambio en la forma en que se construye su proyecto. \end{itemize} Para estos ejemplos debería ser claro que la orden \hgcmd{bisect} es útil no solamente para encontrar la fuente de los fallos. Puede usarla para encontrar cualquier ``propiedad emergente'' de un repositorio(Cualquier cosa que usted no pueda encontrar con una búsqueda de texto sencilla sobre los ficheros en el árbol) para la cual pueda escribir una prueba binaria. A continuación introduciremos algo terminología, para aclarar qué partes del proceso de búsqueda son su responsabilidad y cuáles de Mercurial. Una \emph{prueba} es algo que \emph{usted} ejecuta cuando \hgcmd{bisect} elige un conjunto de cambios. Un \emph{sondeo} es lo que \hgcmd{bisect} ejecuta para decidir si una revisión es buena. Finalmente, usaremos la palabra ``biseccionar', en frases como ``buscar con la orden \hgcmd{bisect}''. Una forma sencilla de automatizar el proceso de búsqueda sería probar cada conjunto de cambios. Lo cual escala muy poco. Si le tomó diez minutos hacer pruebas sobre un conjunto de cambios y tiene 10.000 conjuntos de cambios en su repositorio, esta aproximación exhaustiva tomaría en promedio~35 \emph{días} para encontrar el conjunto de cambios que introdujo el fallo. Incluso si supiera que el fallo se introdujo en un de los últimos 500 conjuntos de cambios y limitara la búsqueda a ellos, estaría tomabdi más de 40 horas para encontrar al conjunto de cambios culpable. La orden \hgcmd{bisect} usa su conocimiento de la ``forma'' de la historia de revisiones de su proyecto para hacer una búsqueda proporcional al \emph{logaritmo} del número de conjunto de cambios a revisar( el tipo de búsqueda que realiza se llama búsqueda binaria). Con esta aproximación, el buscar entre 10.000 conjuntos de cambios tomará menos de 3 horas, incluso a diez minutos por prueba(La búsqueda requerirá cerca de 14 pruebas). Al limitar la búsqueda a la última centena de conjuntos de cambios, tomará a lo sumo una hora(Apenas unas 7 pruebas). La orden \hgcmd{bisect} tiene en cuenta la naturaleza ``ramificada'' de la historia de revisiones del proyecto con Mercurial, así que no hay problemas al tratar con ramas, fusiones o cabezas múltiples en un repositorio. Puede evitar ramas enteras de historia con un solo sondeo. \subsection{Uso de la orden \hgcmd{bisect}} A continuación un ejemplo de \hgcmd{bisect} en acción. \begin{note} En las versiones 0.9.5 y anteriores de Mercurial, \hgcmd{bisect} no era una orden incluída en la distribución principal: se ofrecía como una extensión de Mercurial. Esta sección describe la orden embebida y no la extensión anterior. \end{note} Creamos un repostorio para probar el comando \hgcmd{bisect} de forma aislada \interaction{bisect.init} Simularemos de forma sencilla un proyecto con un fallo: haremos cambios triviales en un ciclo, e indicaremos que un cambio específico sea el ``fallo''. Este ciclo crea 35 conjuntos de cambios, cada uno añade un único fichero al repositorio. Representaremos nuestro ``fallo'' con un fichero que contiene el texto ``tengo un gub''. \interaction{bisect.commits} A continuación observaremos cómo usar la orden \hgcmd{bisect}. Podemos usar el mecanismo de ayuda embebida que trae Mercurial. \interaction{bisect.help} La orden \hgcmd{bisect} trabaja en etapas, de la siguiente forma: \begin{enumerate} \item Usted ejecuta una prueba binaria. \begin{itemize} \item Si la prueba es exitosa, usted se lo indicará a \hgcmd{bisect} ejecutando la orden \hgcmdargs{bisect}{good}. \item Si falla, ejecutará la orden \hgcmdargs{bisect}{--bad}. \end{itemize} \item La orden usa su información para decidir qué conjuntos de cambios deben probarse a continuación. \item Actualiza el directorio de trabajo a tal conjunto de cambios y el proceso se lleva a cabo de nuevo. \end{enumerate} El proceso termina cuando \hgcmd{bisect} identifica un único conjunto de cambios que marca el punto donde se encontró la transición de ``exitoso'' a ``fallido''. Para comenzar la búsqueda, es indispensable ejecutar la orden \hgcmdargs{bisect}{--reset}. \interaction{bisect.search.init} En nuestro caso, la prueba binaria es sencilla: revisamos si el fichero en el repositorio contiene la cadena ``tengo un gub''. Si la tiene, este conjunto de cambios contiene aquel que ``causó el fallo''. Por convención, un conjunto de cambios que tiene la propiedad que estamos buscando es ``malo'', mientras que el otro que no la tiene es ``bueno''. En la mayoría de casos, la revisión del directorio actual (usualmente la punta) exhibe el problema introducido por el cambio con el fallo, por lo tanto la marcaremos como ``mala''. \interaction{bisect.search.bad-init} Nuestra próxima tarea es nominar al conjunto de cambios que sabemos \emph{no} tiene el fallo; la orden \hgcmd{bisect} ``acotará'' su búsqueda entre el primer par de conjuntos de cambios buenos y malos. En nuestro caso, sabemos que la revisión~10 no tenía el fallo. (Más adelante diré un poco más acerca de la elección del conjunto de cambios ``bueno''.) \interaction{bisect.search.good-init} Note que esta orden mostró algo. \begin{itemize} \item Nos dijo cuántos conjuntos de cambios debe considerar antes de que pueda identifica aquel que introdujo el fallo, y cuántas pruebas se requerirán. \item Actualizó el directorio de trabajo al siguiente conjunto de cambios, y nos dijo qué conjunto de cambios está evaluando. \end{itemize} Ahora ejecutamos nuestra prueba en el directorio de trabajo. Usamos la orden \command{grep} para ver si nuestro fichero ``malo'' está presente en el directorio de trabajo. Si lo está, esta revisión es mala; si no esta revisión es buena. \interaction{bisect.search.step1} Esta prueba luce como candidata perfecta para automatizarse, por lo tanto la convertimos en una función de interfaz de comandos. \interaction{bisect.search.mytest} Ahora podemos ejecutar un paso entero de pruebas con un solo comando, \texttt{mytest}. \interaction{bisect.search.step2} Unas invocaciones más de nuestra prueba, y hemos terminado. \interaction{bisect.search.rest} Aunque teníamos unos~40 conjuntos de cambios en los cuales buscar, la orden \hgcmd{bisect} nos permitió encontrar el conjunto de cambios que introdujo el ``fallo'' con sólo cinco pruebas. Porque el número de pruebas que la orden \hgcmd{bisect} ejecuta crece logarítmicamente con la cantidad de conjuntos de cambios a buscar, la ventaja que esto tiene frente a la búsqueda por``fuerza bruta'' crece con cada conjunto de cambios que usted adicione. \subsection{Limpieza después de la búsqueda} Cuando haya terminado de usar la orden \hgcmd{bisect} en un repositorio, puede usar la orden \hgcmdargs{bisect}{reset} para deshacerse de la información que se estaba usando para lograr la búsqueda. Lar orden no usa mucho espacio, así que no hay problema si olvida ejecutar la orden. En todo caso, \hgcmd{bisect} no le permitirá comenzar una nueva búsqueda sobre el repositorio hasta que no aplique \hgcmdargs{bisect}{reset}. \interaction{bisect.search.reset} \section{Consejos para encontrar fallos efectivamente} \subsection{Dar una entrada consistente} La orden \hgcmd{bisect} requiere que usted ofrezca un reporte correcto del resultado de cada prueba que aplique. Si usted le dice que una prueba falla cuando en realidad era acertada, \emph{podría} detectar la inconsistencia. Si puede identificar una inconsistencia en sus reportes, le dirá que un conjunto de cambios particular es a la vez bueno y malo. Aunque puede no hacerlo; estaría tratando de reportar un conjunto de cambios como el responsable de un fallo aunque no lo sea. \subsection{Automatizar tanto como se pueda} Cuando comencé a usar la orden \hgcmd{bisect}, intenté ejecutar algunas veces las pruebas a mano desde la línea de comandos. Es una aproximación a la cual no esta acostumbrado. Después de algunos intentos, me di cuenta que estaba cometiendo tantas equivocaciones que tenía que comenzar de nuevo con mis búsquedas varias veces antes de llegar a los resultados deseados. Mi problema inicial al dirigir a la orden \hgcmd{bisect} manualmente ocurrieron incluso con búsquedas en repositorios pequeños; si el problema que está buscando es más sutil, o el número de pruebas que \hgcmd{bisect} debe aplicar, la posibilidad de errar es mucho más alta. Una vez que comencé a automatizar mis pruebas, obtuve mejores resultados. La clave para las pruebas automatizadas se puede resumir en: \begin{itemize} \item pruebe siempre buscando el mismo síntoma y \item ofrezca siempre datos consistentes a la orden \hgcmd{bisect}. \end{itemize} En mi tutorial de ejemplo anterior, la orden \command{grep} busca el síntoma, y la construcción \texttt{if} toma el resultado de esta prueba y verifica que siempre alimentamos con los mismos datos a la orden \hgcmd{bisect}. La función \texttt{mytest} los une de una forma reproducible, logrando que cada prueba sea uniforme y consistente. \subsection{Verificar los resultados} Dado que la salida de la búsqueda de \hgcmd{bisect} es tan buena como los datos ofrecidos por usted, no confíe en esto como si fuera la verdad absoluta. Una forma sencilla de asegurarse es ejecutar manualmente su prueba a cada uno de los siguientes conjuntos de cambios: \begin{itemize} \item El conjunto de cambios que se reportó como la primera versión erronea. Su prueba debería dar un reporte de fallo. \item El conjunto de cambios padre (cada padre, si es una fusión). Su prueba debería reportar este(os) conjunto(s) de cambios como bueno(s). \item Un hijo del conjunto de cambios. Su prueba debería reportar al conjunto de cambios hijo como malo. \end{itemize} \subsection{Tener en cuenta la interferencia entre fallos} Es posible que su búsqueda de un fallo pueda viciarse por la presencia de otro. Por ejemplo, digamos que su programa se revienta en la revisión 100, y que funcionó correctamente en la revisión 50. Sin su conocimiento, alguien introdujo un fallo con consecuencias grandes en la revisión 60, y lo arregló en la revisión 80. Sus resultados estarían distorcionados de una o muchas formas. Es posible que este fallo ``enmascare'' completamente al suyo, y que podría haberse revelado antes de que su propio fallo haya tenido oportunidad de manifestarse. Si no puede saltar el otro fallo(por ejemplo, este evita que su proyecto se arme o compile), y de esta forma no se pueda revisar si su fallo esté presente en un conjunto particular de cambios, la orden \hgcmd{bisect} no podrá ayudarle directamente. En cambio, puede marcar este conjunto de cambios como al ejecutar \hgcmdargs{bisect}{--skip}. Un problema distinto podría surgir si su prueba de la presencia de un fallo no es suficientemente específica. Si usted busca ``mi programa se revienta'', entonces tanto su fallo como el otro fallo sin relación que terminan presentando síntomas distintos, podría terminar confundiendo a \hgcmd{bisect}. Otra situación en la cual sería de mucha utilidad emplear a \hgcmdargs{bisect}{--skip} surge cuando usted no puede probar una revisión porque su proyecto estaba en una situación de rompimiento y por lo tanto en un estado en el cual era imposible hacer la prueba en esa revisión, tal vez porque alguien consignó un cambio que hacía imposible la construcción del proyecto. \subsection{Acotar la búsqueda perezosamente} Elegir los primeros ``buenos'' y ``malos'' conjuntos de cambios que marcarán los límites de su búsqueda en general es sencillo, pero vale la pena discutirlo. Desde la perspectiva de \hgcmd{bisect}, el conjunto de cambios ``más nuevo'' por convención es el ``malo'', y el otro conjunto de cambios es el ``bueno''. Si no recuerda cuál podría ser el cambio ``bueno'', para informar a \hgcmd{bisect}, podría hacer pruebas aleatorias en el peor de los casos. Pero recuerde eliminar aquellos conjuntos de cambios que podrían no exhibir el fallo(tal vez porque la característica donde se presenta el fallo todavía no está presente) y aquellos en los cuales otro fallo puede enmascararlo(como se discutió anteriormente). Incluso si termina ``muy atrás'' por miles de conjuntos de cambios o meses de historia, solamente estaŕa adicionando unas pruebas contadas para \hgcmd{bisect}, gracias al comportamiento logarítmico. %%% Local Variables: %%% mode: latex %%% TeX-master: "00book" %%% End: