Skip to article frontmatterSkip to article content
Site not loading correctly?

This may be due to an incorrect BASE_URL configuration. See the MyST Documentation for reference.

🖥️ Diapositivas — Sesión 02 (vie 2 oct)

Control de versiones

El control de versiones es un sistema que organiza y rastrea las versiones del código.

Versiones de un artículo de investigación. Los nombres de archivo y los cambios rastreados a mano se vuelven un desorden. De PhD Comics.

Versiones de un artículo de investigación. Los nombres de archivo y los cambios rastreados a mano se vuelven un desorden. De PhD Comics.

Lleva el registro de los cambios y de quién los hizo. Vea más discusión en The Turing Way the_turing_way_community_2022_6909298. Estos son los puntos principales.

Ilustración de una rama principal

Figure 2:Ilustración de una rama principal (main branch), de The Turing Way [1].

En cada commit (confirmación), git registra los cambios. Varias personas pueden trabajar sobre el mismo archivo; el control de versiones reconoce los conflictos y ofrece opciones para resolverlos. La buena práctica mantiene la rama principal como la rama más limpia. Cree ramas adicionales para trabajar en partes específicas del proyecto.

Ilustración de una rama secundaria que se crea, recibe confirmaciones y se fusiona.

Figure 3:Ilustración de varias ramas secundarias que se crean, reciben confirmaciones y se fusionan a la rama principal. De The Turing Way [1].

¿Cuál es la diferencia entre git y GitHub?

Configurar Git

Fije su nombre de usuario y su correo:

git config --global user.name "superseismo"
git config --global user.email "superseismo@uw.edu"

Use el mismo nombre de usuario que su cuenta de GitHub, para que GitHub le atribuya sus confirmaciones. Solo necesita hacerlo una vez por computadora.

GitHub

Crear una cuenta de GitHub

Cree una cuenta de GitHub con el mismo nombre de usuario y correo que en su configuración de git. Las cuentas gratuitas incluyen repositorios públicos y privados ilimitados; los planes de pago agregan funciones de organización y de empresa que no necesitará en este curso.

Autenticación

GitHub exige autenticación de dos factores (2FA) a todos los contribuyentes — configúrela al crear la cuenta, con una aplicación de autenticación, una passkey o la aplicación GitHub Mobile. La contraseña de su cuenta nunca autentica por sí sola las operaciones de git; use una de las siguientes opciones:

Más detalles sobre la autenticación en GitHub aquí. La hoja de referencia de git es un resumen de comandos muy útil.

Obtener una copia de un repositorio existente

Hay dos maneras de trabajar a partir de un repositorio existente, y no son iguales:

Regla práctica: clone los repositorios que le pertenecen o donde tiene permiso de escritura (su repositorio MLGEO2026_UWNETID, el proyecto de su equipo); bifurque y luego clone su fork para los repositorios donde no tiene permiso de escritura (este libro, la mayoría de los proyectos de código abierto).

Crear un repositorio nuevo

Va a crear su primer repositorio. Hágalo una sola vez, con uno de los tres métodos siguientes.

Desde el navegador:

  1. Inicie sesión en GitHub. En la esquina superior derecha de cualquier página, haga clic en + y luego en New repository.
  2. Póngale nombre, elija público o privado.
  3. Marque Add a README file y elija una licencia.
  4. Haga clic en Create repository.
  5. Clónelo a su computadora: git clone https://github.com/superseismo/my-repo.git

Desde la CLI gh (un comando hace todo lo anterior):

gh repo create my-repo --public --add-readme --license mit --clone

Solo con git, cuando el código ya existe en un directorio local: cree primero un repositorio vacío en GitHub (método del navegador, pasos 1–4, sin el README) y luego

cd my-project
git init
git add .
git commit -m "first commit"
git remote add origin https://github.com/superseismo/my-project.git
git push -u origin main

Elija una ruta local fuera de carpetas sincronizadas con la nube (Dropbox, Google Drive) para ahorrarse dolores de cabeza, y abra el repositorio en VS Code o en su editor preferido. Qué pertenece a un repositorio — README, licencia, archivo CONTRIBUTING, especificación del entorno — se cubre en 1.1 Ciencia abierta y reproducible; las buenas prácticas siguen a software_carpentries_intermediate. Agregue temprano un archivo .gitignore para que los archivos de datos grandes y las salidas generadas nunca lleguen a confirmarse.

El ciclo cotidiano

En el día a día, contribuir a un repositorio es un ciclo de cuatro comandos:

  1. Actualice su copia local antes de empezar:

    git pull

  2. Edite archivos en su editor y revise qué cambió:

    git status
git diff

  3. Prepare y confirme los cambios con un mensaje descriptivo:

    git add <archivo1> <archivo2>       # o: git add .  para todos los archivos modificados
git commit -m "Su mensaje descriptivo"

    GitHub usa staging (preparación) como terminología para reunir los cambios que la próxima confirmación registrará en el servidor remoto.

  4. Empuje las confirmaciones a GitHub:

    git push

Ejemplo de flujo de trabajo

Una pasada completa por el ciclo, que termina en un pull request:

  1. Actualice y cree una rama. Parta de la rama principal al día y cree una rama de trabajo:

    git pull
git switch -c fix-readme

  2. Edite. Abra example.txt, haga sus cambios y revíselos con git diff.

  3. Prepare y confirme:

    git add example.txt
git commit -m "Clarify installation instructions"

  4. Empuje la rama a GitHub:

    git push -u origin fix-readme

  5. Abra un pull request. Haga clic en el enlace que git imprime tras el push, use el botón Compare & pull request en la página del repositorio, o ejecute:

    gh pr create

    Cuando el pull request haya sido revisado y fusionado, vuelva a la rama principal y traiga el resultado fusionado: git switch main y luego git pull.

