Instrucciones de entrega

IMPORTANTE: Los métodos aquí descritos constituyen el único mecanismo de entrega válido, y es obligatorio seguir los pasos indicados para garantizar que la entrega sea aceptada.

Introducción

En esta página se explica el mecanismo de entrega para los trabajos prácticos de la materia. Los puntos clave son:

1. a cada estudiante (si el tp es individual) y a cada grupo se les asigna un repositorio privado donde realizar el trabajo y subir el código;

2. para cada trabajo, se proporcionará un rama con el esqueleto o código inicial sobre el que basar la implementación;

3. una vez completado el trabajo, la entrega se realiza desde ese mismo repositorio mediante un pull request.

Proceso

El proceso de entrega, por tanto, es:

1. Apertura de un pull request y posterior revisión.
   • Ver sección Creación de pull requests.

Índice

• Introducción
  • Repositorio
  • Sumario de instrucciones
• Creación de pull requests
  • Ramas base y compare
  • Campos a completar
  • Mecanismo de corrección
  • Reentregas y mejoras

Repositorio

Durante la cursada, se proporciona a cada estudiante/grupo un repositorio privado en la organización [fiubatps] de GitHub. Es necesario aceptar la invitación de Github para poder acceder a él.

El nombre del repositorio suele tener la forma orga_cursada_sha, por ejemplo: github.com:fiubatps/orga_2023C1_e535adfcc1ec490e. Para los trabajos prácticos en grupo se proporciona un segundo repositorio privado siguiendo el mismo esquema, por ejemplo: github.com:fiubatps/orga_2023C1_32db5b56a1cf0ec6.

Sumario de instrucciones

• El acceso a la rama principal está restringido y no se la puede modificar. Cada trabajo será publicado a un branch protegido con el nombre del taller en cuestión, por ejemplo rama gitlab para el taller de git, etc.

• El esqueleto de cada entrega se publicará en la rama remota del mismo nombre. Por tanto, para empezar a a trabajar en un tp, es suficiente con hacer git checkout -t origin/datalab.

• Se recomienda usar git push con frecuencia, para que Github actúe como copia de seguridad del trabajo. Además, para realizar consultas sobre el código, se debe subir siempre la última versión al repositorio privado. De esta manera los docentes puedan consultarlo sin que sea necesario enviarlo por correo.

Los esqueletos de los tp se van enviando a los repositorios según se acerca su fecha, por lo que al publicarse una nueva consigna, será necesario hacer git fetch para descargar el esqueleto asociado.

Creación de pull requests

Una vez terminado el trabajo, se debe crear un pull request en Github, bien visitando de manera directa https://github.com/fiubatps/orga_2024C1_<sha>/compare; bien con la opción New pull request en la pestaña Pull requests del repositorio.¹

Allí aparecerá una interfaz de creación de pull request en la que se deberá hacer tres cosas:

1. elegir la rama base (a la izquierda)
2. elegir la rama compare (a la derecha)
3. una vez elegidas, hacer click en Create pull request y completar los siguientes campos: Título, Reviewers y Assignees.

Ramas base y compare

• la rama compare (a la derecha) es siempre la rama donde se trabajó (p. ej. datalab-dev)
• la rama base (a la izquierda) no debe ser main, sino la rama de entregas asociada al trabajo (p. ej. datalab)

Campos a completar

Antes de finalizar la creación del pull request, se deben completar los siguientes campos:

• título:

  • para entregas individuales, el nombre del trabajo más el apellido, siguiendo el formato:

    1
    [orga] datalab – <apellido>
    

  • para entregas grupales, se agregan todes les integrantes, en orden alfabético, siguiendo el formato:

    1
    2
    [orga] datalab – (Aguada/Manzano)
    [orga] asmlab – (Giampietri/Straus)
    

• assignees: dado que los pull requests se crean desde una sola cuenta de GitHub, si el trabajo es grupal se debe incluir en este campo al resto de integrantes del grupo, a fin de que les lleguen las notificaciones sobre la corrección.

• reviewers: como reviewers deben asignar a la lista docente que fue informada en clase.

Mecanismo de corrección

