Documentaton

Artifact [3f4b13add6]
Login
☰Home Timeline Branches Tags Tickets Wiki Login
Check-ins Using Download Text

Artifact 3f4b13add617db8303411bb83d72217a148d891455bf08ea12d0baa2331fdab7:

breaks: false info: | Este documento fue creado por la comunidad de Grafoscopio durante nuestros talleres, llamados Data Weeks y Data Rodas. Para saber más sobre el proyecto y las recomendaciones de edición y colaboración sobre este y otros documentos visita el repo. repo: https://mutabit.com/repos.fossil/documentaton/ sync: - https://docutopia.tupale.co/documentaton:fossil - repo://es/capitulos/fossil.md variants: - https://docutopia.tupale.co/fossil-dataweek

Fossil: Trabajo colaborativo distribuido

:::success - Propósito: Introducir los sistemas de control de versiones, en especial, Fossil. - Ejercicio práctico: Clonar un repositorio en Fossil, registrarse en él, sincronizarse y agregar nuevo contenido, hecho en Markdown. - Prerequisitos: - Lección: Markdown. :::

Fossil es un sistema de colaboración distribuido para gestión de código fuente. Los SCM (Software Configuration Management) o DVCS (Distributed Version Control System) resuelven el problema respecto a cómo reproduzco el estado de un sistema de cómputo y su historia (orientado a archivos). Al resolver esta inquietud, se está resolviendo una pregunta incidental que es sobre cómo colaborar, de maneras no centralizadas.

Fossil es el SCM elegido para trabajar con Grafoscopio y el Data Week por su caracter sencillo y autocontenido, lo cual quiere decir que brinda mucha funcionalidad en un único programa, con flujos de trabajo y colaboración simples, y puede ejecutarse en una variedad grande de plataformas de hardware y software, con mínimos requerimientos de recursos de hardware (poca memoria RAM, menos de 3 Mb en disco duro) y software, además tanto los datos como los metadatos (salvo las contraseñas) son repartidos entre todos los usuarios que se sincronicen al repositorio, es decir, satisface nuestra definición de infraestructuras de bolsillo.

Existen algunas pocas herramientas para Git, como Gogs, que siguen el enfoque minimalista de Fossil, si bien no toda la información parece ser autocontenida e implican los flujos de trabajo complicados propios de Git.

Referencias Extra:

Instalación

Antes de proceder a la instalación es conveniente verificar si ya se tiene instalado fossil (por ejemplo verificar si el comando "fossil" existe tecleando $ which fossil).

En Gnu/Linux

Averigua con el gestor de paquetes (apt, pacman) si tu distribución de Linux tiene Fossil disponible en una versión relativamente reciente (como las que usamos para nuestros talleres) e instálada desde dicho gestor.

:::warning En nuestra experiencia, algunas distribuciones derivadas de Debian, suelen tener paquetes muy viejos de Fossil. :::

Usando gestores/instaladores de software

Más información acá

Windows

Con Scoop

:::info Importante: Para hacer estar parte debes haber instalado previamente Scoop. :::

Abrimos Power Shell y escribimos:

  scoop install fossil

Al ejecutarlo, debemos ver algo como esto:

Installing 'fossil' (2.8) [32bit]
fossil-w32-2.8.zip (2.1 MB) [=================================================================================] 100%
Checking hash of fossil-w32-2.8.zip ... ok.
Extracting fossil-w32-2.8.zip ... done.
Linking ~\scoop\apps\fossil\current => ~\scoop\apps\fossil\2.8
Creating shim for 'fossil'.
'fossil' (2.8) was installed successfully!

Métodos de instalación alternativos

Se puede instalar desde el gestor de paquetes en Linux, Mac, Windows, pero cuando está muy desactualizado, una alternativa es instalarlo desde el código fuente.

Gnu/Linux y Mac

Así se hace esto en Gnu/Linux y Mac, usando comandos en la terminal:

  1. Descargar el instalador desde la página web:

    cd /tmp
wget http://fossil-scm.org/index.html/uv/fossil-linux-x64-2.3.tar.gz

  2. Descomprimimos el archivo:

    tar xvfz fossil-linux-x64-2.3.tar.gz

  3. Encontraremos un binario llamado fossil que copiamos a donde están todos los binarios:

    sudo cp fossil /usr/bin

Trabajar con repositorios

Para usar Fossil, vamos a sincronizarnos contra un repositorio, agregar archivos a este y mirar cómo ha cambiado su línea de tiempo. Hay otras cuestiones que vamos a dejar en el radar, pero que no vamos a profundizar, como el hecho de publicar repositorios propios. Sin embargo, ese tipo de funcionalidad también está provista por sistemas como Chisel.

Navegación

Existen determinados lugares para visitar con los cuales uno se puede hacer una idea de un repositorio de Fossil, sus contenidos y actividad. A continuación los listamos esos lugares, mostrando algunos ejemplos de los mismos en distintos repositorios.