Deshacer cambios

El git moderno separa el «deshacer» en comandos explícitos. Dos seguros y cotidianos:

Para descartar sus ediciones locales a un archivo y volver a la última versión confirmada:

git restore mycode.py

Puede encontrar git checkout y git reset HEAD <archivo> en tutoriales más viejos; git restore (para archivos) y git switch (para ramas) los reemplazaron en 2019 porque checkout hacía los dos trabajos a la vez y facilitaba los errores.

Trabajar en equipo

La rama principal debe seguir siendo la versión limpia y oficial para el público.

Pull requests con GitHub: tomado de EarthDataScience. Fuente: Earth Lab, Alana Faller

Pull requests con GitHub: tomado de EarthDataScience. Fuente: Earth Lab, Alana Faller

Issues de GitHub: use la plantilla

Issues de GitHub: use la plantilla

Más discusión aquí.

Estructura recomendada del repositorio

Estructura del repositorio

your-repo/ 
├── .github/ # GitHub-specific files (e.g., issue templates, workflows) 
│ ├── ISSUE_TEMPLATE/ # for sophisticated community package
│ ├── PULL_REQUEST_TEMPLATE.md  # for sophisticated community package
│ └── workflows/ 
│ └── ci.yml # Continuous Integration configuration, publish package, build container, test, build github-pages
├── docs/ # Documentation files 
│ ├── conf.py # Sphinx configuration file 
│ ├── index.rst # Main documentation file 
│ └── ... 
├── your_package/ # Main package directory 
│ ├── init.py # Package initialization
│ ├── module1.py # Example module 
│ ├── module2.py # Example module 
│ └── ... 
├── tests/ # Unit tests 
│ ├── init.py 
│ ├── test_module1.py # Tests for module1 
│ ├── test_module2.py # Tests for module2 
│ └── ... 
├── .gitignore # Git ignore file 
├── environment.yml # Conda environment file 
├── requirements.txt # Pip requirements file 
├── pyproject.toml # project TOML file for packaging 
├── README.md # Project README file 
├── LICENSE # License file 
└── CONTRIBUTING.md # Contribution guidelines

Explicación de archivos y directorios clave

Ejemplo de pyproject.toml

Es un estándar más nuevo, introducido por los PEP 518 y 621. Busca dar una forma unificada de especificar los requisitos de construcción y los metadatos del paquete, como parte del esfuerzo por modernizar el empaquetado en Python. Un ejemplo de pyproject.toml para empaquetar su proyecto:

[build-system]
requires = ["setuptools>=42", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "your_package"
version = "0.1.0"
description = "A brief description of your project"
readme = "README.md"
requires-python = ">=3.11"
license = {text = "MIT"}
authors = [
    {name = "Your Name", email = "your.email@example.com"}
]
dependencies = [
    "numpy",
    "pandas",
]

[project.urls]
Homepage = "https://github.com/yourusername/your-repo"

[tool.setuptools]
packages = ["your_package"]

[project.scripts]
your_command = "your_package.module:function"

Esta estructura mantiene un proyecto de Python organizado y predecible para quienes colaboran. GitHub en sí no usa directamente el archivo pyproject.toml. En cambio, puede configurar GitHub Actions para automatizar tareas como probar, construir y publicar su paquete.

Confirmaciones generadas por IA y revisión de código

Hacia 2026, buena parte del código que llega a un repositorio estudiantil fue primero borrador de un asistente de IA, a veces como una confirmación entera o un pull request abierto por el propio agente. El control de versiones es donde usted se mantiene al mando de eso. Tres reglas para este curso:

Publique su software

Si el software se usará en investigación futura y la comunidad lo citaría, publíquelo en Zenodo para obtener un DOI. Vea 1.1 Ciencia abierta y reproducible para el flujo, el licenciamiento y las prácticas de citación.

Ejercicio — ensayo: su primer pull request

Los pull requests tienen peso real en este curso: la tabla de clasificación (leaderboard) de la clase en 3.5 Clasificación multiclase califica archivos de predicción que usted envía por PR. Este ejercicio no se califica, para que su primer PR real no sea su primer PR con puntaje. Corre por completo contra su propio repositorio MLGEO2026_UWNETID (creado en 1.9), donde un error no cuesta nada.

  1. Clone su repositorio (si aún no lo hizo) y cree una rama:

    git clone https://github.com/superseismo/MLGEO2026_UWNETID.git
cd MLGEO2026_UWNETID
git switch -c hello-world

  2. Agregue una línea a README.md — por ejemplo, una oración sobre lo que quiere obtener de este curso. Revise el cambio con git diff.

  3. Confirme y empuje la rama:

    git add README.md
git commit -m "Add hello-world line to README"
git push -u origin hello-world

  4. Abra el pull request en GitHub (o con gh pr create). Escriba una oración en la descripción diciendo cuál es el cambio.

  5. Revise su propio diff en la pestaña Files changed — la misma vista que verá quien revise su envío a la tabla de clasificación. Luego fusione el PR.

  6. De vuelta en su computadora, sincronice la rama principal y borre la rama fusionada:

    git switch main
git pull
git branch -d hello-world

El éxito se ve así: su edición del README visible en la rama principal en GitHub, un PR fusionado en la pestaña Pull requests del repositorio, y una rama principal local que coincide con la remota.

Recursos adicionales

The Turing Way tiene excelentes recursos sobre control de versiones.

Footnotes

  1. the_turing_way_community_2022_6909298

    ↩↩
Capítulo 1 — El ecosistema de código abierto
1.4 Entornos de cómputo
Capítulo 1 — El ecosistema de código abierto
1.6 Galería de datos