Category: Programación

Cambiar de Branch en un Shallow Clone

posted by under Programación

Si estas usando sistemas de integración continua (Continuous Integration), trabajas con repositorios pesados o simplemente no quieres pasar por un un clonado de Git que te traiga todo el árbol de un repositorio, seguro que estás familiarizado con el concepto shallow clone o clonado superficial.

Un shallow clone o cloando superficial permite traerse los últimos commits y no todo el histórico del repositorio Git. Aunque pueda parecer una solución maravillosa para desprenderse de los problemas de un clonado completo del histórico del árbol Git , presenta ciertos problemas a la hora de operarlo como un repositorio clonado de manera normal cuando se ha clonado bajo estas condiciones específicas de clonado.

🐑 Crear un clonado superficial

Para ejecutar un clonado superficial o shallow clone lo haremos con el siguiente comando:

git clone -–depth [depth] [remote-url]

Donde depth la profundidad es el número de commits que nos vamos a traer durante el clonado y remote-url es la dirección URL de origen de donde vamos a clonar el repositorio. 👀 El uso de --depth implica --single-branch.

Para ejecutar clonado superficial o shallow clone de una rama o branch podemos hacerlo con:

git clone [remote-url] -–branch [name] -–single-branch

Donde name es el nombre de la rama o branch que queremos clonar.

Si aún queremos hilar más fino y resulta que tenemos repositorios con submódulos (repositorios Git incluidos en otro repositorio), los cuales tienes su propio árbol Git y se inicializan usando alguno de los siguientes comandos:

git clone -–recursive [remote-url]  # Git version >= 1.6.5
git clone -–recurse-submodules -–jobs [num-jobs] [remote-url]   # Git version >= 2.13

La primera sintaxis con recursive puede resultar más cómoda, aunque resulta más rápida y eficiente la segunda con recurse-submodules, la cual es la sintaxis vigente que permite especificar el número de submódulos operados concurrentemente mediante jobs.

Si este es tu caso, no tiene sentido hacer un clonado superficial si se hace un clonado completo de los submódulo. Para ello ejecutaremos el siguiente comando:

git clone -–depth [depth] -–shallow-submodules [remote-url]

La opción --shallow-submodules implica que todos los submódulos se clonarán con una profundidad de 1.

🐏 Convertir un repositorio con clonado superficial en uno de tipo clonado completo

Si has seguido los pasos anteriores, te darás cuenta que si quieres cambiarte por ejemplo a otra rama no puedes. Eso es debido a que se ha omitido el resto del histórico según se lo hemos especificado. ¿Eso significa que no existe? No, eso sólo quiere decir que no lo conocemos.

Si ejecutamos el siguiente comando sobre un repositorio clonado superficialmente, veremos los remotos que conocemos y los remotos existentes en el local:

git branch -–all

Si intentamos hacer un fetch del remoto veremos que tampoco conseguimos ver el histórico completo del repositorio:

git fetch -–verbose

Esto es debido a que nuestro remoto no está convenientemente configurados debido al clonado superficial. Podemos restaurar su funcionalidad completa partiendo de que nuestro remoto origin, de donde clonamos el repositorio, contiene la remote -url que metimos. Por ello podemos restaurar el acceso a todo el histórico del remoto para nuestro repositorio, usando el siguiente comando:

git remote set-branches origin "*"

Mediante la opción set-branches podemos cambiar la lista de ramas que son seguidas por el remoto conocido y por defecto que es origin.

Ahora volvemos a ejecutar el comando fetch de nuevo y en este caso podremos apreciar que la totalidad de ramas aparecen:

git fetch -–verbose

Adicionalmente también restauramos el histórico completo de la rama actual donde nos encontramos:

git fetch --unshallow

Con esto ya tenemos acceso al historial completo del repositorio y podremos cambiarnos a otra rama a la cual antes no podíamos:

git checkout rama-que-estaba-buscando

Si quieres comprobar el último commit de la rama local para cotejarlo con el último commit disponible el remoto y comprobar que está todo correcto, puedes hacerlo con:

git show

💡 Conclusiones

