Skip to content

Latest commit

 

History

History
108 lines (93 loc) · 7.05 KB

setup.md

File metadata and controls

108 lines (93 loc) · 7.05 KB
Raw

Instrucciones de uso

El objetivo de este portafolio es que el estudiante aprenda a utilizar Git y posea material demostrable de las habilidades aprendidas en el curso. Las instrucciones se dividen en la configuración del repositorio personal, configuración del repositorio del curso y en un flujo típico a lo largo del semestre.

En particular, se debe configurar Binder con tal de poder ejecutar el código del estudiante desde cualquier computador sin la necesidad de descargar, por eso es necesario que al subir los laboratorios, tareas o proyectos estos se suban en conjunto a los datos necesarios.

Configuración inicial para el curso

  1. Crear cuenta de GitHub aquí.
    • Es recomendable aprovechar el correo UTFSM y reclamar el Student Pack de GitHub. Uno de sus beneficios es acceder a una membresía Pro y así tener repositorios privados.
  2. Instalar Git.
    • En Windows lo ideal sería instalar Git for Windows.
    • También existe una alternativa con interfaz gráfica, GitHub Desktop pero no es recomendable, pues uno de los objetivos del curso es aprender los fundamentos de Git.
  3. Configurar tu forma de acceder a GitHub. Recomendaciones.
    • Recomendado pero menos seguro: HTTPS
      • Te podría ser útil configurar credential helper para recordar tu usuario en tu computador.
    • Más engorroso pero más seguro: SSH
  4. Ir al repositorio mat281_portfolio_template y presionar el botón Use this template.
  5. Nombar el nuevo repositorio como mat281_portfolio y dejarlo en modo público.
  6. Se recomienda crear un directorio en el computador personal para repositorios de Git. Por ejemplo en ~/Documents/git/.
  7. Clonar el repositorio recién creado. Dependiendo de tu configuración de Git, reemplazar {username} por el nombre de usuario personal de GitHub uno de los siguientes comandos en la terminal (usuarios de Windows probablemente tengan que utilizar Git Shell.)
    • HTTPS: git clone https://github.com/{GITHUB_USER}/mat281_portfolio.git
    • SSH: git clone git@github.com:{GITHUB_USER}/mat281_portfolio.git
  8. En el archivo README.md editar los campos personales:
    • Línea 14: [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/{GITHUT_USER}/mat281_portfolio/master?urlpath=lab) donde deber cambiar {GITHUB_USER} por tu usuario de GitHub.
    • Línea 16: Nombre y si se desea algún link a perfil profesional, por ejemplo Linkedin o GitHub.

Configurar repositorio del curso

  1. Clonar el repositorio del curso (no puede estar dentro de la carpeta de tu portafolio) ejecutando: git clone https://github.com/{TEACHER_GH_USER}/mat281_{PERIOD}.git donde {TEACHER_GH_USER} es el usuario del profesor a cargo del curso y {PERIOD} es el año-semestre en que se dictó. Por ejemplo, para el segundo semestre de 2019 los valores son aoguedao y 2019S2 respectivamente.
  2. En el transcurso del semestre, para actualizar se debe ejecutar git pull en la terminal dentro del directorio del repositorio. Por ejemplo, si el repositorio está en la ruta ~/Documents/git/mat281_2019S2:
    • cd ~/Documents/git/mat281_2019S2
    • git pull
    • ¡IMPORTANTE! Para no tener problemas al pullear no deben existir conflictos con el repositorio original, la mejor forma de evitar esto es no editar ningún archivo y realizar todos los laboratorios/tareas/etc. en el repositorio personal del curso.

Flujo típico de uso

  1. Al comenzar el semestre creaste y clonaste tu repositorio personal del curso y clonaste el repositorio oficial del curso. Deberías tener estructura de directorios similar a esta: 
    - your_git_folder
|
|- mat281_2019S2
|  |
|  |- ...
|
|- mat281_portfolio
    |
    |- ...
  2. Al comenzar cada clase actualizas el contenido en el respositorio oficial del curso, es decir, ejecutas git pull dentro de la carpeta mat281_2019S2.
  3. Copia el archivo ipynb del laboratorio y pégalo en la carpeta mat281_portfolio\labs.
  4. Abrir desde jupyter lab el archivo correspondiente a la clase que se encuentre en el repositorio personal.
  5. Realiza el laboratorio, tarea o proyecto y guarda los cambios.
  6. Agregar, commitear y pushear los cambios, lo típico sería: 
    cd ~/Documents/git/mat281_portfolio
git add lab_xx.ipynb any_other_file
git commit -m "Laboratorio xx."
git push origin master
    Con esto se verán reflejados los cambios en tu cuenta de GitHub.

Verifica que todo funcione correctamente!

Después de cada commit, prueba que Binder está bien configurado, ya que Binder necesita realizar una nueva imagen/contenedor de tu repositorio. Además, durante el curso se han instalado librerías o actualizado otras, por lo que debes editar el archivo binder/environment.yml de tu respostorio.

Ejemplo:

  • Pusheaste la tarea del módulo de análisis datos (m02_homework)
  • Vas a tu repositorio y ejecutas Binder haciendo click en el icono de Binder configurado anteriormente.
  • Se va a tardar un par de minutos en crear la nueva imagen y lanzar la instancia de Jupyter Lab (NO Jupyter Notebook!).
  • Al estar lista la instancia de Jupyter Lab, abre el notebook m02_homework.ipynb que debe estar en la carpeta m02_data_analysis/m02_homework.
  • Haz click en Kernel -> Restart Kernel and Run All Cells.
  • Si al ejecutar from PIL import Image te arroja el error ModuleNotFoundError: No module named 'PIL' es porque no agregaste pillow a tu archivo environment.yml
    • Recuerda que las librerías instaladas en tu computador personal no se traspasan mágicamente a la instancia de Binder en tu repositorio, debes especificar las librerías en el famoso archivo environment.yml.
  • En el caso que se te presente el caso anterior debes agregar la dependencia pillow y environment.yml te quedaría algo como esto:
name: mat281
channels:
  - conda-forge
  - defaults
dependencies:
  - altair=3
  - jupyterlab=1.0.9
  - matplotlib=3.1.1
  - nodejs=12.8
  - numpy=1.17.0
  - pandas=0.25.1
  - pandas-profiling=2.3.0
  - pip
  - pillow=6.2.1
  - python=3.7
  - scikit-learn=0.21.3
  - scipy=1.3.1
  - seaborn=0.9.0
  - pip:
    - datachile
  • Luego vuelves a hacer un push con este cambio.
  • Levantas la instancia de Binder en tu repostorio y vuelves a probar a ejectuar todas las celdas de m02_homework.ipynb.
  • Repite el proceso hasta que todos tus entregables no tengan problema.

Finalmente, recuerda que la estructura de las carpetas es importante, así como los archivos que están en tu repositorio. Mostrar orden y pulcridad demuestra profesionalismo y seriedad. Recuerden que este repositorio será su carta de presentación el día de mañana.