40  Realiza un curso con GitHub

Este contenido es bastante obsoleto y es poco probable que se desarrolle más.

GitHub es una plataforma maravillosa para impartir un curso. He estado haciendo esto en github.com desde 2014 en STAT 545, un curso de posgrado de 80 estudiantes en análisis de datos con R, y en un segundo gran curso de posgrado con uso intensivo de código en genómica estadística. Estamos ejecutando todos los cursos para el programa de Maestría en Ciencia de Datos de la UBC desde una instancia privada de GitHub Enterprise alojado en Canadá.

40.1 Beneficios

Para el instructor

  • Si ya usa Git/GitHub, es extremadamente eficiente usar los mismos flujos de trabajo para administrar los materiales del curso, el trabajo de los estudiantes y la comunicación con los estudiantes y los asistentes técnicos.
    • Cuando cambié a Git/GitHub y R Markdown, ¿abandoné mi antiguo “sistema” de aceptar todo tipo de cosas como archivos adjuntos de correo electrónico? Fue la primera vez que ejecuté el código en los proyectos finales de mis alumnos, porque fue muy fácil tenerlo en mi computadora de manera organizada. ¡Incluso hice algunas correcciones como solicitudes de cambio!
  • Si todavía estás en tus inicios con Git/GitHub, el gran volumen de operaciones y los plazos pequeños y regulares aumentarán tu dominio muy rápidamente. ¡La práctica hace la perfección! Sin embargo, no recomendaría realizar un curso en GitHub como su primer proyecto sustancial de control de versiones.

Para los estudiantes

  • He descubierto que los estudiantes se adaptan a Git/GitHub con bastante rapidez y realmente les gusta. Les resulta gratificante ver sus hermosos y ricos informes R Markdown en Internet. Como es fácil exponer su trabajo dentro de la clase, hacemos mucha revisión por pares. Encuentro que la experiencia se propaga por la clase como un virus. Esto se aplica tanto al contenido del plato principal como al flujo de trabajo.
  • Muchos estudiantes están específicamente interesados en aprender Git y GitHub, como complemento a las habilidades analíticas y de codificación que enseñamos en estos cursos. El hecho de que lo utilicemos para mecánica de curso mata dos pájaros de un tiro. Enseñar el uso del control de versiones distribuidas es un objetivo pedagógico válido en sí mismo.

40.2 La configuración del estudiante STAT 545

Las organizaciones/equipos y la API de GitHub han cambiado a lo largo de los más de 3 años que llevamos haciendo esto, por lo que mi enfoque ha evolucionado con el tiempo y también está moldeado por una dura experiencia.

Puntos principales:

  • Crear una organización para el curso.
    • Solicite inmediatamente un descuento educativo para la Organización, de modo que pueda obtener repositorios privados ilimitados.
  • Haga que sus estudiantes se registren de forma gratuita y personal cuentas GitHub.
    • Anímelos a solicitar un descuento educativo en su propio nombre (también conocido como “paquete de desarrollador para estudiantes”). Pero tenga la seguridad de que nada de lo que necesita para la maquinaria de su curso dependerá de esto.
  • Obtenga los nombres de usuario de GitHub de sus estudiantes: utilizamos una aplicación Shiny! - además de algo de información que le permite vincularlos a su lista oficial de cursos.
  • Cree un equipo de estudiantes y un equipo de asistencia técnica. Hago estos equipos para cada ejecución del curso, p.e. 2016_estudiantes y 2016_ap.
  • Invite a los estudiantes a unirse a la organización de su curso y al equipo de estudiantes. Lo mismo ocurre con los TA y el equipo de TA.
  • Cree un nombre canónico para cada estudiante, basado en la lista oficial de cursos, es decir, apellido_nombre.
  • Cree un repositorio para cada estudiante, utilizando el nombre canónico del estudiante.
    • Este es un repositorio privado dentro de la organización del curso.
    • Apago los wikis y dejo que GitHub se inicialice automáticamente o inserte inmediatamente archivos, incluido un archivo README, en los repositorios.
    • Dar al equipo de estudiantes acceso de lectura o extracción al repositorio de cada estudiante. Sí, esto les permite verse trabajar unos a otros. Hablo de esto en otro lugar.
    • Proporcionar al equipo de asistencia técnica acceso por escritura o inserción al repositorio de cada estudiante.
    • Agregar al alumno como colaborador con acceso de escritura o push.
    • ¡Deja de mirar estos repositorios personalmente! Vaya que notificación.

¡Esa es la configuración! Utilizo los paquetes gh y purrr para programar todo esto API de GitHub funciona. En una segunda ola, publicaré fragmentos de código para las operaciones anteriores.