El clonado superficial o shallow clone es una gran herramienta, pero puede echarnos el lazo al cuello si no sabemos y necesitamos deshacerlo. No obstante aunque siempre existe la opción de hacer un clonado clásico de nuevo, no resulta una opción elegante y eficiente que nos obliga a duplicar y volver a clonar el repositorio.

Inclusión de aportes mediante las diferentes estrategias de Merge en Git

posted by under Programación , ,

Cada vez suele ser más normal ver la figura del ingeniero de software que se dedica a la gestión de proyectos, gestionando las ramas de desarrollo (develop & features) y la rama estable master (recientemente normalizada como main).

Imagen obtenida de la presentación Desarrollo Colaborativo de Software

Muchas veces sin querer se usan las herramientas de "merge" de código de manera incorrecta sin pararse a pensar en los beneficios y "contraprestaciones" que puede tener hacerlo de una forma u otra. Es por ello que este artículo, pretende arrojar algo de luz en qué nos puede convenir hacer en cada momento.

Antes de nada vamos a aclarar la notación para que resulte todo más sencillo. Nos referiremos a la rama Base, como la rama a la que se desea fusionar los cambios en el proceso de merge. Por otro lado nos referiremos a la rama Head como la rama que contiene los cambios que queremos incluir en la rama Base. Estos cambios en términos de plataformas para el desarrollo colaborativo de software como GitHub, GitLab, Bitbucket o Gogs, se suele aplicar con frecuencia en los conocidos como Pull Request (PR). Una solicitud formal a la inclusión de código de un desarrollador o grupo de desarrolladores externo al equipo de desarrolladores de un repositorio, la cual puede ser revisada y probada antes de realizar el merge.

La rama Base más habitual es la master o main que es asumida además como rama estable del desarrollo en un repositorio de manera generalizada. Los puntos más estables y que deberías usar son los denominados Tags de versión que son puntos específicos donde se ha trabajado una estabilidad específica que suele cerrar una iteración de desarrollo que incluye mejoras y soluciones a fallos conocidos desde la anterior versión.

Porque sale fuera de alcance de este artículo, no mencionaremos toda la problemática y gestión inherente que puede aparecer en forma de conflicto cuando realizamos un merge de código. Conflictos que deberán ser resueltos para asegurar la coherencia y estabilidad de la rama Base. Y que dicho sea de paso, suelen ser producidos muchas veces por falta de comunicación o por no ser "aséptico" en la forma de programar, refactorizando el código más de la cuenta o cuando no toca, por tener un mal diseño de clases o funciones... o incluso por aplicar la regla del scout que se resume en "Dejar las cosas mejor de como te las encontraste". Esto último puede convertir en un infierno la tarea de la persona que se dedica a integrar cambios y aportes externos si no se gestiona correctamente o falla el proceso de comunicación. Los potenciales conflictos por cambios en el código, es la causa número uno por la que una propuesta de cambio (PR) acaba por no integrarse al código finalmente y por consecuencia genera frustración y pérdida de tiempo.

Merge

La opción de hacer un merge de varios commits de una rama (Head) o hacer un merge de un PR es la acción habitual y predeterminada. Al realizar el merge todos los commits de la rama Head se fusionarán con los de la rama Base.

Estado inicial

Tras aplicar el merge

En esta ilustración, la rama Head se bifurca desde el segundo commit en la rama Base. Se sugieren algunos cambios como nuevas confirmaciones en la rama Head y ahora deben actualizarse en la rama Base. Mediante el merge, las confirmaciones se agregan a la rama Base como se muestra en la imagen superior.

No obstante el ejemplo presentado resulta una visión simplificada, existiendo dos posibles formas de hacer el merge dependiendo de la casuística en la inclusión o no del merge commit.

Fast-Forward o No Fast-Forward 🤔

En el primer caso, el merge fusiona lo cambios y añade los commits de la rama Head en la rama Base. Esto es posible siempre y cuando los commits se produzcan en la rama Head. Básicamente lo que se produce es un desplazamiento del puntero (fast-forward) de la rama Base al último commit de la rama Head.