Las entregas que poseen corrección automática deberán pasar éstas obligatoriamente. En algunos casos, luego de la corrección automática se creará un comentario indicando el resultado. El mínimo, para la aprobación, es pasar las pruebas automáticas; algunas de ellas disponibles en el repositorio, otras ocultas ya que revelan parte de la solución. En caso de no disponer de alguna prueba automática, porque la misma está oculta, el resultado de la prueba se indicará con un comentario lo suficientemente claro como para que el estudiante comprenda dónde radica el error. Si se está convencide de que el resultado de la prueba es incorrecto, comentar el PR @ arrobando al plantel docente.

Nosotres realizaremos la corrección a través del pull request creado en el paso anterior. Así, le docente asignade revisará el código y realizará las correcciones y comentarios oportunos. Estos comentarios se recibirán por correo electrónico, y se podrán consultar también a través de las interfaces web de GitHub y (en su caso) Reviewable. Se recomienda la lectura de la corrección a través de las interfaces web, pues:

• aparecerán los comentarios junto con el código a que estos se refieren (en otras palabras, los comentarios aparecerán con el contexto exacto en que se realizaron)

• se podrá contestar a los comentarios de manera directa desde la interfaz web, lo cual permite saber con exactitud a qué comentario o corrección se refiere cada respuesta (cosa que no ocurre con igual facilidad por correo)

Junto con los comentarios, la corrección recibida indicará claramente:

• si el TP está aprobado o no;
• en caso de no estar aprobado, qué cambios es imprescindible realizar para poder aprobarlo;
• en caso de estar aprobado, si el corrector aceptaría cambios adicionales para mejorar la nota, y cuáles son estos cambios.

En caso de no estar claro qué es lo que se está pidiendo, se puede pedir una aclaración con el mecanismo de respuestas en el propio pull request, descrito arriba.

Reviewable

Algunos docentes utilizan Reviewable para revisar el código, en lugar de la interfaz de GitHub. En ese caso, se recomienda leer las correcciones en el sitio web de Reviewable, y no a través de GitHub (pues no aparecerían los comentarios con todo el contexto necesario). Para acceder a Reviewable, no es necesario crear una cuenta; es suficiente con usar la opción Sign in with GitHub.

Asimismo, los comentarios de Reviewable tienen un concepto de “prioridad” (o disposition, en inglés). En general, el significado en las correcciones de la materia es:

• blocking (marcados con el ícono de prohibición ): si el TP no está aprobado, se debe corregir este ítem para poder aprobar; si está aprobado, para subir la nota se deben corregir TODOS los ítems marcados de esta manera.

• discussing (marcados con el círculo vacío ): el ítem merece la pena ser corregido, pero no es obligatorio hacerlo.

• informing (marcados con el ícono de información ): corrección menor o informativa.

Reentregas y mejoras

En caso de realizarse cambios (para aprobar o para subir nota), estos deben enviarse vía el mismo pull request que fue creado para la entrega, y no a a través de uno nuevo. Una vez enviados los cambios, se deben hacer dos cosas:

1. Revisar la lista completa de comentarios realizados por el docente, y responder a los mismos indicando si se realizaron los cambios solicitados (en los casos más triviales es suficiente con responder Done o Hecho; Reviewable proporciona un botón para esto); si corresponde, responder también a cualquier pregunta que hubiera hecho el docente, e indicar qué decisiones se tomaron en la (re-)implementación.²

   • En el caso de Reviewable, es importante que no queden “pending conversations”, esto es, que al enviar los comentarios, Reviewable no diga “waiting on … nombre de le alumne”.

2. Una vez respondidos los comentarios, hacer explícito en el pull request que éste está listo para ser revisado de nuevo. Esto se puede hacer al tiempo que se envían los comentarios, incluyendo el acrónimo PTAL en la respuesta (estándar en la industria anglosajona con significado Please take another look).

   Como alternativa, este paso también se puede realizar vía la interfaz de GitHub, con el ícono de solicitud de revisión (dos flechas en círculo ) que aparece al lado del campo Reviewer.

Como comentario final, es especialmente importante realizar las correcciones con gran atención al detalle, para que no suceda que una reentrega empeora la situación (esto es, que en una reentrega dejen de funcionar aspectos que sí funcionaban antes).