Lo que NO debes hacer (voz de la experiencia, aquí):

NO permita que los estudiantes creen sus propios repositorios.

  • Tendrás una convención de nomenclatura y ellos nunca, jamás, la seguirán.
  • Debes tener derechos de administrador sobre el repositorio de cursos, para poder manipularlo a voluntad a través de la API de GitHub. Les pedirás que te agreguen a ti y a los TA como colaboradores, pero no todos lograrán ejecutar esta tarea.
  • Querrá realizar varias operaciones masivas en los repositorios y su trabajo de API será más simple si los repositorios pertenecen a la misma organización en lugar de recorrer repositorios con nombres aleatorios propiedad de personas aleatorias, sujeto a sus caprichos.

40.3 El flujo de tareas

En clase, los estudiantes toman posesión de sus repositorios, desde RStudio vía File > New Project. Hacen la mayor parte de su trabajo de curso aquí: es un directorio en su computadora, un repositorio de Git asociado con el control remoto de GitHub y un proyecto RStudio.

Normalmente, la tarea se realiza en R Markdown, utilizando el formato de salida github_document. Confirman y envían .Rmd, .md y cualquier archivo necesario, como cifras.

La tarea se envía abriendo una edición:

  • El nombre del problema es “Marcar tarea x de apellido_primer nombre”. Bueno, en realidad no, pero puedo soñar.
  • El cuerpo debe contener el SHA de su última confirmación, etiquetas para el TA de marcado o el equipo de TA y, idealmente, enlaces a los archivos que se van a marcar.

Los asistentes técnicos dejan comentarios aquí. Las marcas reales se almacenan en otro lugar y se distribuyen por correo electrónico. Como marcan las AT, cierran los temas.

Después de enviar la tarea, asignamos aleatoriamente a cada estudiante para que revise el trabajo de dos compañeros. Cada tarea de revisión por pares toma la forma de un problema, asignado al revisor. Los estudiantes dejan comentarios unos a otros aquí. Como marcan los AT, leen y evalúan estas revisiones por pares (¡también puntuadas!) y cierran los temas.

40.4 GitHub como sistema de gestión de cursos

2017-05-29 Esta sección fue eliminada de un artículo que estoy escribiendo. Es parcialmente redundante con lo anterior y los dos se fusionarán.

STAT 545 es un curso de análisis y discusión de datos en la Universidad de Columbia Británica. Fui el instructor a cargo durante varios años, lo que coincidió con mi propia adopción de Git/GitHub. GitHub se utiliza para gestionar el desarrollo del material del curso, servir al sitio web del curso, crear un foro de discusión y alojar todo el trabajo enviado por los estudiantes.

Dado que los estudiantes deben enviar su trabajo y proporcionar una revisión por pares del trabajo de otros a través de GitHub, el uso del control de versiones alojado es una parte explícita, aunque modesta, del curso. El sitio web Happy Git y GitHub para el usuario contiene nuestras instrucciones probadas en batalla para la configuración y el uso inicial. Los estudiantes alcanzan las competencias básicas con bastante rapidez y les resulta gratificante ver sus informes R Markdown formateados y ricos en cifras en Internet. Dado que es fácil exponer su trabajo dentro de la clase, llevamos a cabo una revisión por pares, lo que ayuda a que la experiencia se difunda rápidamente en todo el grupo.

40.4.1 Utilice una organización GitHub

Organizaciones de GitHub son “cuentas compartidas donde grupos de personas pueden colaborar en muchos proyectos a la vez”. Esta es la estructura más adecuada para administrar los recursos del curso, ya que puedo otorgar a los asistentes técnicos y a los estudiantes diferentes niveles de acceso a varios repositorios. El acceso se puede controlar a nivel de usuario individual o, más convenientemente, para equipos completos. El equipo de asistencia técnica comparte conmigo acceso de escritura en un repositorio privado para asuntos internos. Proporciono a cada estudiante su propio repositorio privado para el trabajo del curso y otorgo acceso de lectura a otros miembros del equipo de estudiantes, para facilitar la revisión por pares. Existe un repositorio público que sustenta el sitio web del curso (ver más abajo). Tenemos otro repositorio público que existe únicamente para que los Problemas puedan usarse como foro de discusión.