master = Base | feature = Base

En el segundo caso, con el merge se añade un commit adicional en la rama Base que deja constancia de la unión de la rama Head con la rama Base. Este commit adicional aparece, bien porque lo forzamos para que no se produzca un fast forward (--no-ff); o bien porque la rama Base también contenía cambios, existiendo cambios en ambas ramas en el momento de la fusión.

Squash + Merge

Squash y merge combina todos los commits de la rama Head en un único commit y luego fusiona la rama Head con la rama Base. De esta manera, el historial de commits de la rama Head queda simplificado en un único commit en la rama Base.

Estado inicial

Tras aplicar squash + merge

Se puede observar que la rama Head se bifurca desde el segundo commit de la rama Base y se agregan dos nuevos commits que se añaden a la cabecera de la rama Base. Mediante squash y merge, ambos commits (6 y 7) se combinan en una único commit y luego se fusionan en la rama Base como se muestra en la imagen superior.

Rebase + Merge

Rebase y merge agrega todas los commits en la rama Head de manera individual a la rama Base sin un merge commit. Para todas los hotfix y commits puntuales que no se puedan fusionar con otros commits, esta es la opción de referencia. Esto es debido a que a no existe relación de parentesco con los commits preexistentes del propio árbol.

Cuando se hace una reorganización con rebase en el flujo de los commits de una rama, el SHA único de cada commit cambia debido a que además del contenido del commit para la formación del hash SHA, también se tiene en cuenta el parentesco con el commit inmediatamente anterior y por consiguiente del árbol completo. Este hecho provoca que el uso de rebase provoque más conflictos y su gestión sea más complicada. Esta gestión es complicada, es debido a que Git principalmente usa los commits comunes como base de parentesco, el contenido del propio commit y su contexto (líneas de código anteriores y posteriores a cada cambio de un commit); y en el caso del rebase por causa de la reorganización, no se cuenta con la base de parentesco.

Estado inicial

Tras aplicar rebase + merge de la rama Base a la rama Head

Tras aplicar rebase + merge de la rama head a la rama Base

Atendiendo a la ilustración, la rama Base se bifurca en el segundo commit para formar la rama Head. Posteriormente, se agrega un nuevo commit a la rama Base. Mientras tanto, los commits se realizan en la rama Head.

Por causa del rebase y merge de la rama de la Base a la rama Head, la base de la rama Head se vuelve a colocar. Es decir, ahora la rama Head se bifurca desde el nuevo tercer commit para que el nuevo commit de la rama Base se incluya en la rama Head. Y luego, se aplican los commits en la rama Head.

Ahora, para actualizar la rama Base con los últimos commits de la rama Head, el rebase se realiza de la rama Head a la rama Base como se muestra en la imagen superior.

GitHub

En GitHub podemos ver estas 3 opciones, siendo el ejemplo más habitual e ilustrativo cuando estamos revisando un PR y finalmente decidimos incorporar los cambios:

Haciendo click en la flecha que apunta hacia abajo al lado del "Merge pull request", podremos ver las tres formas de hacer merge que hemos mencionado. De manera análoga GitLab, Bitbucket o Gogs presentan las mismas opciones, o muy similares.

Conclusiones

Tras ver todas las opciones de merge, es recomendable tener en Git cuanta más traza mejor, eso incluye la creación del merge commit evitando el fast-forward si con ello podemos mejorar la traza de la rama donde existían los cambios que se fusionan a la rama Base.

Pero si trabajas en proyectos grandes o eres el gestor de la ramas de desarrollo de un repositorio con suficientes desarrolladores implicados, es más que seguro usarás squash y merge para compartimentar mejor los commits de cada desarrollador. Eso sí asegúrate de tener un buen sistema de CI como Travis CI o AppVeyor, así como suficientes pruebas unitarias, porque el problema de juntar varios commits en uno, es la imposibilidad de revertir los commits parciales una vez que se han juntado.

