From fd3e2530003eb7d49e883329106085020ad28ad6 Mon Sep 17 00:00:00 2001 From: ivy Date: Fri, 18 Nov 2022 11:18:41 -0500 Subject: [PATCH 1/9] agrega paso para dependencias a deployment --- DEPLOYMENT.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/DEPLOYMENT.md b/DEPLOYMENT.md index 585b5c8ac..602826431 100644 --- a/DEPLOYMENT.md +++ b/DEPLOYMENT.md @@ -2,6 +2,15 @@ Descripción de los pasos a seguir para realizar el despliegue. +Para preparar el release: + +1. Ejecutar el comando para ver si necesitamos actualizar las dependencias de proyecto + `npm outdated —depth 0`. +2. Revisa/compara si las versiones son actualizados, y si no, si podemos actualizarlo + (revisando que se trata el nuevo version, si va a romper algo o no, puede actualizarlo localmente y probar) +3. Empieza escribir un nuevo log de version en github. Va a incluir el changelog y en casos de version + mayor, una descripción. + ⚠️ Antes de hacer un tag de release, es imprescindible: 1. Ejecutar comando `npm run changelog` y actualizar release en Github From 17e6dce299ec9ffeb48fbf8c745cf3fecca9b7ec Mon Sep 17 00:00:00 2001 From: ivy Date: Fri, 18 Nov 2022 11:19:07 -0500 Subject: [PATCH 2/9] un start para contenido de contributing --- CONTRIBUTING.md | 64 +++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 62 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 408cbc33c..0d9f23f56 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,7 +1,7 @@ # Cómo contribuir a este repo Este repositorio es un recurso abierto, y como tal estamos todos invitados a -participar. +participar. ## Sugerencias, errores y comentarios generales @@ -10,10 +10,29 @@ El lugar donde empezar es nuestro puedes buscar y ver si tu pregunta o sugerencia ya se ha preguntado antes, participar en discusiones relevantes y añadir nuevos _issues_. -## Ayuda con review, validación y sugerencias de contenido +## Para ayudar con review, validación y sugerencias de contenido Busca _issues_ con los tags [`help-wanted`](https://github.com/Laboratoria/bootcamp/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22). +### Git workflow + +En el repo seguimos un modelo de colaboración basado en forks. +__Cada una trabaja en su fork.__ Como repo público cualquiera puede +hacer un fork en su cuenta, hacer los cambios que considere y enviar +propuestas de cambios desde su fork en un pull request (PR). + +* Cambios (PRs) normalmente se envían de una rama de su fork a Laboratoria/main. +* Toda propuesta de cambios (PR) tendrá que pasar peer-review y tareas de validación, + linting y pruebas unitarias (npm test). +* Antes de enviar un PR siempre revisa primero el issue tracker para ver si ya existe + una conversación al respecto. + +Si no estás segura de cómo enviar un PR o si deberías hacerlo, lo mejor es comenzar +por un issue. +Si son cambios menores, o tienes muy claro qué cambiar y cómo, +lo ideal es pull request directamente y describir el issue/error +en la descripción de PR. + ## Creación de contenido Si tienes una idea para un curso, chequea el @@ -21,3 +40,44 @@ Si tienes una idea para un curso, chequea el [`README.md`](README.md) para ver si ya se ha propuesto algo parecido. Si tu propuesta es algo nuevo, abre un issue con tu idea y veamos que opina la comunidad. + +En el repo tenemos dos tipos de contenido: topicos y proyectos, cada una tiene +una desarolla una poca distina. + +### Topicos + +Un topico siguen un formato en particular. Nuevos topicos necesitan nuevo directorio +dentro de carpeta `topic` con el nombre de topic, y dentro eso creas directorios por casa "capitulo". + +En el directorio `topics` de proyecto encuentras un `_template` que puede seguir. + +CUando estas haciendo contenido o cambios puedes visualizar los cambios corriendo el sitio +de curricula localmente con estos pasos: + +1. corre `npm build:content` para crear/actualizar el contenido topicos +2. `npm run test:topics o pretest ?` +3. corre `npm run build` para hacer los componentes de sitio +4. correr `npm start` para correr el server y navegar al sitio, o `npm run watch` si quiere.. + + +### Proyectos + +Puedes encontrar los proyectos dentro `projects`. Cada proyecto tiene su propio carpeta con un +boilerplate. Los READMEs son generado con un script que incluye los Objetivos de Aprendizaje +en una manera automatizado. + +Si haces cambios a un README y o agregas objetivos de aprendizaje al proyecto +y quieres ver como parece en su totalidad, +usa (`create-cohort-project` script)[scripts/README.md#scripts-para-coaches] para generar +el repo localmente (no tienes que epujer el repo). + +Si haces cambios con un impacto a boilerplate o creas un proyecto nuevo, +seria bueno tener un ejemplo de implementacion, un proyecto desplegada para probarlo. + +md lint? + +### Learning Objectives + +... + + From 98a4a25ad1b1816134635fe148b6c0725aea41f4 Mon Sep 17 00:00:00 2001 From: ivy Date: Fri, 18 Nov 2022 11:21:03 -0500 Subject: [PATCH 3/9] add placeholders --- CONTRIBUTING.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0d9f23f56..7c98a4b15 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,10 +10,12 @@ El lugar donde empezar es nuestro puedes buscar y ver si tu pregunta o sugerencia ya se ha preguntado antes, participar en discusiones relevantes y añadir nuevos _issues_. -## Para ayudar con review, validación y sugerencias de contenido +### Para ayudar con review, validación y sugerencias de contenido Busca _issues_ con los tags [`help-wanted`](https://github.com/Laboratoria/bootcamp/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22). +## Temas de Desarollo + ### Git workflow En el repo seguimos un modelo de colaboración basado en forks. @@ -33,6 +35,10 @@ Si son cambios menores, o tienes muy claro qué cambiar y cómo, lo ideal es pull request directamente y describir el issue/error en la descripción de PR. +### Estilo de codigo + +Link to wiki + ## Creación de contenido Si tienes una idea para un curso, chequea el From 136dd1b1e54604b438a4b6c9b7ae38df9799702e Mon Sep 17 00:00:00 2001 From: ivy Date: Fri, 18 Nov 2022 13:32:06 -0500 Subject: [PATCH 4/9] links a wiki, learning objectives --- CONTRIBUTING.md | 20 +++++++++++++++++--- 1 file changed, 17 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7c98a4b15..0f9302608 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -56,8 +56,9 @@ Un topico siguen un formato en particular. Nuevos topicos necesitan nuevo direct dentro de carpeta `topic` con el nombre de topic, y dentro eso creas directorios por casa "capitulo". En el directorio `topics` de proyecto encuentras un `_template` que puede seguir. +Aqui es un descripcion de [anaotmia de n topico](https://github.com/Laboratoria/bootcamp/wiki/Anatom%C3%ADa-de-un-t%C3%B3pico). -CUando estas haciendo contenido o cambios puedes visualizar los cambios corriendo el sitio +Cuando estas haciendo contenido o cambios puedes visualizar los cambios corriendo el sitio de curricula localmente con estos pasos: 1. corre `npm build:content` para crear/actualizar el contenido topicos @@ -70,7 +71,9 @@ de curricula localmente con estos pasos: Puedes encontrar los proyectos dentro `projects`. Cada proyecto tiene su propio carpeta con un boilerplate. Los READMEs son generado con un script que incluye los Objetivos de Aprendizaje -en una manera automatizado. +en una manera automatizado. Mas detalle aqui en +[anatomia de proyecto](https://github.com/Laboratoria/bootcamp/wiki/Anatom%C3%ADa-de-un-proyecto) +y [anatomia de un unidad](https://github.com/Laboratoria/bootcamp/wiki/Anatom%C3%ADa-de-una-unidad). Si haces cambios a un README y o agregas objetivos de aprendizaje al proyecto y quieres ver como parece en su totalidad, @@ -84,6 +87,17 @@ md lint? ### Learning Objectives -... +Los Objetivos de Aprendizaje (Learning Objectives) tambien son abiertos a evolucionar. +Cada proyecto viene con objetivos que definimos en su `project.yml`. + +Los objetivos que encuentran en el `proyect.yml` de un proyecto son solo algunos, +la lista completo esta en (`learning-objectives/data.yml`)[./src/learning-objectives.data.yml]. + + Con esta lista definimos los objetivos completos, traducidos, en formato yaml + que se encuentra en (`learning-objectives/intl`)[./src/learning-objectives.data.yml] + + Para proponer cambios... + + Para proponer nuevos... From 444e8abb36df2c7a1dde37539760081476654319 Mon Sep 17 00:00:00 2001 From: ivy Date: Fri, 18 Nov 2022 13:36:19 -0500 Subject: [PATCH 5/9] corregir links target blank --- CONTRIBUTING.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0f9302608..9ecbd7533 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -56,7 +56,7 @@ Un topico siguen un formato en particular. Nuevos topicos necesitan nuevo direct dentro de carpeta `topic` con el nombre de topic, y dentro eso creas directorios por casa "capitulo". En el directorio `topics` de proyecto encuentras un `_template` que puede seguir. -Aqui es un descripcion de [anaotmia de n topico](https://github.com/Laboratoria/bootcamp/wiki/Anatom%C3%ADa-de-un-t%C3%B3pico). +Aqui es un descripcion de [anaotmia de un topico](https://github.com/Laboratoria/bootcamp/wiki/Anatom%C3%ADa-de-un-t%C3%B3pico){:target="_blank"}. Cuando estas haciendo contenido o cambios puedes visualizar los cambios corriendo el sitio de curricula localmente con estos pasos: @@ -71,9 +71,9 @@ de curricula localmente con estos pasos: Puedes encontrar los proyectos dentro `projects`. Cada proyecto tiene su propio carpeta con un boilerplate. Los READMEs son generado con un script que incluye los Objetivos de Aprendizaje -en una manera automatizado. Mas detalle aqui en -[anatomia de proyecto](https://github.com/Laboratoria/bootcamp/wiki/Anatom%C3%ADa-de-un-proyecto) -y [anatomia de un unidad](https://github.com/Laboratoria/bootcamp/wiki/Anatom%C3%ADa-de-una-unidad). +en una manera automatizado. Mas detalle aqui en el wiki +[anatomia de proyecto](https://github.com/Laboratoria/bootcamp/wiki/Anatom%C3%ADa-de-un-proyecto){:target="_blank"} +y [anatomia de un unidad](https://github.com/Laboratoria/bootcamp/wiki/Anatom%C3%ADa-de-una-unidad){:target="_blank"}. Si haces cambios a un README y o agregas objetivos de aprendizaje al proyecto y quieres ver como parece en su totalidad, @@ -91,10 +91,10 @@ Los Objetivos de Aprendizaje (Learning Objectives) tambien son abiertos a evoluc Cada proyecto viene con objetivos que definimos en su `project.yml`. Los objetivos que encuentran en el `proyect.yml` de un proyecto son solo algunos, -la lista completo esta en (`learning-objectives/data.yml`)[./src/learning-objectives.data.yml]. +la lista completo esta en [`learning-objectives/data.yml`](./src/learning-objectives.data.yml){:target="_blank"}. Con esta lista definimos los objetivos completos, traducidos, en formato yaml - que se encuentra en (`learning-objectives/intl`)[./src/learning-objectives.data.yml] + que se encuentra en [`learning-objectives/intl`](./src/learning-objectives.data.yml){:target="_blank"}. Para proponer cambios... From af96c72eb1976e5913c2bc82eb09fb5fefaa1010 Mon Sep 17 00:00:00 2001 From: ivy Date: Thu, 11 May 2023 14:56:07 -0500 Subject: [PATCH 6/9] revise contributing, separar partes de Topics y Projects --- CONTRIBUTING.md | 266 ++++++++++++++++++++++++++++++++------- contributing/PROJECTS.md | 145 +++++++++++++++++++++ contributing/TOPICS.md | 190 ++++++++++++++++++++++++++++ 3 files changed, 553 insertions(+), 48 deletions(-) create mode 100644 contributing/PROJECTS.md create mode 100644 contributing/TOPICS.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9ecbd7533..5dcec7810 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,20 +1,72 @@ -# Cómo contribuir a este repo +# Contribución + + +## Índice + +* [Cómo contribuir a este repo](#cómo-contribuir-a-este-repo) + * [Sugerencias errores y comentarios generales](#sugerencias-errores-y-comentarios-generales) + * [Para ayudar con review, validación y sugerencias de contenido](#para-ayudar-con-review-validación-y-sugerencias-de-contenido) + * [Para mejorar o crear contenido](#para-mejorar-o-crear-contenido) +* [Guía de Desarrollo](#guía-de-desarrollo) + * [Git workflow](#git-workflow) + * [Viendo cambios](#viendo-cambios) + * [Estilo](#estilo) + * [Estilo Editorial](#estilo-editorial) + * [Configuración de Editor de Texto](#configuración-de-editor-de-texto) + * [Markdown](#markdown) + * [JavaScript](#javascript) +* [Creación de Contenido](#creación-de-contenido) + * [Buenas practicas](#buenas-prácticas) + * [Tópicos](#tópicos) + * [Proyectos](#proyectos) + +## Cómo contribuir a este repo Este repositorio es un recurso abierto, y como tal estamos todos invitados a -participar. +participar. Puedes contribuir con sugerencias, reportajes de errores o bugs, +comentarios en pull requests o conversaciones de issues. -## Sugerencias, errores y comentarios generales +### Sugerencias, errores y comentarios generales -El lugar donde empezar es nuestro +Si quieres comentar o añadir sugerencias, o reportar un error, +el lugar donde empezar es nuestro [_issue tracker_](https://github.com/Laboratoria/bootcamp/issues). Ahí puedes buscar y ver si tu pregunta o sugerencia ya se ha preguntado antes, participar en discusiones relevantes y añadir nuevos _issues_. ### Para ayudar con review, validación y sugerencias de contenido -Busca _issues_ con los tags [`help-wanted`](https://github.com/Laboratoria/bootcamp/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22). +Busca _issues_ con los tags [`help-wanted`](https://github.com/Laboratoria/bootcamp/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) +o [pull requests abiertos en review](https://github.com/Laboratoria/bootcamp/pulls) y +participar en las conversaciones. -## Temas de Desarollo +### Para mejorar o crear contenido + +Si tienes ganas a arreglar un error o un issue existente, lee las secciones de +Guía de Desarrollo para aprender como escribir, probar +y mandar su código. Si no existe un issue pero son cambios menores, +o tienes muy claro qué cambiar y cómo, lo ideal es pull request directamente +y describir el issue/error en la descripción de PR. + +Para crear nuevo contenido, el trabajo necesita tener un issue para describir el +propósito de trabajo y conversar con la comunidad de la idea. +Puede ser [un issue que ya existe](https://github.com/Laboratoria/bootcamp/issues) +o puedes crear un nuevo issue. Si es un nuevo issue, +hay que conversar con el equipo de contenido de curricula, y otros coaches, +si vale hacer el trabajo que el issue se propone. + +Igual, lee las secciones de Guía de Desarrollo para aprender +como construir nuevo contenido (proyectos y tópicos), +probar y mandar su código. + +--- + +## Guía de Desarrollo + +El planteamiento general del desarrollo de la curricula se basa intencionalmente +en el modelo de desarrollo de software libre y apunta a aprovechar sus bondades. +Si no tienes un perfil técnico y todo esto te suena raro, no te preocupes, +la comunidad está acá para ayudar y guiar. ### Git workflow @@ -31,73 +83,191 @@ propuestas de cambios desde su fork en un pull request (PR). Si no estás segura de cómo enviar un PR o si deberías hacerlo, lo mejor es comenzar por un issue. -Si son cambios menores, o tienes muy claro qué cambiar y cómo, -lo ideal es pull request directamente y describir el issue/error -en la descripción de PR. -### Estilo de codigo +### Viendo cambios + +Cuando estas haciendo cambios a contenido puedes visualizar los cambios corriendo el sitio +de curricula localmente con estos pasos: + +1. Corre `npm test` para ver si los cambios han afectado los tests +2. Corre `npm build:content` para crear/actualizar los jsons de tópicos y proyectos (el sitio usa esos jsons) +3. Corre `npm run build` para hacer los componentes de sitio +4. Correr `npm start` para correr el server y navegar al sitio, o `npm run watch` si quiere. + +Puedes ver los proyectos y topicos en el sitio localmente. + +También puedes visualizar los cambios de READMEs de proyecto en otras maneras. + +1. Directamente en VSC con un preview de markdown. +2. Empujando los cambios a tu rama y navegando al README en tu rama en tu fork. +3. Corriendo el script `create-cohort-project` para ver el proyecto + generado como tal los coaches van a usar. TODO link a script + +*** + +### Estilo + +El contenido que se vaya creando en este repo debe seguir una serie de +**convenciones** a nivel de **estilo**, **formato** y **estructura** con los +siguientes objetivos: + +* crear una **experiencia consistente** +* sacar el máximo provecho al **proceso colaborativo** +* poder **analizar los cursos de forma programática** para después ofrecer la + experiencia de aprendizaje a nuestras estudiantes + +Estas convenciones se irán documentando acá e irán evolucionando en el tiempo, +así que no dudes en proponer mejoras o cambios. + +Para facilitar el proceso de _code review_ y colaboración en general, creemos +que es esencial seguir una guía de estilos clara, que dé consistencia a la +malla en general. + +Es responsabilidad de lxs mantenedores de este repo asegurar que se cumplen +las convenciones. Hay autorxs que no son necesariamente programadorxs y en este +aspecto la comunidad, y en particular Laboratoria, deben apoyar y guiar en los +temas técnicos. Este proyecto adopta un modelo propio del desarrollo de software +para diseñar contenido, así que nos toca tener flexibilidad para creadorxs a la +vez que aseguramos estándares de estilo, estructura y formato para poder +analizar estos cursos de forma programática. + +[El estilo es importante](https://www.smashingmagazine.com/2012/10/why-coding-style-matters/). + +Las guías de estilo se dividen en: + +* [Estilo editorial](#estilo-editorial) +* [Configuración de editor de texto](#configuración-de-editor-de-texto) +* [Markdown](#markdown) +* [Javascript](#javascript) + +#### Estilo editorial + +A tener en cuenta a la hora de escribir... -Link to wiki +* Tono coloquial (tú en vez de usted) +* Narración dirigida a la estudiante como lectora, 2da persona, singular (ie: en esta + lección aprenderás a ...) +* Femenino genérico o `x` para neutro (ie: `Todxs lxs programadorxs`) TODO resalta eso +* [El adverbio solo y los pronombres demostrativos, sin tilde](http://www.rae.es/consultas/el-adverbio-solo-y-los-pronombres-demostrativos-sin-tilde) +* Marcado semántico (ie: usar `blockquotes` para _citas_ y solo citas) +* Frases cortas + +#### Configuración de editor de texto + +La mayoría del contenido (pero no todo) se desarrolla en archivos de texto +plano. Para manejar archivos de texto (`.md`, `.js`, `.html`, ...) vas a +necesitar un editor de texto. Puedes usar tu editor favorito, y si todavía no +tienes uno te recomendamos [VS Code](https://code.visualstudio.com/). + +Para definir y mantener convenciones de uso de espacios y otras características +configurable en un editor de texto el repo incluye un archivo +[`.editorconfig`](https://github.com/Laboratoria/bootcamp/blob/main/.editorconfig), +que es un estándar para manejar este tipo de convenciones. Más info en +[editorconfig.org](http://editorconfig.org/). + +Esta configuración funciona con la mayoría de editores populares. + +#### Markdown + +[Markdown](https://daringfireball.net/projects/markdown/syntax), en particular +[GitHub Flavored Markdown](https://guides.github.com/features/mastering-markdown/), +es el formato más común en la currícula. Si no estás familiarizada con Markdown, +acá tienes un +[Cheat Sheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) +muy útil. + +Para facilitar la tarea de validar las convenciones a nivel de Markdown, el +repo incluye una _tarea_ que verifica el _estilo_ del Markdown usando un linter. +Esta tarea se ejecuta automáticamente al enviar un pull request. +Alternativamente, también la puedes ejecutar directamente en tu copia local con +el comando `npm run mdlint` (esta tarea también se ejecuta cuando hacemos +`npm test`). + +#### JavaScript + +Por ahora hemos [acordado](https://github.com/Laboratoria/bootcamp/issues/11) +usar la guías de estilo de [AirBnB](https://github.com/airbnb/javascript), en +particular usando: + +* [`eslint-config-airbnb-base`](https://www.npmjs.com/package/eslint-config-airbnb-base) +* [`eslint-config-airbnb`](https://www.npmjs.com/package/eslint-config-airbnb) + +Los ejemplos, snippets, y proyectos de ejemplo de Laboratoria deberían usar +el mismo estilo. ## Creación de contenido -Si tienes una idea para un curso, chequea el +La malla curricular está compuesta de _proyectos_ y _tópicos_. + +Los contenidos desarrollados en este repo deben seguir una estructura y una +serie de convenciones para después poder ser analizado y convertido de forma +automatizada a una estructura de datos que pueda ser usada por nuestro _LMS_ +(Ver [`curriculum-parser`](https://github.com/Laboratoria/curriculum-parser)). + +Si tienes una idea para un curso o proyecto, chequea el [issue tracker](https://github.com/Laboratoria/bootcamp/issues) y el [`README.md`](README.md) para ver si ya se ha propuesto algo parecido. Si tu -propuesta es algo nuevo, abre un issue con tu idea y veamos que opina la +propuesta es nueva, abre un issue con tu idea y veamos que opina la comunidad. -En el repo tenemos dos tipos de contenido: topicos y proyectos, cada una tiene -una desarolla una poca distina. +TODO: donde mencionamos eso? + +\* Dependiendo de la naturaleza del contenido, se decidirán los detalles +exactos ya que no todos los proyectos o tópicos tienen la misma naturaleza._ + +### Buenas prácticas -### Topicos +- **Mantener tus contenidos DRY** Al momento de planear un contenido, tener en + consideración que ya existe material (videos, entradas de blog, etc) muy + bueno en internet que únicamente necesita traducirse. Generar contenido + desde 0 es difícil. Traducir y dar crédito, no tanto. +- **Manejo de archivos binarios** +Ver [#114](https://github.com/Laboratoria/bootcamp/issues/114#issuecomment-321457379). -Un topico siguen un formato en particular. Nuevos topicos necesitan nuevo directorio -dentro de carpeta `topic` con el nombre de topic, y dentro eso creas directorios por casa "capitulo". +### Tópicos -En el directorio `topics` de proyecto encuentras un `_template` que puede seguir. -Aqui es un descripcion de [anaotmia de un topico](https://github.com/Laboratoria/bootcamp/wiki/Anatom%C3%ADa-de-un-t%C3%B3pico){:target="_blank"}. +Un tópico siguen un formato en particular. Nuevos tópicos necesitan nuevo +directorio dentro de carpeta `topic` con el nombre de topic, y dentro eso +creas directorios por cada "capitulo". + +Para aprender como estructurar un tópico, lee [la guía de tópicos](contributing/TOPICS.md) + +// TODO verifica pasos Cuando estas haciendo contenido o cambios puedes visualizar los cambios corriendo el sitio de curricula localmente con estos pasos: -1. corre `npm build:content` para crear/actualizar el contenido topicos -2. `npm run test:topics o pretest ?` +1. ejecuta `npm run test:topics` para confirmar que los tests pasen +2. corre `npm build:content` para crear/actualizar el contenido tópicos 3. corre `npm run build` para hacer los componentes de sitio -4. correr `npm start` para correr el server y navegar al sitio, o `npm run watch` si quiere.. - +4. correr `npm start` para correr el server y navegar al sitio, o `npm run watch` si quiere. ### Proyectos -Puedes encontrar los proyectos dentro `projects`. Cada proyecto tiene su propio carpeta con un -boilerplate. Los READMEs son generado con un script que incluye los Objetivos de Aprendizaje -en una manera automatizado. Mas detalle aqui en el wiki -[anatomia de proyecto](https://github.com/Laboratoria/bootcamp/wiki/Anatom%C3%ADa-de-un-proyecto){:target="_blank"} -y [anatomia de un unidad](https://github.com/Laboratoria/bootcamp/wiki/Anatom%C3%ADa-de-una-unidad){:target="_blank"}. +Puedes encontrar los proyectos de curricula dentro [la carpeta `projects`](https://github.com/Laboratoria/bootcamp/blob/main/projects). +Cada proyecto tiene su propio carpeta con un boilerplate y README. + +Para aprender como estructurar un proyecto, revisa [la guía de Proyectos](contributing/PROJECTS.md) Si haces cambios a un README y o agregas objetivos de aprendizaje al proyecto -y quieres ver como parece en su totalidad, +y quieres ver como parece el proyecto en su totalidad, usa (`create-cohort-project` script)[scripts/README.md#scripts-para-coaches] para generar -el repo localmente (no tienes que epujer el repo). +el repo de proyecto localmente (no tienes que empujar el repo). Este script incluye los +Objetivos de Aprendizaje en una manera automatizado. -Si haces cambios con un impacto a boilerplate o creas un proyecto nuevo, -seria bueno tener un ejemplo de implementacion, un proyecto desplegada para probarlo. - -md lint? - -### Learning Objectives +También puedes verlo en el sitio de curricula, usando los mismos pasos +para ver tópicos. -Los Objetivos de Aprendizaje (Learning Objectives) tambien son abiertos a evolucionar. -Cada proyecto viene con objetivos que definimos en su `project.yml`. +TODO hay que hacer npm run test? -Los objetivos que encuentran en el `proyect.yml` de un proyecto son solo algunos, -la lista completo esta en [`learning-objectives/data.yml`](./src/learning-objectives.data.yml){:target="_blank"}. - - Con esta lista definimos los objetivos completos, traducidos, en formato yaml - que se encuentra en [`learning-objectives/intl`](./src/learning-objectives.data.yml){:target="_blank"}. - - Para proponer cambios... - - Para proponer nuevos... +1. corre `npm build:content` para crear/actualizar el contenido tópicos +2. corre `npm run build` para hacer los componentes de sitio +3. correr `npm start` para correr el server y navegar al sitio, o `npm run watch` si quiere. +Otro script que debes ejecutar mientras cambiar un README de un proyecto es +`npm run mdlint` que va a chequear los archivos Markdown y resaltar errores. Corremos +eso con github actions también entonces mejor usarlo localmente para ver y corregir +errores. +Si haces cambios con un impacto a boilerplate o creas un proyecto nuevo, +seria bueno tener un ejemplo de implementación, un proyecto desplegada para probarlo. diff --git a/contributing/PROJECTS.md b/contributing/PROJECTS.md new file mode 100644 index 000000000..1a7d8cac4 --- /dev/null +++ b/contributing/PROJECTS.md @@ -0,0 +1,145 @@ +# Guía de Proyectos + +## Anatomía de un proyecto + +* Las carpetas de _proyectos_ siguen la nomenclarura `00-slug`, donde `00` son + dos dígitos que expresan una intención de ordenado, y el `slug` es un string + único para cada _proyecto_, en minúsculas y de entre `1` y `97` caracteres. + Expresado como `RegExp` sería algo como `^\d{2}-[a-z\-]{1,97}$`. Longitud + máxima del nombre de carpeta son `100` caracteres. +* El único archivo obligatorio es el `README.md`. +* Todo lo demás se considera _boilerplate_. + +## project.yml + +## `README.md` + +Lo mejor es ver un par de ejemplos como +[`cipher`](../tree/master/projects/01-cipher) o +[`burger-queen`](../tree/master/projects/04-burger-queen). + +* Debe comenzar con un `