GitHub fomenta activamente el uso de su plataforma en la enseñanza. Como instructor, puede solicitar una cuenta de organización gratuita que proporciona funciones que normalmente solo están disponibles en planes pagos, como repositorios privados. De hecho, GitHub proporciona herramientas para flujos de trabajo de enseñanza específicos a través de GitHub Classroom, aunque yo no las uso. Esto no es un golpe intencional a sus herramientas. Comencé a enseñar con GitHub varios años antes de que esto existiera y desarrollé una forma diferente de usar la plataforma. También encuentro que los recursos de GitHub Education están más orientados a la informática que a la ciencia de datos.

40.4.2 Páginas de GitHub para el sitio web del curso

Todo el contenido del curso se proporciona en el sitio web de STAT 545. Cada página se genera a partir de un documento R Markdown que se representa en HTML localmente utilizando el paquete rmarkdown, conservando el Markdown intermedio. Estas páginas son una mezcla de prosa y código R renderizado, lo que refleja la codificación en vivo realizada en clase. Todos estos archivos y su historial se pueden explorar en el repositorio de origen. El equipo de asistencia técnica tiene permiso para escribir en este repositorio, lo que significa que pueden (¡y lo hacen!) ayudarme a mantener el sitio web. Me alegro de no ser más el webmaster. También recibimos correcciones de errores tipográficos y otras aportaciones del mundo en general, ya que esto es completamente público.

Si hoy comenzara desde cero, continuaría usando R Markdown, RStudio y GitHub Pages (ver más abajo), pero actualizaría a un enfoque más moderno y automatizado para representar las páginas. Ahora recomiendo sitios web de R Markdown, bookdown o blogdown para gestionar el proceso de creación de un sitio web estático a partir de un conjunto grande e interrelacionado de archivos .Rmd.

GitHub ofrece varias formas de alojar un sitio web directamente desde un repositorio, conocido colectivamente como Páginas de GitHub. El sitio web STAT 545 es una Página de organización muy simple que utiliza un dominio personalizado, stat545.com, en lugar del valor predeterminado orgname.github.io.

Este sistema para gestionar el contenido del curso es un gran ejemplo de cómo integrar la realización del trabajo y su intercambio. Analizamos datos en vivo en clase, usando R, basándonos en los scripts del sitio web. Vuelvo a renderizar el .R o .Rmd asociado, confirmo los archivos modificados, los envío y lo veo reflejado de inmediato en http://stat545.com. No existe separación entre tener una idea, implementarla y publicarla en el sitio web.

40.4.3 Repositorios privados específicos para estudiantes

Al principio del curso, obtengo nombres de usuario de GitHub para los estudiantes registrados, a través de una aplicación Shiny, y los invito a unirse a la organización del curso. Luego creo un repositorio privado por estudiante, en la Organización STAT 545. El estudiante objetivo tiene acceso de escritura y los demás estudiantes tienen acceso de lectura. Esto es algo controvertido, debido a la posibilidad de hacer trampa, pero he visto más ventajas que desventajas en esta configuración, en el contexto de STAT 545. En otras configuraciones, también he usado un repositorio por estudiante por tarea, lo que le permite mantener los repositorios completamente privados hasta la entrega de la tarea y luego aumentar su visibilidad durante la calificación y la revisión por pares. Algunos cursos funcionarán mejor con un modelo u otro.

Cada estudiante hace su trabajo en este repositorio y envía una tarea importante aproximadamente una vez por semana. La primera tarea es simplemente reclamar el repositorio y crear un archivo README, lo que demuestra que tienen toda la configuración de software relevante y que pueden escribir un poco de Markdown. Cada semana abordamos algún nuevo análisis de datos o una tarea de discusión, con un margen cada vez mayor para la independencia. La tarea se implementa en documentos de R Markdown, se representa en Markdown y se envía a GitHub. Los estudiantes envían su trabajo abriendo una incidencia en su repositorio, nombrando la tarea en el título, proporcionando el SHA de la confirmación final asociada y vinculándolo al archivo principal .md. Dejamos comentarios en el hilo del problema o, ocasionalmente, proponemos cambios en el código mediante “solicitudes de cambio”. Se seleccionan dos pares al azar para revisar cada tarea, un proceso que también implementamos a través de GitHub Issues.

Al final del trimestre, el estudiante (¡y su instructor!) pueden visitar el repositorio para encontrar una secuencia organizada y navegable de ~10 tareas. Cada estudiante se marcha con documentación escrita por él mismo de todo lo que ha hecho, lista para consultar en futuros proyectos. Las últimas asignaciones requieren escribir un paquete R o una aplicación Shiny, lo que generalmente hacen en repositorios públicos bajo sus propias cuentas. Terminan STAT 545 con varios meses de experiencia en Git/GitHub y el inicio de una cartera de ciencia de datos.