Por último el uso de rebase y merge es recomendable hacerlo como última opción y en caso de que squash y merge no sean suficiente o se quiera tener la trazabilidad manteniendo los commits parciales de las ramas que se fusionan (hotfix, commits puntales, excesiva densidad de ramas del árbol de versionado Git...), pudiendo realizar así una regresión limpia y más fácil de seguir. La principal desventaja de este método es que se pierde trazabilidad cronológica por la reorganización y potencialmente aumentan los conflictos, pero a la vez se gana simplicidad y claridad en el árbol debido a que no genera una densidad de ramas que complique su gestión. Además, también es posible revertir cualquier commit parcial, pero esto pierde relevancia, cuando se asume que existen servicios de CI que deberías estar ya usando que pueden hacer correr tus pruebas unitarias y ahorrarte sufrimiento y sobresfuerzo innecesario.

Comprobar permisos de Administrador en una ejecución (estilo 🐍 Python)

posted by under Programación , , , ,

Habitualmente nos encontramos con la situación en la que debemos ejecutar ciertos programas o flujos de ejecución y necesitamos permisos de Administrador. Estas situaciones se nos presentan cuando tenemos que manejar carpetas y ficheros en acciones que impliquen lectura, escritura o ejecución en directorios protegidos del sistema. Para ello se requiere una elevación de permisos que deberemos comprobar si existe antes de lanzar nuestra ejecución.

Aprovechando que seguramente tengamos que hacer esto varias veces, creo que la mejor opción de hacerlo es con el mejor lenguaje pegamento que existe hasta la fecha, que no es ni más ni menos que Python. Por ello la solución final que vamos a plantear es excelente tanto para administradores de sistemas como para desarrolladores, siendo además multiplataforma GNU/Linux y Windows.

Tenemos que tener en cuenta que GNU/Linux y Windows no funcionan igual para la gestión de permisos. En Windows preguntaremos desde la API disponible si el usuario es administrador, mientras que en GNU/Linux preguntaremos por si el usuario tiene permisos root.

import ctypes, os
from sys import exit


def is_admin():
    is_admin = False
    try:
        is_admin = os.getuid() == 0
    except AttributeError:
        is_admin = ctypes.windll.shell32.IsUserAnAdmin() != 0

    print ("Admin privileges: {}".format(is_admin))
    return is_admin

Para mirar los permisos en Windows usaremos la librería ctypes y para los permisos en GNU/Linux usaremos la librería os. Ambas están incluida en Python. Por una razón arbitraría se ha elegido comprobar primero GNU/Linux y después Windows.

Cuando se comprueba en GNU/Linux invocamos a la función os.getuid que nos devolverá 0 en el caso de ser root. Si llamamos a la función desde Windows con Python nos elevará una excepción del tipo AttributeError, que aprovecharemos a capturar para hacer la comprobación en Windows invocando a la función ctypes.windll.shell32.IsUserAnAdmin. En ambos casos guardaremos el booleano de la evaluación y lo devolveremos al final de la función.

Hasta aquí sencillo, pero esto es código Python y es necesario tener el interprete de Python, con el que obliga al sistema a tener instalado el intérprete de Python. Para solucionarlo, deberíamos convertir nuestro código en un programa añadiendo un punto de entrada y devolviendo un código de retorno tras la ejecución.

import ctypes, os
from sys import exit


def is_admin():
    is_admin = False
    is_win = False
    try:
        is_admin = os.getuid() == 0
    except AttributeError:
        is_admin = ctypes.windll.shell32.IsUserAnAdmin() != 0
        is_win = True

    print ("Admin privileges: {}".format(is_admin))
    return is_admin, is_win

Antes modificaremos un poco la función is_admin()añadiendo un valor is_win que usaremos para saber que estamos comprobando en GNU/Linux o Windows los permisos de administrador, devolviendo el valor como un segundo valor en el retorno de la función.

Recordad que Python es posible recoger múltiples valores de retorno en una variable como una tupla, en variables separadas o incluso tirar los valores que no nos interesen.

def my_function():
    a = 2
    b = 3
    return a, b

a = my_function()
print(a)  # out: (2, 3)

a, b = my_function()
print(a)  # out: 2
print(b)  # out: 3

