P0 · Primer aporte

Publicado: semana 1 · Entrega: semana 3 · Individual

En un equipo de software casi nadie escribe un programa desde cero: llega a un código que ya existe, toma un issue, lo resuelve en una rama, lo prueba y lo propone en un pull request que otra persona revisa. En esta entrega van a hacer exactamente eso, una vez y con calma, sobre Kallpa, la aplicación de reservas del complejo deportivo que usamos en los laboratorios (kallpa/, con su README).

Cada estudiante resuelve un issue en su propia copia de Kallpa, con pruebas, y abre un pull request que revisa un compañero o compañera. También revisan el pull request de otra persona. No hace falta saber TypeScript de antemano: los cambios son pequeños (de una a tres horas de trabajo) y el código de Kallpa sirve de ejemplo.

Qué issue les toca

Tomen los dos últimos dígitos de su código de estudiante, divídanlos entre 8 y súmenle 1 al residuo. Por ejemplo, con el código 20231234A los dos últimos dígitos son 34; 34 entre 8 deja residuo 2; les toca el issue 03.

Residuo	Issue	Tipo
0	01 · Los feriados se cobran como fin de semana	funcionalidad
1	02 · La disponibilidad de una cancha que no existe	bug
2	03 · Con dos reservas seguidas se pasa el límite de 3 horas	bug
3	04 · Registrar vecinos desde la API	funcionalidad
4	05 · Filtrar las canchas por deporte	funcionalidad
5	06 · Kallpa acepta reservas para el 30 de febrero	bug
6	07 · Los domingos atendemos de 8:00 a 20:00	funcionalidad
7	08 · Decir cuánto se devuelve cuando se cancela	funcionalidad

Cada issue está escrito como lo escribiría la administración del complejo en GitHub: el contexto, lo que se espera y los criterios de aceptación en la forma Dado… cuando… entonces… (Given/When/Then). Cada criterio es una de las pruebas de aceptación de tests/issue-NN.test.ts.

Revisión: cada uno revisa el pull request de la persona que le sigue en la lista del curso (la última persona revisa a la primera). Si esa persona tiene el mismo issue que ustedes, revisen el de la siguiente.

Paso a paso

1. Su repositorio de Kallpa

Abran el contenedor desde la carpeta del repositorio del curso (./env/run.sh): dentro, el curso está en /work. Copien Kallpa a una carpeta propia y conviértanla en un repositorio de Git:

cp -r /work/kallpa /work/kallpa-su-usuario
cd /work/kallpa-su-usuario
git init
git add -A
git commit -m "Versión inicial de Kallpa"
make check                      # tiene que pasar antes de cambiar nada

En la terminal de su computadora (donde tienen sus credenciales de GitHub), desde esa misma carpeta, creen el repositorio en GitHub y suban main:

gh repo create kallpa-su-usuario --private --source=. --push

En GitHub, en Settings → Collaborators, agreguen a la persona que los va a revisar y al docente.

2. El issue en GitHub

Creen el issue en su repositorio con el texto del enunciado, para poder enlazarlo desde el pull request:

gh issue create --title "Los feriados se cobran como fin de semana" --body-file /ruta/al/curso/projects/p0-primer-aporte/issues/01-feriados.md

(o cópienlo a mano en la página del repositorio).

3. Una rama con el nombre del cambio

git switch -c feriados-tarifa

El nombre dice qué cambia (feriados-tarifa, filtro-deporte, horario-domingo), no quién lo hace ni el número del issue.

4. Entender, probar, cambiar

Lean el README de Kallpa (las reglas y la API) y el código que menciona el issue. Levanten el servidor (make start) y reproduzcan el problema con curl o en la página.
Escriban primero una prueba que falle y que muestre el problema o la funcionalidad que falta, en test/ (un archivo nuevo o uno que ya existe). Las pruebas de aceptación del curso no cuentan como suyas: tienen que agregar las propias.
Hagan el cambio más pequeño que cumpla los criterios de aceptación. Sigan el estilo del código que ya existe y la guía de estilo.
Si cambia una regla del negocio o la API, actualicen el README de Kallpa.
Corran make check ISSUE=NN (sección siguiente) hasta que todo pase.

Hagan al menos 2 commits que tengan sentido por separado (por ejemplo, “Agrega pruebas de tarifa en feriados” y “Cobra los feriados como fin de semana”). El resumen de cada commit va en imperativo y es corto (unos 60 caracteres; la revisión automática rechaza más de 72); si hace falta explicar el porqué, va en el cuerpo, después de una línea en blanco.