Tickets: Sugerencias, correcciones y planeación

Una de las maneras más habituales de usar repositorios es a través de los tickets (boletas), que permiten realizar sugerencias sobre mejoras o ampliaciones, reportar errores para realizar correcciones e incluso hacer una gestión ligera de cómo el proyecto va dando cuenta de las solicitudes que se hacen sobre el mismo. Acá veremos cómo realizar cada una de estas actividades.

Crear un ticket

Empecemos por crear un ticket. Estos son los pasos:

Cerrar un ticket

La sección precedente nos enseñó como abrir un ticket y nos dijo que esta era una de las formas más habituales de trabajo con los repositorios, como usuarios del proyecto que allí se construye. Esta sección muestra otra de las formas más habituales de trabajo, como co-autores del mismo: cerrar tickets.

Para esta sección, supondremos que tienes familiaridad con el resto del capítulo sobre Fossil. Si estás leyendo el libro en orden y sólo has leído hasta acá, es conveniente que la saltes y aprendas el resto de los elementos del trabajo básico con repositorios (clonación, modificación, etc), antes de proceder a cerrar el ticket. Hemos dejado esta sección acá, simplemente para manetener consistente la presentación.

Cerrar un ticket puede ocurrir por distintos motivos, pero el más usual de ellos es que hicimos trabajo dentro del repositorio para abordarlo. De este modo, los commits en el repositorio y los tickets pueden enlazarse, de modo que el trabajo hecho esté en el repositorio conectado con el reporte que solicitaba hacerlo.

Tomemos por ejemplo el ticket de la sección precedente. Una vez hemos empezado a explicar en la obra el aspecto que el ticket nos solicitaba, escribiendo y modificando los textos que dan cuenta de ello (bien sea en prosa o código) podemos hacer un commit indicándolo, con un comando como este:

fossil commit -m "Pandoc: Abordando ticket [921caf54a2]."

Veamos cómo queda la línea de tiempo en este caso:

Línea de tiempo donde el _commit_ se refiere al _ticket_.{width=60%}

Vemos quel el último commit dice algo como:

Pandoc: Abordando ticket [921caf54a2] Leaf check-in 9f8e9e98f1

es decir que hemos vinculado el check-in 9f8e9e98f1 con el ticket 921caf54a2 y si miramos los detalles del primero, veremos cuáles archivos cambiaron para poder abordar esta solicitud, en particular veremos esto:

Diff en el archivo sobre Fosil: muestra lo que se agregó (en verde) y removió (en rojo) de un archivo mientras se explicaba como funcionan los _tickets_{width=60% #fig:ticket-diff}

Es decir, que un lector del repositorio está en condiciones de ver los archivos que se modificaron y en qué partes, para dar cuenta de determinada solicitud. Esto puede ocurrir para trozos de texto sustanciales, como en este caso, o porque hicimos cambios pequeños, como agrega una imagen a un capítulo o sus cabeceras, redimensionarla, o porque hicimos varias correciones de estilo u ortográficas. De este modo, cambios grandes o pequeños, solicitados por los lectores y usuarios de nuestra creación, pueden ser auditados asociándolos con los cambios efecticamente hechos en los archivos, para dar cuenta de los mismos.

Ahora bien, los vínculos son mejores en la web, si funcionan de doble vía. Cuando vayamos a cerrar el ticket, entrando en el mismo desde la tabla de resumen de todos ellos, mostrada en la sección precedente, es conveniente indicar que identificadores de los commits corresponde a aquellos donde se hizo trabajo en el ticket. Por ejemplo, ahora que se ha explicado un poco más sobre como cerrar el ticket, haremos otro commit, similar al anterior:

 fossil commit -m "Fossil > Tickets: Cómo cerrarlos (ver [921caf54a2])."

Lo cual produce esta línea de tiempo ahora:

Segundo commit para cerrar un ticket{width=60%}

y cuando editemos el ticket 921caf54a2, para cerrarlo. El formulario para cerrar ticket quedaría algo así:

Editando el ticket para cerrarlo.{width=70%}

Nótese que hemos cambiado el campo Status por Closed y el campo Resolution por Fixed, y en la descripción detalllada de cómo lo cerramos hacemos referencia a aquellos commits que hablaben del mismo en la línea de tiempo, en este ejemplo aquellos con los identifadores [9f8e9e98f1] y [49406fac71] (recordemos que al usar los paréntesis cuadrados, los convertimos automáticament en un enlace dentro del repositorio). Veamos cómo queda ahora la línea de tiempo:

Línea de tiempo una vez se ha cerrado el _ticket_.{width=70%}

El ticket que hemos cerrado aparece tachado (~~[921caf54a2]~~) y todos los estados de la línea de tiempo correspondientes a commits donde se referencio dicho ticket continuan enlazados al mismo. A su vez, si hacemos click en el ticket, veremos que apunta a los commits en líneas de tiempo donde trabajamos en el mismo:

Detalle de _ticket_ cerrado{width=60%}

De este modo Fossil nos provee una manera ligera de gestionar proyectos, mediante una práctica sencilla: enlazar commits y tickets entre sí. Una vez hallamos creado un ticket, usamos su UUID resumido y entre paréntesis angulares para los commits que trabajen en el mismo y, una vez cerremos el ticket, hacemos lo propio para los commits, creando así una vinculación en doble vía. Si por alguna razón se reabre un ticket, es posible repetir este procedimiento con futuros commits para abordarlo y ediciones del mismo para cerrarlo.

Ya sea que queremos reportar y corregir errores o solicitar e implementar nuevas características en nuestra obra, esta manera de proceder nos permitirá indicar con agilidad qué hemos hecho en cualquiera de esos frentes y hacerlo transparente a la comunidad que se reune en torno a la obra.

Clonación

:::warning ADVERTENCIA: asegurarse que los comandos se ejecutan en el directorio correcto porque se pueden crear un montón de directorios y cosas en un directorio que no se desea. :::

Cuando se descarga un repositorio lo que se hace es traer toda la historia del mismo de su lugar remoto a mi disco duro. Vamos a hacer esto con el repositorio de la Documentanton, desde la consola de comandos.

Donde <nombre_repositorio> es el nombre de la carpeta a descargar (repositorio).

Modificación

Vamos a crear un archivo en una subcarpeta dentro de la carpeta de idiomas, que contiene un de los capítulos del librillo.

Sincronización

La sincronización entre repositorios es hecha a través de un servidor que sirve como coordinador. En nuestro caso, será el repositorio original del Data Week. Lo anterior quiere decir que debemos registrarnos en dicho repositorio y solicitar permisos para sincronizarnos con él.

Pantalla de registro de Fossil{width=85%}

Donde <usuario> es el usuario que creamos en el paso anterior del "login" (sin los símbolos < >).

donde <usuario> es el nombre del usuario con el que nos registramos en Fossil y <nombre_repositorio> es el nombre del repositorio (carpeta descargada)

::: success En caso de que la actualización falle, es probable que hayas realizado una sincronización con un usuario incorrecto, verifica el usuario con que estas sincronizando, recuerda que fossil es sensible a minusculas y mayusculas. :::

Deberas tener una respuesta como esta:

Round-trips: 2   Artifacts sent: 0  received: 4
Sync done, sent: 1123  received: 3782  ip: 45.55.37.99

Cómo resolver las bifurcaciones involutarias (forks).

La diferencia entre "branches" y "forks":

El estado del repositorio a hoy era este:

Repositorio antes del merge.{width=85%}

Vemos que se han integrado dos bifurcaciones, pero aún quedan tres por integrar. Cada estado del sistema está descrito por un código alfanumérico único, suma hash.

Las ramas que fueron integradas corresponden (en la imagen) a las siguientes sumas hash: [f0ea5717e4] (El commit de Grace) y el tronco (trunk) de ese momento, cuyo checksum corresponde a [1b5023d5a4], produciendo un estado del sistema nuevo, cuyo checksum es [dcd4e53045].

Vamos a integrar una nueva ramificación en el tronco principal. Para ello, ubicados en el repositorio, desde la terminal

fossil update trunk
fossil merge 0ef40cd985

Aparecerá algo como esto:

Autosync:  http://offray@mutabit.com/repos.fossil/<nombre_repositorio>/
Round-trips: 1   Artifacts sent: 0  received: 0
Pull done, sent: 383  received: 2429  ip: 45.55.37.99
ADDED Participantes/Ivan/intro.md
 "fossil undo" is available to undo changes to the working checkout.
WARNING: multiple open leaf check-ins on trunk:                                                   
  (1) 2018-02-24 18:59:24 [dcd4e53045] (current)
  (2) 2018-02-24 01:33:03 [5da6cdb6dc]
  (3) 2018-02-24 01:32:45 [0a25a7636d]
  (4) 2018-02-24 01:31:51 [0ef40cd985]

Luego hacemos un commit al repositorio:

fossil commit -m "Integrando cambios de Iván."

Y luego mezclamos ese commit con el tronco principal, que de ahora en adelante llamaremos simplemente "trunk". Veremos algo como esto:

Repositorio después del merge.{width=85%}

NOTA: Si olvidas hacer el fossil update trunk antes de hacer el merge, puedes usar fossil undo para revertir el cambio.

Varios

<!-- [[Indice](./indice-tematico)] [< [Markdown](./markdown)] [[Grafoscopio](./grafoscopio) >] -->

This page was generated in about 0.009s by Fossil 2.21 [f9aa474081] 2023-02-25 19:23:39