Instrucciones de entrega

AVISO: Se actualizó el documento para 2021a.

Introducción

En esta página se explica el mecanismo de entrega para los labs y TPs de la materia. Los puntos clave son:

1. a cada estudiante y a cada grupo se les asigna un repositorio privado donde realizar el trabajo y subir el código;

2. para cada lab o TP, 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, se descompone en dos partes.

1. Envío del código al repositorio privado.
   • Ver sección Envío del código.
2. Apertura de un pull request y posterior revisión.
   • Ver sección Creación de pull requests.

La segunda parte es siempre igual, y las instrucciones que se dan son, por el momento, únicas. Para la primera parte, sin embargo, se ofrecen instrucciones según el “nivel de destreza” con Git:

• a quien ya se maneje de manera cómoda con Git y Github debería serle suficiente con leer la sección Sumario de instrucciones;

• quien —por falta de conocimientos o tiempo— prefiera ceñirse a lo imprescindible, puede consultar la sección Modalidad de envío web;

• para quien se encuentre a mitad de camino entre ambas opciones, y quiera avanzar en su aprendizaje de la herramienta, se incluye al final del documento la sección Instrucciones detalladas, con una descripción de los pasos del proceso.

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

Índice

• Introducción
• Envío del código
  • Repositorio
  • Sumario de instrucciones
  • Modalidad de envío web
• Creación de pull requests
  • Ramas base y compare
  • Campos a completar
  • Mecanismo de corrección
  • Reentregas y mejoras
• Instrucciones detalladas

Envío del código

En esta sección se ofrecen unas instrucciones resumidas para la entrega, así como una guía para realizar las entregas vía web. Al final de un documento se incluyen las Instrucciones detalladas del proceso.

Repositorio

Durante la cursada, se proporciona a cada estudiante 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_año_usuario, por ejemplo: github.com:fiubatps/orga_2021a_pamoreno. Para los trabajos prácticos en grupo se proporciona un segundo repositorio privado siguiendo el esquema orga_año_numgrupo_usuarios, por ejemplo: github.com:fiubatps/orga_2021a_g0_pamoreno_xcancerberox.

Sumario de instrucciones

• El acceso a la rama principal está restringido y no se la puede modificar. Cada lab o trabajo práctico debe desarrollase en una rama separada, con el nombre exacto de ese lab o TP (por ejemplo, rama lab1 para el lab1, etc.).

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

• 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.

Modalidad de envío web

Para esta materia es posible el envío de código a través del navegador visitando el repositorio en Github.com. Esto es posible porque no se requieren integraciones (git merge) entre los distintos labs y TPs. Para ello, se pueden seguir estos pasos:

1. Abrir el repositorio, que por omisión se encontrará en la rama main:

   

2. Cambiar a la rama de la entrega, por ejemplo, lab1:

   

3. Entrar en el directorio asociado a la entrega, marcado con una flecha en la imagen anterior; en ese directorio aparecerán los archivos del esqueleto y un botón Upload files:

   

4. Al hacer click en Upload files, se abre una interfaz para agregar archivos a ese directorio del repositorio. Una vez elegidos los archivos, se debe escribir un breve mensaje y hacer click en Commit changes para registrar los cambios en el repositorio. (El mismo procedimiento se puede seguir para subir nuevas versiones del código.)

   Importante: se debe obligatoriamente crear el commit en la misma rama, y no en otra (ver la imagen que sigue).

   

Creación de pull requests

Una vez terminado el lab o TP, se debe crear un pull request en Github, bien visitando de manera directa https://github.com/fiubatps/orga_<año>_<usuario>/compare; bien con la opción New pull request en la pestaña Pull requests del repositorio.²

documentación de GitHub, About pull requests, o en castellano: Acerca de las solicitudes de extracción.

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. lab1)
• la rama base (a la izquierda) no debe ser master, sino la rama de entregas asociada al lab o TP (p. ej. entrega_lab1)

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 lab más el apellido, siguiendo el formato:

    1
    2
    [orga] lab1 – Moreno
    [orga] lab2 – Simó
    

  • para entregas grupales, se agrega el número de grupo a los apellidos, siguiendo el formato:

    1
    2
    [orga] tp1 – g10 (Aguada/Manzano)
    [orga] tp2 – g11 (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 reviewer deben asignar a @orga-21a, quien la podrá reasignar a otros docentes del curso.

Mecanismo de corrección

La corrección se realizará a través del pull request creado en el paso anterior. Así, el docente asignado 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).

Instrucciones detalladas

Próximamente.