a, _ = my_function()  #  b es ignorado
print(a)  # out: 2

Además añadimos un punto de entrada debajo de la función is_admin().

if __name__ == "__main__":
    is_admin, is_win = is_admin()
    # Converting boolean to integer 
    ret = int(is_admin == False)
    if is_win:
        exit(ret)
    else:
        exit(ret * -1)

Comprobar si __name__ es __main__, es una excelente forma de hacer que cada unidad de fichero Python sea ejecutable si se quiere. El nombre de __main__ sólo es dado al fichero Python que es dado al intérprete para ser ejecutado y en caso de no serlo, siempre puede ser importado en otro fichero Python, sin que el punto de entrada afecte.

Como vemos, ahora estamos recogiendo en el retorno is_admin e is_win. Necesitamos el segundo valor para decidir el valor de retorno, ya que los códigos de error en Windows son enteros positivos y en GNU/Linux son enteros negativos. El único punto en común es que devolver un 0 es señal de que la ejecución fue correcta. Sabiendo esto debemos adaptar el retorno de los errores dependiendo el sistema.

💾 Binarizando nuestra aplicación Python

Para convertirlo en un ejecutable usaremos PyInstaller, el cual podéis instalar con un simple pip install pyinstaller. Para binarizar nuestra aplicación en un ejecutable autocontenido con el interprete de Python ejecutaremos:

pyinstaller -F is_admin.py

De esta forma resultará, mucho mas sencilla la distribución de nuestra aplicación.

👔 Puesta en Producción

Ahora vamos a plantear los dos casos de uso para Windows y GNU/Linux. Como aclaración, decir que los ejemplos expuestos se pueden usar tanto con la versión binarizada o con la de código invocando al intérprete de Python.

Windows

@echo off

cd
cd /D "%~dp0"
cd

#REM python is_admin.py
is_admin.exe

if errorlevel 1 (
   echo Exit Code is %errorlevel%
   echo.
   echo Admin privileges required
   echo Run it again as Administrator
   echo.
   pause
   exit /b %errorlevel%
)

#REM [your_executable].exe

pause

👀 Puedes descargar la versión binarizada de is_admin.exe

GNU/Linux

#!/bin/bash

pwd
cd `dirname $0`
SCRIPTDIR=`pwd`
pwd

#python is_admin.py
is_admin


if [ $? -eq 0 ]
then
  # [your_executable]
else
  echo Exit Code is $?
  echo.
  echo Admin privileges required
  echo Run it again as Administrator
  echo.
  read -rsp $'Press any key to continue...\n' -n 1 key
  exit $?
fi

read -rsp $'Press any key to continue...\n' -n 1 key

Si no estás tan familiarizado con el Bash te invito a que visites el proyecto ExplainShell para que puedas obtener la explicación de los diferentes comandos y argumentos.

🥅 Conclusiones

La solución presentada, sin ser seguramente perfecta, asegura tanto a administradores de sistemas como desarrolladores, comprobar si existen los permisos de administrador necesarios de manera sencilla; pudiendo hacerlo con una versión binarizada autocontenida que incluya el intérpretete Python, ejecutándolo usando el intérprete de Python del sistema gracias a ser todo dependencias internas, o llamando directamente a la función is_admin() si se quiere integrar en un desarrollo.

El código completo puedes encontrarlo en el siguiente gist de GitHub:

Espero que esta forma de trabajar te resulte útil y puedas extrapolarla y usar para otros casos Python como tu lenguaje pegamento generando código y aplicaciones altamente reutilizables.

Gestión de dependencias y versionado en Python

posted by under Programación

Cuando programas una de las cosas más importantes para asegurar la compatibilidad y el soporte de una librería, herramienta o programa, es el versionado del mismo.

El versionado sirve para que a nivel interno, el equipo de desarrolladores pueda llevar un control de hitos dentro del desarrollo y a su vez sirve para que otros desarrolladores o usuarios, que usan estas librerías, herramientas o programas, puedan tener un control a la hora de integrarlas o actualizarlas.

