El material de esta materia es abierto, lo cual quiere decir que cualquier persona puede usarlo para sus propios fines pedagógicos, y colaborativo, con lo cual contribuciones de alumnos son bienvenidas. Eso significa que los estudiantes también pueden ayudar a mejorarlo.
Te invitamos a contribuir en cualquiera de los siguientes casos:
🔤 Errores de tipeo u ortográficos
🔗 Links que no funcionan
📖 Explicaciones poco claras o incorrectas
💻 Código que no funciona
➕ Material adicional que sería útil
¿Por qué fomentar contribuciones?¶
Además de mejorar el material del curso, esto también es una buena forma de practicar el workflow de colaboración con Git y GitHub, que es una herramienta clave en computación científica. Este curso intenta acercarse a la forma en que realmente se produce conocimiento científico y software:
🤝 Trabajo colaborativo
🔍 Revisión por pares
🔄 Mejora continua del material
Incluso pequeñas correcciones ayudan muchísimo a mejorar el curso para todos los estudiantes e interesados. Además, tu nombre quedará para siempre en el repositorio del curso por haber contribuido y aportado cambios al mismo.
Reportar un problema (Issue)¶
Si encontrás un problema o querés sugerir una mejora, lo más simple es abrir un issue en GitHub. Un issue sirve para reportar errores, proponer mejoras, hacer preguntas sobre el material y discutir cambios antes de implementarlos.
Proponer cambios al material (Pull Request)¶
Si querés corregir o mejorar directamente el contenido del curso, podés enviar un Pull Request (PR). Un Pull Request propone cambios al repositorio original y permite que el instructor revise el cambio antes de integrarlo.
El flujo típico para contribuir a un repositorio en GitHub es el siguiente:
1️⃣ Crear un fork del repositorio¶
Ir al repositorio del curso en GitHub y hacer click en fork. Esto crea una copia del repositorio en tu propia cuenta. Podés encontrar información para crear un fork en el siguiente link.
2️⃣ Clonar tu fork y trabajar localmente¶
Cloná tu repositorio en local y realizá los nuevos cambios. Recomiendo crear una nueva branch en local para realizar los cambios.
3️⃣ Guardar los cambios y agregarlos a GitHub¶
Esta es la secuencia clásica git add, git commit y git push donde se agregan los cambios nuevos a tu versión local del repositorio y luego a la remota (GitHub).
4️⃣ Abrir un Pull Request¶
Desde GitHub (la página web):
Abrí un PR. Podés encontrar más información de cómo abrir un PR en el siguiente link.
Seleccioná el repositorio original como destino.
Agregá al instructor como reviewer, así puedo evaluar los cambios y potencialmente dar feedback sobre más cambios.
Requisito de contribuir a la materia¶
Todos los estudiantes que estén tomando la materia por los puntos de optativa deberán contribuir a los apuntes de la materia al menos una vez. Para ello, tenemos una planilla donde los estudiantes deben anotar su nombre y anotarse para estar a cargo de una de las clases (la misma está disponible por medio de las cadenas de mails de la materia). Idealmente, dos estudiantes se deben encargar de las notas de cada clase.
Al momento de abrir un PR para contribuir a la materia, por favor tener en cuenta los siguientes puntos:
🤝 Los estudiantes encargados de los apuntes de una clase deben coordinar sus PRs. Hay varias maneras de hacer esto, pero debe haber un único PR por clase con commits de todos los estudiantes. Luego de que el PR se abra, Facu va a encargarse de hacer una revisión y posiblemente sugerir cambios y mejoras. Luego de iterar y haber conseguido una buena versión de las notas, los cambios se van a integrar en la página web de la materia.
↩️ Por favor seguir la convención de una oración por línea al escribir el texto. Esto facilita enormemente la revisión de cambios en Git, ya que cada línea aparece como una modificación independiente.
📝 En las notas, por favor incluir cuanto detalle sea posible sobre la clase. Piensen que las notas tienen que ser entendibles para alguien que no fue a la clase. Pueden usar las grabaciones de la clase para guiarse!
✨ No es necesario volverse un experto en myst para poder contribuir a la página web, pero recomiendo que vean la planilla de myst en la página web y cómo la misma fue generada. Myst es super elegante para escribir! Pueden usar cuantas herramientas quieran para que la página web quede lo mejor posible.
🖼️ Pueden incluir imágenes o figuras en las notas (de hecho, mucho mejor si lo hacen!). En tal caso, por favor incluir imágenes dentro de la carpeta
clases/figures.💻 En caso de que en la clase se haya mostrado código, por favor incluir en las notas el link al mismo y también las líneas de código mencionadas (myst deja poner código!). En vez de simplemente copiar y pegar el código, tratar de partir el mismo en bloques explicando qué está pasando en el mismo y qué se fue explicando durante la clase.
📚 Notar que en las notas se pueden poner palabras clave que luego pueden ser incluidas en el glosario.
📖 En caso de necesitar una referencia bibliográfica, ¡por favor citarla! También se pueden agregar nuevas citas en el archivo
bibliography.bib.🏅 Agregar sus nombres junto con sus usuarios de GitHub en la tabla al final del
README. De esta manera podemos llevar un conteo de quienes ya han contribuido a la materia y también podemos dar crédito por el trabajo de los estudiantes.
¡Así es como se trabaja en GitHub! Bienvenido al mundo del software abierto. 🚀