5. El pull request

Suban la rama (en la terminal de su computadora: git push -u origin feriados-tarifa) y abran un pull request hacia main (gh pr create o en GitHub). La descripción tiene:

Qué cambia y por qué, en dos o tres frases, y Closes #1 (el número de su issue) para enlazarlo.
Cómo se verificó: qué pruebas agregaron y la salida de make check ISSUE=NN.
Qué debería mirar quien revisa: una decisión que tomaron y que podría ser discutible, o una duda.

Pidan la revisión a su compañero o compañera (Reviewers en GitHub).

6. La revisión, en los dos sentidos

Como autor. Respondan cada comentario: con un commit nuevo que lo resuelve (y digan cuál) o explicando por qué no lo cambian. No reescriban la historia de la rama después de la revisión (nada de git push --force): quien revisa tiene que poder ver qué cambió desde su comentario.

Como revisor. Lean el issue antes que el código. Bajen la rama y corran make check ISSUE=NN. Dejen al menos dos comentarios en líneas concretas (algo que no se entiende, un caso que falta probar, un nombre que confunde), con una sugerencia cuando puedan. Terminen con Approve o Request changes, y digan por qué.

Entreguen al docente el enlace del pull request. No hagan merge hasta que el docente haya revisado la entrega: la revisión automática compara la rama con main, y después del merge ya no hay diferencia que revisar.

Lo que revisa `make check ISSUE=NN`

Desde la carpeta de su repositorio, en el contenedor:

make check ISSUE=03

El Makefile de Kallpa llama a check.sh de esta carpeta (lo busca en /work/projects/p0-primer-aporte; si tienen el curso en otro lugar, agreguen P0_DIR=<ruta>). Las pruebas corren sobre una copia de su repositorio, así que no se agrega ningún archivo a su carpeta. Esto es lo que revisa y qué hacer si falla:

Revisión	Si falla
Están en una rama que no es `main`	Hicieron los cambios en `main`. Creen la rama ahí mismo (`git switch -c <rama>`); `main` se arregla después con ayuda del docente.
La rama tiene al menos 2 commits propios (sin contar merges)	Separen el trabajo en pasos. Los commits que ya estaban en `main` no cuentan.
Ningún resumen de commit pasa de 72 caracteres	El mensaje dice cuál. El último se corrige con `git commit --amend`; los anteriores, con `git rebase -i main` (antes de subir la rama).
La rama agrega o cambia un `test/*.test.ts`	Falta su prueba propia.
Tipos (`tsc`)	Un error de tipos. `tsc` revisa también las pruebas del issue: si cambiaron algo que esas pruebas usan, como `test/helpers.ts` o los datos de ejemplo, vuelvan a dejarlo como estaba.
Linter (`eslint`)	Lo que marque ESLint; `make lint` lo muestra.
Pruebas de Kallpa	Su cambio rompió algo que ya funcionaba, o una prueba suya falla. El mensaje de `assert` dice qué se esperaba y qué llegó.
Pruebas de aceptación del issue	Algún criterio no se cumple. El nombre de la prueba dice cuál.

Además da dos avisos, que no hacen fallar la revisión: si hay cambios sin commit (la revisión del docente usa solo lo que subieron) y si la rama toca archivos fuera de src/, test/, public/ y README.md (quien revise va a preguntar por qué son parte del cambio).

Las pruebas de aceptación usan solo la API HTTP, a través de test/helpers.ts: pueden organizar el código como les parezca mejor, siempre que la API responda lo que pide el issue.

Las reglas del curso sobre integridad y uso de herramientas (SYLLABUS, secciones 7 y 8) valen también aquí. En la semana 3, cualquiera puede tener que explicar su cambio línea por línea.

Errores comunes

Cambiar los datos de ejemplo (src/store/seed.ts) o test/helpers.ts para que una prueba pase: las pruebas de aceptación cuentan con ellos.
Arreglar de paso otras cosas que encontraron. Anótenlas como issues nuevos en su repositorio; un pull request, un cambio.
Un solo commit enorme con todo y luego “Corrige pruebas”. Cada commit tiene que dejar el código en un estado que se entienda.
Responder a la revisión con un “listo” sin decir qué cambió.