Ahora bien, el problema viene a la hora de establecer la significación de dicho número de versión. En Python es normal usar el sistema SemVer, el cual establece tres grupos de números separados por puntos de la forma MAJOR.MINOR.PATCH

  • MAJOR: Se incrementa cuando cuando se realizan cambios incompatibles a nivel de API.
  • MINOR: Se incrementa cuando se añaden funcionalidad de manera retrocompatible.
  • PATCH: Se incrementa cuando se corrigen 🐛 fallos de manera retrocompotible

Es posible que estuvieras familiarizado con este sistema de versionado, pero aún así te recomiendo su lectura completa en https://semver.org.

Teniendo esto claro, vamos a pasar a ver la aplicación práctica que que tiene esto en la gestión de dependencias, donde la generación de paquetes para su distribución en Pipy es donde se marca la diferencia. Podemos ajustar que nuestro paquete maneje las dependencias de acuerdo a criterios de versión de Python, debido a casos como que una librería específica deje de dar soporte a ciertas versiones de Python a partir de cierta versión.

En el caso citado, hay dos opciones directas que son, o retirar soporte a ciertas versiones de Python propagando la restricción de alguna de nuestras dependencias, o controlar las versiones de las dependencias dependiendo de la versión de Python a utilizar. Veamos cómo:

colorama==0.3.7; python_version < '3.4.*'
colorama>=0.3.7; python_version >= '3.4.*'

En este caso definimos en nuestro requirements.txt la condición de que para versiones de Python menores a 3.4.* es necesario usar la versión de colorama 0.3.7, ya que dicha dependencia retira el soporte a versiones inferiores desde esa versión. Para versiones iguales o mayores a 3.4.*, simplemente se exige una versión mayor o igual a 0.3.7. Atención a que siempre se citan los tres grupos de números.

Otras veces puede pasar que cierta versión de una dependencia nos dé problemas y queramos convertirla en una excepción al requerimiento

fake_library>1.6.2,!=1.7.2

En este caso de la librería inventada fake_library exigiría una versión superior a 1.6.2, pero que no sea 1.7.2.

Por último es posible instalar dependencias que sean necesarias para ciertos sistemas operativos. Veamos un ejemplo:

pywin32 >=1.0.*; sys_platform == 'win32'
SistemaValor platform
AIX'aix'
GNU/Linux'linux'
Windows'win32'
Windows/Cygwin'cygwin'
macOS'darwin'

https://docs.python.org/3/library/sys.html#sys.platform

Para el ejemplo se especifica una versión superior o igual a 1.0.* de pywin32 en el caso de encontrarnos en un sistema Windows.

Finalmente es posible que en el setup.py de una librería, herramienta o aplicación, se obligue a contar con unas versión especificas de Python y/o evitar otras:

from setuptools import setup
 
setup(
    name='mypackage',
    packages=['mypackage'],
    version='0.1',
    license='LGPL v3',
    description='A random test lib',
    author='RDCH106',
    author_email='contact@rdch106.hol.es',
    url='https://github.com/RDCH106/mypackage',
    download_url='https://github.com/RDCH106/parallel_foreach_submodule/archive/v0.1.tar.gz',
    keywords='test example develop', 
    python_requires='>=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*', # requerimientos de versión de Python
    classifiers = ['Programming Language :: Python',
                   'Programming Language :: Python :: 2.7',
                   'Programming Language :: Python :: 3.4',
                   'Programming Language :: Python :: 3.5',
                   'Programming Language :: Python :: 3.6',
                   'Programming Language :: Python :: 3.7',
                   'Programming Language :: Python :: 3.8'],
)

En la línea 14 se puede ver que se especifica que se requiere versiones de Python mayores a 2.7, pero que no sean ni 3.0.*, 3.1.*, 3.2.* o 3.3.*.

Todas estas reglas condicionales para la gestión de dependencias quedan reflejadas en las PEP (Python Enhancement Proposal) 345, 440, 496 y 508 principalmente.

Espero que todo esto sirva para evitar caer en el llamado “infierno de las dependencias”, mientras crece tu librería, herramienta o aplicación.