` con el _título_ del proyecto. +* Justo después del título debe incluir un _índice_ (TOC). +* El índice debería incluir solo un nivel del árbol, a menos de que haya un + motivo especial que lo justifique. +* Inmediatamente después cerramos el índice con un `
`. +* El índice no debe listarse a sí mismo. No hay necesidad de incluir el índice como primer elemento del índice. +* Los elementos del indice estarán numerados. Esto hace más fácil digerir y manejar la información del proyecto. + +Ejemplo de título y TOC: + +```md +# Título + +## Índice + +* [1. Preámbulo](#1-preámbulo) +* [2. Resumen del proyecto](#2-resumen-del-proyecto) +* [3. Objetivos de aprendizaje](#3-objetivos-de-aprendizaje) +* [4. Consideraciones generales](#4-consideraciones-generales) +* [5. Criterios de aceptación mínimos del proyecto](#5-criterios-de-aceptación-mínimos-del-proyecto) +* [6. Pistas, tips y lecturas complementarias](#6-pistas-tips-y-lecturas-complementarias) + +*** +``` + +https://github.com/Laboratoria/bootcamp/blob/1b99054d798e945dcb863b4d14f7ea91dd53d726/projects/01-cipher/README.md?plain=1#L1-L16 + +### Secciones + +Cada sección (obligatoria o no) comienza con un `

