Los Componentes Mumuki
¡Hola! Esta es la documentación de los Componentes Mumuki, un ecosistema de piezas de software libre diseñado para construir herramientas educativas basadas en tres principios:
- aprendizaje y práctica mediante explicaciones interactivas y resolución de ejercicios de complejidad incremental;
- generazión de contenido didáctico, estructurado en términos de libros, capítulos, lecciones y ejercicios;
- seguimiento de estudiantes, en contextos de cursos presenciales, semipresencial o virtuales
Este ecosistema presenta una arquitectura híbrida en torno a bibliotecas, aplicaciones HTTP y frameworks para el lenguaje Ruby. Además tiene excepcional soporte para ejercicios de programación y pensamiento computacional, al posibilitar la ejecución y evaluación de código, provisto en parte por la herramienta Mulang, desarrollada en Haskell.
Los componentes son desarrollados por el Proyecto Mumuki y una comunidad docente y programadora, y son la base de la Plataforma Mumuki.
- Licencias
- Reportando errores
- Arquitectura
- Componentes principales
- Comenzando a desarrollar
- Requerimientos Mínimos
- Contribuyendo
Licencias
Todo el código (incluida esta misma documentación) se encuentra bajo la organización Github Mumuki, distribuido bajo licencias libres GPL versión 3 o bien MIT, según el componente.
Por otro lado, el contenido, también libre y distribuido bajo licencia CC BY-SA, se encuentra distribuido a lo largo de varias organizaciones Github, como MumukiProject, sagrado-corazon-alcal, pdep-utn, 10pines-mumuki entre otras.
Reportando errores
Finalmente, esta documentación, al igual que la Plataforma Mumuki y el Proyecto Mumuki, se encuentra en continuo crecimiento.
Es probable que encuentres errores y omisiones; en tal caso no dudes en comunicarte con nosotros a través de nuestra cuenta info@mumuki.org, de nuestro grupo devs@mumuki.org, o de nuestras cuentas en Facebook y Twitter
Arquitectura
Los cuatro servicios principales el ecosistema Mumuki están modelados como Engines para el framework Web Ruby on Rails
- Laboratorio (
mumuki-laboratory): provee funcionalidades de code-assesment que permite a un estudiante acceder a explicaciones y ejercicios, e interactuar con ellos a través del envío de soluciones a problemas - Biblioteca (
mumuki-bibliotheca-api): es un repositorio headless de contenido didáctico (guías, ejercicios, capiítulos, libros), capaz de replicar dichos contenidos en repositorios GIT. - Aula (
mumuki-classroom-api): es una herramienta headless de seguimiento de estudiantes que permite a los docentes de un curso navegar las soluciones de sus estudiantes, obtener estadísticas y proveer feedback manual. - Dominio (
mumuki-domain): modelo de dominio y persistencia del ecosistema Mumuki
Estos tres componentes interactuan entre sí a través de tres medios de comunicación:
- Colas de mensajes
- APIs REST y WebHooks
- Tokens JWT provistos
Y todo esto se apoya en:
- Bibliotecas (
mumukit-*): gemas reutilizables ruby (gems) que proveen funcionalidades comunes a toda la platorma - Runners (
mumuki-*-runner): servidores http (también distribuidos mediante gemas) que permiten la ejecución de código - Mulang, un ejecutable de línea de comando que permite realizar el análisis de código.
Componentes principales
Biblioteca (bibliotheca-api)
Es un servidor HTTP escrito en Ruby. Utiliza como motor de persistencia una base de datos Mongo. La sincronización con un repositorio GIT es opcional, configurable mediante variables de entorno. Expone sus operaciones mediante un API REST.
La interfaz grafíca de la biblioteca (Editor) es una aplicación de cliente pesado escrita utilizando el framework para SPA (Single Page Applications) Angular.js
Ateneo (laboratory)
Es el servicio más visible: una plataforma web de autoestudio que presenta al estudiante ejercicios para que resuelva, y corrige automáticamente utilizando runners. Está desarrollada en Ruby, utilizando el framework Rails.
Aula virtual (classroom-api)
:warning: TODO
Analizador de código (mulang)
A diferencia de los componentes anteriores, mulang, es un ejecutable y está desarrollada en Haskell.
Bibliotecas (gemas)
Todas nuestras bibliotecas (gemas de ruby, todas publicadas en rubygems siguiendo estricto versionado semántico) tienen el prefijo mumukit
- mumukit: la biblioteca original. Para ser justos, se trata de un framework, pensado para implementar runners de forma muy fácil (y cuando decimos muy fácil, queremos decir que dar soporte a un lenguaje nuevo es tarea de un día de trabajo)
- mumukit-core: extensiones a active-support, que en tanto son extensiones al lenguaje ruby.
- mumukit-nuntius: manejo de colas de mensajes RabbitMQ, de forma que sea muy fácil para cualquier servicio enviar mensajes asincrónicos y confiables a otros servicios.
- mumukit-bridge: manejo de comunicación hacia los runners via HTTP. A diferencia de los mensajes que se envían a través de nuntius, los mensajes que se intercambian con los runners son sincrónicos y no confiables.
- mumukit-inspection
- mumukit-directives
- mumukit-content-type
Runners
Los runners son componentes que capaces de ejecutar y probar porciones de código en un cierto lenguaje.
- Son componentes 100% stateless.
- Por motivos de seguridad, la mayoría de ellos ejecutan el código del usuario dentro de un sandbox, creado mediante un contenedor Docker instanciado ante demanda.
- Exponen sus funcionalidades mediante HTTP
- Exponente tres endpoints principales:
/test: permite probar el código, lo cual normalmente involucra los siguientes pasos:- ejecutar pruebas unitarias
- disparar el análisis de código (típicamente, mediante Mulang)
- Proveer feedback (esto es, analizar los resultados del compilador/intérprete del lenguaje y proveer al usuario una descripción más amena del error e indicios de solución)
/query: permite ejecutar consultas, de forma similar a cómo lo hace un intérprete interactivo/info: provee información introspectiva sobre el runner: su versión, información de ambiente, versiones del lenguaje y framework de test que ejecuta, íconos, editores ACE recomendados, etc.
Contribuyendo
Para contribuir al desarrollo de la Plataforma Mumuki sólo necesitás una cuenta en Github y las ganas de ayudarnos. No importa si sos una programadora Ruby, un diseñador Web o un docente que tiene propuestas de mejoras: todo suma.
Hay dos formas fundamentales de colaborar: subiendo pedidos de cambios y mejoras (issues), o haciendo commits.
Subiendo issues
Subir issues es fácil, aunque a veces puede no ser obvio en qué repositorio github subirlo:
- Si es un issue general sobre las herramientas docentes (ya sea el editor o el aula virtual), subilo a mumuki/mumuki-teacher-tools
- Si es un issue general sobre la plataforma, o particular de la herramienta de autoestudio, subilo a mumuki/mumuki-laboratory.
- Si es un issue sobre el contenido didáctico, subilo al repositorio correspondiente. Por ejemplo, si querés subir uno sobre (la lección de Mixins y Autoclases en Ruby)[http://mumuki.io/lessons/127-metaprogramacion-mixins-y-autoclases], hacelo acá.
¡Y prestá atención a las guías de contribución específicas de cada proyecto! Ya Github te las senñalará cuando subas un issue :wink:
Commiteando
El proceso para contribur con aportes de código es simple:
- Forkea el proyecto desde Github (usando el botón Fork que está en la esquina superior derecha) y clonalo en tu computadora de trabajo
- Creá un branch por tema (feature branch) (git checkout -b my-new-feature)
- Comiteá tus cambios your changes
git commit -am 'Add some feature' - Hacé push al branch (git push origin my-new-feature)
- Hacé un nuevo Pull Request, desde el branch en tu fork hacia master en el repositorio de mumuki.
La idea de trabajar con Pull Requests es que sea fácil que cualquiera pueda proponer un cambio o mejora; si bien se pueden hacer PRs desde branches de los proyectos en la organización mumuki, eso implica tener que darle permisos especiales de collaborator a cada contribuidor, por cada repositorio, lo cual es lento, burocrático, y si no se tiene cuidado, un riesgo de seguridad. Por eso es que te pedimos hacer tu propio fork.