Esta es la Parte 3 (cierre del arco principal). Si necesitas contexto, empieza por la Parte 1 — Especificación y la Parte 2 — Versionado, changelog y pruebas sobre la separación entre @slothy/core y @slothy/angular.
Las partes 1 y 2 definieron el producto y la disciplina de release. La Parte 3 habla de personas: cómo contribuir con seguridad y cómo documentar la superficie pública para que la librería siga siendo usable.
Por qué importa la experiencia de contribución
Una librería sin una entrada clara para quien contribuye acaba con PRs improvisados, forks silenciosos o conocimiento solo interno—todo eso erosiona el contrato de la Parte 1.
Una buena contribución documentada reduce fricción para:
- Colaboradores de código abierto.
- Otros equipos de la organización que consumen
@slothy/*.
El objetivo no es burocracia, sino alineación repetible con tu arquitectura y tus reglas de versionado.
CONTRIBUTING.md — el README de onboarding
Que sea corto y accionable. Secciones típicas:
| Sección | Propósito |
|---|---|
| Requisitos | Versión de Node, gestor de paquetes (pnpm / npm), monorepo si aplica. |
| Clonar e instalar | Comandos exactos (git clone, npm ci, npm run build). |
| Flujo de desarrollo | Cómo lanzar tests, lint y docs o Storybook en local. |
| Estructura del repo | Dónde está el domain frente a los adaptadores (@slothy/core vs @slothy/angular). |
| Pull requests | Nombres de rama, checks obligatorios, alcance (un tema por PR). |
| Commits | Opcional: Conventional Commits para automatizar el changelog (Parte 2). |
Para librerías internas, replica el contenido en la wiki o el portal de docs, pero mantén la copia en el repo como fuente de verdad para quien clone el código.
Plantillas de issues — clasificar antes de codificar
Pide a quien reporta que elija bug frente a feature frente a pregunta (o documentación).
Un bug mínimo puede pedir:
- Versión del paquete (
@slothy/core/@slothy/angular). - Entorno (Node, navegador, versión de Angular).
- Reproducción (StackBlitz, repo o snippet).
- Comportamiento esperado vs real.
Una feature debería pedir:
- Qué problema resuelves (historia de usuario), no solo “añadir API X”.
Eso reduce idas y vuelvas y encaja con el MVP de la Parte 1: no toda idea debe entrar en el alcance.
RFCs para cambios grandes o incompatibles
Para cambios que afectan la API pública, varios paquetes o el comportamiento a largo plazo, usa un RFC ligero:
- Un markdown breve en
rfcs/o una GitHub Discussion: contexto, propuesta, alternativas, impacto (semver). - Un periodo de comentarios acotado (p. ej. una semana en interno, más en OSS con mucha audiencia).
- Decisión reflejada en el RFC (aceptado / sustituido) y enlazada desde el changelog al publicar.
Escala mejor que un PR gigante como único lugar de debate.
Documentación — la API como producto
TSDoc en exports públicos
Cada export de @slothy/core debería tener TSDoc (@param, @returns, @example cuando ayude). El ejemplo suele ser la forma más rápida de transmitir intención—la misma filosofía README-first de la Parte 1.
Referencia de API generada
Herramientas como TypeDoc (o API Extractor para empaquetados más estrictos) pueden convertir TSDoc en un sitio estático o en Markdown junto al README. No hace falta una plataforma enorme el primer día; hace falta un sitio que liste exports y enlace con las guías.
“Guías” frente a “API”
- Guías (tutoriales, migraciones): redactadas por personas, versionadas en el repo.
- Referencia API: generada desde tipos, regenerada en CI al release.
Navegación clara: “Primeros pasos” → “Configuración” → “Adaptador Angular” → “API”.
Seguridad y convivencia (breve)
SECURITY.md: cómo reportar vulnerabilidades (email, GitHub Security Advisories). No depender solo de issues públicos para informes sensibles.CODE_OF_CONDUCT: en comunidades open source, adopta un estándar (Contributor Covenant) y aplícalo con coherencia.
Las librerías internas también se benefician de un contacto de seguridad claro y de una política de actualización de dependencias (Dependabot).
Cómo cierra la serie la Parte 3
| Parte | Enfoque |
|---|---|
| 1 — Especificación | Qué construir y cómo empaquetarlo |
| 2 — Versionado y pruebas | Cómo evoluciona el contrato y cómo se verifica |
| 3 — Contribuidores y docs | Cómo la gente se alinea con ese contrato y encuentra las abstracciones correctas |
Cierre
Las librerías son objetos sociales: viven en el cruce entre código, documentación y expectativas. Invertir la misma exigencia en contribución y documentos que en el diseño de API es lo que mantiene usable un proyecto Slothy años después de la primera línea.
Etiquetas: código abierto, librería, TypeScript, Angular, documentación, contributing