` con el título de la +sección. Para facilitar la navegación y conversación sobre los proyectos usamos +un prefijo numérico (como lista numerada). + +#### Secciones obligatorias + +* 1. Preámbulo +* 2. Resumen del proyecto +* 3. Objetivos de aprendizaje +* 4. Consideraciones generales +* 5. Criterios de aceptación mínimos del proyecto +* 6. Pistas, tips y lecturas complementarias + +Ejemplo de secciones: + +```md +## 1. Preámbulo + +Entre 1 y 3 párrafos dándo contexto al proyecto, las tecnologías y herramientas +involucradas, por qué es importante/útil aprender esto. Qué esperar del proyecto +(desde el punto de vista de la estudiante). + +## 2. Resumen del proyecto + +Un explanación de concepto de proyecto, mejor con un ejemplo y contexto. + +## 3. Objetivos de aprendizaje + +Este sección debe que estar en algun parte de proyecto (no importa el orden) +pero con el titulo `Objetivos de aprendizaje`. El script de curriculum parser +inserta los objetivos en este seccion, usando los que estan listado en el `project.yml`. + +## 4. Consideraciones generales + +Este proyecto se debe "resolver" de forma [individual/duplas/tríos/...]. + +Blah blah blah... + +## 5. Criterios de aceptación mínimos del proyecto + +### Definición del producto + +Blah blah blah... + +*** + +#### [Historia de usuario 1] Blah blah blah... + +Blah blah blah... + +##### Criterios de aceptación + +Lo que debe ocurrir para que se satisfagan las necesidades del usuario) + +* ... + +##### Definición de terminado + +Lo acordado que debe ocurrir para decir que la historia está terminada. + +* ... + +*** + +## 6. Pistas, tips y lecturas complementarias + +### Primeros pasos + +Blah blah blah... + +### Otros recursos + +Blah blah blah... +``` + +#### Secciones opcionales + +* Hacker edition +* Consideraciones técnicas (más detalles técnicos :see_no_evil:) +* Checklist + +### Learning Objectives + +Los Objetivos de Aprendizaje (Learning Objectives) tambien son abiertos a evolucionar. +Cada proyecto viene con objetivos que definimos en su `project.yml`. + +Los objetivos que encuentran en el `proyect.yml` de un proyecto son solo algunos, +la lista completo esta en [`learning-objectives/data.yml`](./src/learning-objectives.data.yml){:target="_blank"}. + + Con esta lista definimos los objetivos completos, traducidos, en formato yaml + que se encuentra en [`learning-objectives/intl`](./src/learning-objectives.data.yml){:target="_blank"}. + + Para proponer cambios... + + Para proponer nuevos... + diff --git a/contributing/TOPICS.md b/contributing/TOPICS.md new file mode 100644 index 000000000..9cadd4955 --- /dev/null +++ b/contributing/TOPICS.md @@ -0,0 +1,190 @@ +# Guía de topics + +## Anatomía de un tópico + +Dentro de cada carpeta de _tópico_ debe haber un archivo `README.md` con la +información general del tópico. + +Estructura de archivos: + +TODO: revisa con alpi + +```text +topic-slug # tópico +├── 01-unit-slug # unidad +│   ├── 00-opening # parte +│   │   └── README.md +│   ├── 01-part-title-1 +│   │   └── README.md +│   ├── 02-part-title-2 +│   │   └── README.md +│   ├── 03-example-exercise +│   │   ├── 01-print-primes +│   │   │   ├── README.md +│   │   │   ├── boilerplate +│   │   │   │   └── printPrimes.js +│   │   │   ├── solution +│   │   │   │   └── printPrimes.js +│   │   │   └── test +│   │   │   └── printPrimes.spec.js +│   │   └── README.md +│   └── 04-closing +│   └── README.md +├── 02-unit-slug/ +│ └── ... +├── 03-unit-slug/ +│ └── ... +└── README.md +``` + +_slug_ significa title o identificador. + +Nombres de archivos y carpetas en minúsculas, usando `-` en vez de espacios y +evitando caracteres especiales. + +## `README.md` principal del _tópico_ + +Cada tópico empieza por un archivo `README.md`. La mejor manera de familiarizarse +con la estructura de este archivo es ver [este ejemplo](https://github.com/Laboratoria/bootcamp/blob/main/topics/_template/README.md). + +TODO: talk about head matter +solo tiene track + +* Título (`title`) _required_ +~* Descripción (`description`)~ _required_ +~* Tags: (`tags`)~ _required_ + +Secciones: + +* Público objetivo (`targetAudience`) _required_ +* Requerimientos previos (`dependencies`) _required_ +* Objetivos de aprendizaje (`learningObjectives`) _required_ +* Producto(s) a desarrollar (`product`) _required_ +* Guía de preguntas y conceptos clave (`keyConcepts`) +* Syllabus (`syllabus`) _required_ +* Evaluación (`grading`) _required_ +* Contribuidores (`contributors`) _required_ +* Libros (`books`) +* Benchmarks (`benchmarks`) +* Referencias (`references`) + +### Título (requerido) + +La primera línea del `README.md` de un tópico debe contener un `h1` con el título +completo. + +```md +# Título del tópico +``` + +### Descripción (requerido) + +La descripcción del tópico es un espacio _libre_ que va desde el título hasta +la lista de `tags` o el heading de público objetivo. + +### Tags (requerido) + +... + + +## Anatomía de Unidades + +Recomendamos que cada unidad empiece con una _lectura_ de **apertura** y termine +con una de **cierre**. + +Estructura de archivos: + +```text +0X-topic-slug +├── 01-titulo-corto-unidad/ # unidad +│   ├── 00-apertura # parte +│ |  └── README.md +│   ├── 01-titulo-corto +│ |  └── README.md +│   ├── 02-practice +│ |  ├── 01-un-ejercicio +│ |  ├── 02-otro-ejercicio +│ |  └── README.md +│   ├── 03-some-quiz +│   ├── 04-ejercicios-guiados +│   ├── 05-solucionario +│   ├── 06-requizz +│   └── 07-cierre +├── 02-titulo-corto-unidad/ +├── 03-titulo-corto-unidad/ +└── README.md +``` + +TODO readme de unidades tiene estructura o solo consiste de directoriod de partes? + +## Anatomía de una _parte_ (actividad) de una _unidad_ + +Cada parte de cada unidad debe tener su propio `README.md`. La primera línea en +el `README.md` debe ser un `h1` con el título completo de la parte. + +```text +h1 (título) * +ul * + li (tipo) * + li (formato) * + li (duración) * +h2 (objetivos de aprendizaje) +ul + li (objetivo de aprendizaje 1) + li (objetivo de aprendizaje 2) + li (objetivo de aprendizaje n) +hr * +body (el cuerpo/contenido) + +* obligatorio +``` + +### Tipo + +#### `seminario/seminar` (deprecated/legacy) + +Un seminario es lo más parecido a una clase presencial tradicional. Los +seminarios son _guiados_ por unx o más instructorxs. + +#### `lectura/read` + +Las lecturas son artículos de contenido que pueden incluir videos, imágenes y +otros soprtes, embebidos o como vínculos externos. + +#### `práctica/practice` + +Las prácticas principalmente ejercicios y pueden tener diferentes entornos: +`js`, `web`, `node`, ... + +#### `cuestionario/quiz` + +Los cuestionarios a corto plazo se manejarán como links a Google Forms. Más +adelante se implementará una manera más apropiada para poder incluir en nuestro +LMS. + +#### `taller/workshop` (deprecated/legacy) + +Los talleres (o workshops) son sesiones guiadas o no guiadas (self-paced) +durante las cuales las alumnas realizan una actividad prolongada, como +implementación, diseño o investigación. Al final de un taller o grupo de +talleres normalmente se cierra con una demo o presentación. + +### Formato + +Cualquiera de los _tipos_ de contenido anteriores pueden darse (o proponerse) en +dos formatos: + +#### `guiado/guided` (deprecated/legacy) + +Los contenidos guiados son aquellos donde la _clase_ es dirigida por unx o más +instructorxs. Los seminarios son siempre guiados, mientras que los talleres, +lecturas o ejercicios pueden ser guiados o no. + +#### `self-paced` + +Los contenidos _self paced_ (a tu propio ritmo) son aquellos que están dirigidos +por las alumnas y por lo general podrían ver estas partes en su propio tiempo. +En este formato, lxs instructorxs tienen el rol de acompañar, guíar y apoyar, +pero son ellxs quienes dirigen la actividad. + +### Duracion ? TODO como averiguar eso From c4a44607ec808742625b5a639acaf85dffe806c7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alfredo=20Gonz=C3=A1lez?= Date: Tue, 16 May 2023 15:55:06 -0400 Subject: [PATCH 7/9] =?UTF-8?q?fix(docs):=20Arregla=20y=20responde=20vario?= =?UTF-8?q?s=20TODOs=20del=20archivo=20CONTRIBUTING.md=20(a=C3=BAn=20un=20?= =?UTF-8?q?WIP=20a=20ser=20revisado)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CONTRIBUTING.md | 112 ++++++++++++++++++++++++------------------------ 1 file changed, 57 insertions(+), 55 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5dcec7810..4d4852ae6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,5 @@ # Contribución - ## Índice * [Cómo contribuir a este repo](#cómo-contribuir-a-este-repo) @@ -22,9 +21,10 @@ ## Cómo contribuir a este repo -Este repositorio es un recurso abierto, y como tal estamos todos invitados a -participar. Puedes contribuir con sugerencias, reportajes de errores o bugs, -comentarios en pull requests o conversaciones de issues. +Este repositorio es un recurso abierto, y como tal estamos toas y todos +invitados a participar. Puedes contribuir con sugerencias, ideas, cambios, +reportes de errores o bugs, comentarios en pull requests o conversaciones de +issues. ### Sugerencias, errores y comentarios generales @@ -52,12 +52,12 @@ Para crear nuevo contenido, el trabajo necesita tener un issue para describir el propósito de trabajo y conversar con la comunidad de la idea. Puede ser [un issue que ya existe](https://github.com/Laboratoria/bootcamp/issues) o puedes crear un nuevo issue. Si es un nuevo issue, -hay que conversar con el equipo de contenido de curricula, y otros coaches, -si vale hacer el trabajo que el issue se propone. +intenta conversar con el equipo de contenido de curricula, y otras coaches, +si el cambio propuesto es válido y le hace sentido a las demás. -Igual, lee las secciones de Guía de Desarrollo para aprender -como construir nuevo contenido (proyectos y tópicos), -probar y mandar su código. +De igual manera, te invitamos a leer las secciones de Guía de Desarrollo +para aprender como construir nuevo contenido (ya sea de proyectos o tópicos), +testear y enviar tu código como PR. --- @@ -89,19 +89,22 @@ por un issue. Cuando estas haciendo cambios a contenido puedes visualizar los cambios corriendo el sitio de curricula localmente con estos pasos: -1. Corre `npm test` para ver si los cambios han afectado los tests -2. Corre `npm build:content` para crear/actualizar los jsons de tópicos y proyectos (el sitio usa esos jsons) -3. Corre `npm run build` para hacer los componentes de sitio -4. Correr `npm start` para correr el server y navegar al sitio, o `npm run watch` si quiere. +1. Corre `npm test` para ver si los cambios han afectado los tests. +2. Corre `npm run build:content` para crear/actualizar los jsons de tópicos y + proyectos de los cuales la App de React del repo se alimenta. +3. Correr `npm start` para correr el server y navegar al sitio, o + también puedes hacer `npm run watch` para poder visualizar los cambios en + vivo sin tener que estar actualizando el sitio. -Puedes ver los proyectos y topicos en el sitio localmente. +Puedes navegar hacia los proyectos y topicos en el sitio localmente. También puedes visualizar los cambios de READMEs de proyecto en otras maneras. 1. Directamente en VSC con un preview de markdown. 2. Empujando los cambios a tu rama y navegando al README en tu rama en tu fork. -3. Corriendo el script `create-cohort-project` para ver el proyecto - generado como tal los coaches van a usar. TODO link a script +3. Corriendo el script [`create-cohort-project`](./scripts/create-cohort-project.mjs) + para ver el proyecto generado tal cual como las coaches se lo compartirán a + las estudiantes. *** @@ -111,9 +114,9 @@ El contenido que se vaya creando en este repo debe seguir una serie de **convenciones** a nivel de **estilo**, **formato** y **estructura** con los siguientes objetivos: -* crear una **experiencia consistente** -* sacar el máximo provecho al **proceso colaborativo** -* poder **analizar los cursos de forma programática** para después ofrecer la +* Crear una **experiencia consistente** +* Sacar el máximo provecho al **proceso colaborativo** +* Poder **analizar los cursos de forma programática** para después ofrecer la experiencia de aprendizaje a nuestras estudiantes Estas convenciones se irán documentando acá e irán evolucionando en el tiempo, @@ -147,7 +150,7 @@ A tener en cuenta a la hora de escribir... * Tono coloquial (tú en vez de usted) * Narración dirigida a la estudiante como lectora, 2da persona, singular (ie: en esta lección aprenderás a ...) -* Femenino genérico o `x` para neutro (ie: `Todxs lxs programadorxs`) TODO resalta eso +* **Femenino genérico o `x` para neutro (ie: `Todxs lxs programadorxs`)** * [El adverbio solo y los pronombres demostrativos, sin tilde](http://www.rae.es/consultas/el-adverbio-solo-y-los-pronombres-demostrativos-sin-tilde) * Marcado semántico (ie: usar `blockquotes` para _citas_ y solo citas) * Frases cortas @@ -227,47 +230,46 @@ Ver [#114](https://github.com/Laboratoria/bootcamp/issues/114#issuecomment-32145 ### Tópicos Un tópico siguen un formato en particular. Nuevos tópicos necesitan nuevo -directorio dentro de carpeta `topic` con el nombre de topic, y dentro eso -creas directorios por cada "capitulo". - -Para aprender como estructurar un tópico, lee [la guía de tópicos](contributing/TOPICS.md) +directorio dentro de carpeta [`/topics`](./topics/) con el nombre del tópico, +y dentro eso creas directorios por cada _unidad_. -// TODO verifica pasos +Para aprender como estructurar un tópico, lee [la guía de tópicos](./contributing/TOPICS.md) -Cuando estas haciendo contenido o cambios puedes visualizar los cambios corriendo el sitio -de curricula localmente con estos pasos: - -1. ejecuta `npm run test:topics` para confirmar que los tests pasen -2. corre `npm build:content` para crear/actualizar el contenido tópicos -3. corre `npm run build` para hacer los componentes de sitio -4. correr `npm start` para correr el server y navegar al sitio, o `npm run watch` si quiere. +Cuando estés creando contenido o haciendo cambios puedes visualizarlos +corriendo el sitio de curricula localmente como +[se explica anteriormente](#viendo-cambios). ### Proyectos -Puedes encontrar los proyectos de curricula dentro [la carpeta `projects`](https://github.com/Laboratoria/bootcamp/blob/main/projects). -Cada proyecto tiene su propio carpeta con un boilerplate y README. +Puedes encontrar los proyectos de la curricula en el directorio +[`projects`](./projects/). + +Cada proyecto tiene su propio directorio con el boilerplate necesario y +su enunciado en el archivo README. -Para aprender como estructurar un proyecto, revisa [la guía de Proyectos](contributing/PROJECTS.md) +Para aprender como estructurar un proyecto, revisa [la guía de Proyectos](./contributing/PROJECTS.md) Si haces cambios a un README y o agregas objetivos de aprendizaje al proyecto y quieres ver como parece el proyecto en su totalidad, -usa (`create-cohort-project` script)[scripts/README.md#scripts-para-coaches] para generar -el repo de proyecto localmente (no tienes que empujar el repo). Este script incluye los -Objetivos de Aprendizaje en una manera automatizado. - -También puedes verlo en el sitio de curricula, usando los mismos pasos -para ver tópicos. - -TODO hay que hacer npm run test? - -1. corre `npm build:content` para crear/actualizar el contenido tópicos -2. corre `npm run build` para hacer los componentes de sitio -3. correr `npm start` para correr el server y navegar al sitio, o `npm run watch` si quiere. - -Otro script que debes ejecutar mientras cambiar un README de un proyecto es -`npm run mdlint` que va a chequear los archivos Markdown y resaltar errores. Corremos -eso con github actions también entonces mejor usarlo localmente para ver y corregir -errores. - -Si haces cambios con un impacto a boilerplate o creas un proyecto nuevo, -seria bueno tener un ejemplo de implementación, un proyecto desplegada para probarlo. +usa el script [`create-cohort-project`](./scripts/README.md#create-cohort-project) +para generar el proyecto localmente (no es necesario empujarlo a Github). + +Este script crea la sección de Objetivos de Aprendizaje del proyecto a partir +del archivo `project-yml` que lo acompaña y que enlista los OAs asociados a él. + +También puedes ir viendo el resultado corriendo el sitio de curricula +localmente como [se explica anteriormente](#viendo-cambios). + +Otro script que debes ejecutar mientras realizas cambios a un README de un +proyecto es `npm run mdlint` que va a ejecutar el linter que va a analizar los +archivos Markdown y resaltar errores. Si no se ejecuta de manera local, de +igual forma será ejecutado en una Github Action cuando abras tu PR, +recomendamos ejecutarlo de manera local de manera de arreglar errores de estilo +que puedan haber de manera que luego la Github Action asociada pase +satisfactoriamente sin errores. + +Si haces cambios con que impacten directamente el _boilerplate_ de un proyecto, +o derechamente si quieres proponer un nuevo proyecto, es necesario contar con +una implementación modelo del proyecto de manera de entender cualquier caso +borde o _caveat_ que pueda haber con respecto al enunciado, OAs, o tecnología +asociada a la solución propuesta para ese proyecto. From 1db41b1c88814c7f13b456c34371d218e2dfbedf Mon Sep 17 00:00:00 2001 From: ivy Date: Mon, 26 Jun 2023 09:33:07 -0400 Subject: [PATCH 8/9] chore(content): add track to template --- topics/_template/README.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/topics/_template/README.md b/topics/_template/README.md index f5d1c6090..0d905bf2e 100644 --- a/topics/_template/README.md +++ b/topics/_template/README.md @@ -1,3 +1,7 @@ +--- +track: ... +--- + # Título del tópico Dos o tres párrafos explicando el tópico en líneas generales. Introducción al From 4ca21e8d681354c5c161de8fe08617cca76fdb0b Mon Sep 17 00:00:00 2001 From: ivy Date: Mon, 26 Jun 2023 09:34:03 -0400 Subject: [PATCH 9/9] chore(contnet): rewriting topic guide --- CONTRIBUTING.md | 20 ++-- contributing/TOPICS.md | 262 +++++++++++++++++++++++++++++------------ 2 files changed, 199 insertions(+), 83 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5dcec7810..bb5504ab0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -84,7 +84,11 @@ propuestas de cambios desde su fork en un pull request (PR). Si no estás segura de cómo enviar un PR o si deberías hacerlo, lo mejor es comenzar por un issue. -### Viendo cambios +### Commits + +TODO: describir estilo https://www.conventionalcommits.org/ + +### Viendo tus cambios Cuando estas haciendo cambios a contenido puedes visualizar los cambios corriendo el sitio de curricula localmente con estos pasos: @@ -147,7 +151,7 @@ A tener en cuenta a la hora de escribir... * Tono coloquial (tú en vez de usted) * Narración dirigida a la estudiante como lectora, 2da persona, singular (ie: en esta lección aprenderás a ...) -* Femenino genérico o `x` para neutro (ie: `Todxs lxs programadorxs`) TODO resalta eso +* Femenino genérico o `x` para neutro (ie: `Todxs lxs programadorxs`) TODO: resalta eso o cambiar/omitirlo - el x se dificulta lecturas de pantalla * [El adverbio solo y los pronombres demostrativos, sin tilde](http://www.rae.es/consultas/el-adverbio-solo-y-los-pronombres-demostrativos-sin-tilde) * Marcado semántico (ie: usar `blockquotes` para _citas_ y solo citas) * Frases cortas @@ -210,9 +214,9 @@ Si tienes una idea para un curso o proyecto, chequea el propuesta es nueva, abre un issue con tu idea y veamos que opina la comunidad. -TODO: donde mencionamos eso? +TODO: donde mencionamos el siguiente: -\* Dependiendo de la naturaleza del contenido, se decidirán los detalles +Dependiendo de la naturaleza del contenido, se decidirán los detalles exactos ya que no todos los proyectos o tópicos tienen la misma naturaleza._ ### Buenas prácticas @@ -232,10 +236,10 @@ creas directorios por cada "capitulo". Para aprender como estructurar un tópico, lee [la guía de tópicos](contributing/TOPICS.md) -// TODO verifica pasos +/* TODO: verifica pasos */ -Cuando estas haciendo contenido o cambios puedes visualizar los cambios corriendo el sitio -de curricula localmente con estos pasos: +Cuando estas haciendo contenido o cambios puedes visualizar los cambios +corriendo el sitio de curricula localmente con estos pasos: 1. ejecuta `npm run test:topics` para confirmar que los tests pasen 2. corre `npm build:content` para crear/actualizar el contenido tópicos @@ -258,7 +262,7 @@ Objetivos de Aprendizaje en una manera automatizado. También puedes verlo en el sitio de curricula, usando los mismos pasos para ver tópicos. -TODO hay que hacer npm run test? +/* TODO: hay que hacer npm run test cuando creas un proyecto */ 1. corre `npm build:content` para crear/actualizar el contenido tópicos 2. corre `npm run build` para hacer los componentes de sitio diff --git a/contributing/TOPICS.md b/contributing/TOPICS.md index 9cadd4955..a1215b5d1 100644 --- a/contributing/TOPICS.md +++ b/contributing/TOPICS.md @@ -2,24 +2,24 @@ ## Anatomía de un tópico -Dentro de cada carpeta de _tópico_ debe haber un archivo `README.md` con la -información general del tópico. +Dentro de cada carpeta de _tópico_ debe haber un archivo `README.md` +con la información general del tópico. -Estructura de archivos: +Estructura de archivos de un tópico: -TODO: revisa con alpi + ```text -topic-slug # tópico -├── 01-unit-slug # unidad -│   ├── 00-opening # parte +topic-slug # tópico +├── 01-unit-slug # unidad +│   ├── 00-opening # parte │   │   └── README.md │   ├── 01-part-title-1 │   │   └── README.md │   ├── 02-part-title-2 │   │   └── README.md │   ├── 03-example-exercise -│   │   ├── 01-print-primes +│   │   ├── 01-print-primes #challenge │   │   │   ├── README.md │   │   │   ├── boilerplate │   │   │   │   └── printPrimes.js @@ -37,37 +37,49 @@ topic-slug # tópico └── README.md ``` -_slug_ significa title o identificador. +_slug_ significa title o identificador de tópico. Nombres de archivos y carpetas en minúsculas, usando `-` en vez de espacios y evitando caracteres especiales. ## `README.md` principal del _tópico_ -Cada tópico empieza por un archivo `README.md`. La mejor manera de familiarizarse -con la estructura de este archivo es ver [este ejemplo](https://github.com/Laboratoria/bootcamp/blob/main/topics/_template/README.md). +Cada tópico empieza por un archivo `README.md`. +Una manera de familiarizarse con la estructura de este archivo es ver +[este ejemplo de template](https://github.com/Laboratoria/bootcamp/blob/main/topics/_template/README.md). -TODO: talk about head matter -solo tiene track +El `README` debe tener: -* Título (`title`) _required_ +1. Track de tópico `track` (`web-dev`, `ux`, etc) +2. Título(`title`) _required_ + ~* Descripción (`description`)~ _required_ -~* Tags: (`tags`)~ _required_ - -Secciones: - -* Público objetivo (`targetAudience`) _required_ -* Requerimientos previos (`dependencies`) _required_ -* Objetivos de aprendizaje (`learningObjectives`) _required_ -* Producto(s) a desarrollar (`product`) _required_ -* Guía de preguntas y conceptos clave (`keyConcepts`) -* Syllabus (`syllabus`) _required_ -* Evaluación (`grading`) _required_ -* Contribuidores (`contributors`) _required_ +~* Tags: (`tags`)~ _required_ +3. Syllabus (`syllabus`) _required_ +4. Requerimientos previos, si hay (`dependencies`) _required_ +~* Público objetivo (`targetAudience`)~ _required_ + + +~* Evaluación (`grading`)~ _required_ +~* Contribuidores (`contributors`)~ _required_ + +Partes adicionales: + +* Producto(s) a desarrollar (`product`) por unidades de track `ux` * Libros (`books`) * Benchmarks (`benchmarks`) * Referencias (`references`) +### Track (requerido) + +El track parece en el front-matter de Markdown. + +``` md +--- +track: ux +--- +``` + ### Título (requerido) La primera línea del `README.md` de un tópico debe contener un `h1` con el título @@ -77,20 +89,30 @@ completo. # Título del tópico ``` -### Descripción (requerido) +### Syllabus (requerido) -La descripcción del tópico es un espacio _libre_ que va desde el título hasta -la lista de `tags` o el heading de público objetivo. +El syllabus esta marcado en `h2` (`##` en Markdown) y contiene +los títulos de los unidades marcado como `h3` y con links +al directorio del unidad. -### Tags (requerido) +Opcionalmente cada titulo de unidad tiene una descripción de unidad. -... +``` md +### Unidad 01: [Tu primera página web](01-intro) +En esta unidad crearás tu primera página web. +``` + +... ## Anatomía de Unidades -Recomendamos que cada unidad empiece con una _lectura_ de **apertura** y termine -con una de **cierre**. +Los unidades son los directorios que encuentras dentro un +tópico y que contiene el contenido de partes. + + + Estructura de archivos: @@ -98,36 +120,49 @@ Estructura de archivos: 0X-topic-slug ├── 01-titulo-corto-unidad/ # unidad │   ├── 00-apertura # parte -│ |  └── README.md +│ │  └── README.md │   ├── 01-titulo-corto -│ |  └── README.md +│ │  └── README.md │   ├── 02-practice -│ |  ├── 01-un-ejercicio -│ |  ├── 02-otro-ejercicio -│ |  └── README.md +│ │  ├── 01-un-ejercicio +│ │  ├── 02-otro-ejercicio +│ │  └── README.md │   ├── 03-some-quiz │   ├── 04-ejercicios-guiados │   ├── 05-solucionario -│   ├── 06-requizz -│   └── 07-cierre +│   └── 06-cierre ├── 02-titulo-corto-unidad/ -├── 03-titulo-corto-unidad/ └── README.md ``` -TODO readme de unidades tiene estructura o solo consiste de directoriod de partes? + +Recomendamos que cada unidad empiece con una parte _lectura_ de **apertura** o +**opening** y termine con una de **cierre** o **closing**. +Por ejemplo, la unidad 01 arriba tiene `00-apertura`, `06-cierre`. ## Anatomía de una _parte_ (actividad) de una _unidad_ -Cada parte de cada unidad debe tener su propio `README.md`. La primera línea en -el `README.md` debe ser un `h1` con el título completo de la parte. +Cada parte es un directorio dentro un unidad, y debe tener +su propio `README.md`. + +El `README.md` debe tener: + +1. Tipo de parte (`type`) _required_ +2. Duración (`duration`) _required_ +3. Titulo de unidad (`title`) _required_ +4. Objetivos de aprendizaje (`learningObjectives`) _required_ +5. Contenido/cuerpo _required_ ```text + +front-matter +--- + type * + format * + duration * +--- + h1 (título) * -ul * - li (tipo) * - li (formato) * - li (duración) * h2 (objetivos de aprendizaje) ul li (objetivo de aprendizaje 1) @@ -139,52 +174,129 @@ body (el cuerpo/contenido) * obligatorio ``` -### Tipo +### Tipo, Format y Duración -#### `seminario/seminar` (deprecated/legacy) +Esta información o metadata parece en el front-matter de un parte. -Un seminario es lo más parecido a una clase presencial tradicional. Los -seminarios son _guiados_ por unx o más instructorxs. - -#### `lectura/read` +``` md +--- +type: read +format: self-paced +duration: 30min +--- +``` +Los tipos son `lectura/read`, `práctica/practice`, `cuestionario/quiz`, +`self-paced` (Leer mas de tipos y formatos.)[] + +Los formatos son self-paced y guiado (deprecated). -Las lecturas son artículos de contenido que pueden incluir videos, imágenes y -otros soprtes, embebidos o como vínculos externos. +Duración puede calcular como ... -#### `práctica/practice` +### Título (requerido) -Las prácticas principalmente ejercicios y pueden tener diferentes entornos: -`js`, `web`, `node`, ... +La primera línea del `README.md` de un parte debe contener +un `h1` con el título completo. -#### `cuestionario/quiz` +### Objetivos de Aprendizaje -Los cuestionarios a corto plazo se manejarán como links a Google Forms. Más -adelante se implementará una manera más apropiada para poder incluir en nuestro -LMS. +Una lista de puntos o breve descripción de que va a aprender en este parte. -#### `taller/workshop` (deprecated/legacy) +### Contenido de parte -Los talleres (o workshops) son sesiones guiadas o no guiadas (self-paced) -durante las cuales las alumnas realizan una actividad prolongada, como -implementación, diseño o investigación. Al final de un taller o grupo de -talleres normalmente se cierra con una demo o presentación. +Puede tener las secciones necesarias con sus propios títulos. +Por favor usa markup semantica como encabezados, listas, y links +donde correcto. -### Formato +Algunas secciones que otras partes tienen - +* Guía de preguntas y conceptos clave (`keyConcepts`) +* No se si hay otros ejemplos + +#### Sobre Tipos y Formatos + +* `seminario/seminar` (deprecated/legacy) + Un seminario es lo más parecido a una clase presencial tradicional. Los + seminarios son _guiados_ por unx o más instructoras. +* `lectura/read` + Las lecturas son artículos de contenido que pueden incluir videos, imágenes y + otros soportes, embebidos o como vínculos externos. +* `práctica/practice` + Las prácticas principalmente ejercicios y pueden tener diferentes entornos: +`js`, `web`, `node`, ... +* `cuestionario/quiz` + Los cuestionarios a corto plazo se manejarán como links a Google Forms. Más + adelante se implementará una manera más apropiada para poder incluir en nuestro + LMS. +* `taller/workshop` (deprecated/legacy) + Los talleres (o workshops) son sesiones guiadas o no guiadas (self-paced) + durante las cuales las alumnas realizan una actividad prolongada, como + implementación, diseño o investigación. Al final de un taller o grupo de + talleres normalmente se cierra con una demo o presentación. + +#### Formato Cualquiera de los _tipos_ de contenido anteriores pueden darse (o proponerse) en dos formatos: -#### `guiado/guided` (deprecated/legacy) - +* `guiado/guided` (deprecated/legacy) Los contenidos guiados son aquellos donde la _clase_ es dirigida por unx o más instructorxs. Los seminarios son siempre guiados, mientras que los talleres, lecturas o ejercicios pueden ser guiados o no. - -#### `self-paced` - +* `self-paced` Los contenidos _self paced_ (a tu propio ritmo) son aquellos que están dirigidos por las alumnas y por lo general podrían ver estas partes en su propio tiempo. En este formato, lxs instructorxs tienen el rol de acompañar, guíar y apoyar, pero son ellxs quienes dirigen la actividad. -### Duracion ? TODO como averiguar eso + +### Challenges + +Challenges composeen los partes de normalmente llaman +`practice`, `code-challenges` o `exercises`. + +```text +0X-topic-slug +├── 01-titulo-corto-unidad/ # unidad +│   ├── 00-apertura # parte +│   ├── 01-titulo-corto +│   ├── 02-practice +│ │  ├── 01-un-ejercicio # challenge +│ │ │ ├── boilerplate +│ │ │ │ └── un-ejercicio.js +│ │ │ ├── solution +│ │ │ │ └── un-ejercicio.js +│ │ │ ├── test +│ │ │ │ └── un-ejercicio.spec.js +│ │ │ └──README.md +│ │  ├── 02-otro-ejercicio +│ │  └── README.md************* // TODO describe que hace aqui? +├── 02-titulo-corto-unidad/ +└── README.md +``` + +Cada challenge es un directorio que contiene: + +1. README.md +2. directorio `boilerplate` con un archivo js que sirve + como plantilla del ejercicio +3. directorio `solution` con un archivo js que tiene el reto + resuelto +4. directorios `test` con un spec.js con pruebas para + verificar la solución + +El `README.md` explica el reto / problema con links a conceptos +para revisar. Necesitan este front matter para designarlo como +`CommonJS`. + +``` +--- +env: cjs +--- +``` + +El boilerplate contiene un archivo js que es un template de +la función o markup para resolver. La función es exportado con +un `module.exports` si es necesario. + +El spec contiene un grupo de tests que van a correr para chequear la +solución del reto. +