Incorporación de contribuidores
Los nuevos contribuidores necesitan tres cosas: un camino (CONTRIBUTING.md), un mapa (etiquetas) y un primer paso (good first issues). Construye los tres a partir de los comandos reales del proyecto.
Cuándo usarla
- "Escribe un CONTRIBUTING.md" / "¿cómo consigo contribuidores?"
- Crear o limpiar etiquetas de GitHub
- Escribir good first issues, o prepararse para Hacktoberfest o un lanzamiento
Cuándo no usarla
- Documentos de gobierno para fundaciones (GOVERNANCE.md, charters): fuera de alcance.
- Texto de código de conducta: adopta el Contributor Covenant tal cual; no lo reescribas.
Flujo de trabajo
1. CONTRIBUTING.md
- Encuentra los comandos reales: setup (
pip install -e ".[dev]",npm ci,composer install), pruebas, lint/format, build, docs. Lee los flujos de CI; son la fuente de verdad. - Copia la plantilla y rellena cada marcador de posición. Ejecuta cada comando que documentes, o di claramente cuáles no pudiste ejecutar.
- Mantenlo escaneable: formas de contribuir (por tiempo necesario), setup, pruebas, estilo, convención de commits, proceso de PR, dónde preguntar. Enlaza CODE_OF_CONDUCT.md y SECURITY.md.
- Añade de 5 a 10 tareas concretas para principiantes bajo "Good first issues" o enlaza la etiqueta.
2. Etiquetas
scripts/ es relativo al directorio de esta skill. El script nunca llama a GitHub en sí.
python3 scripts/labels.py generate > labels.json # conjunto por defecto
python3 scripts/labels.py generate --area cli --area docs --prefixed > labels.json
python3 scripts/labels.py validate labels.json # termina con 1 si hay problemas
python3 scripts/labels.py commands labels.json --repo OWNER/NOMBRE > apply-labels.sh
Muestra al usuario apply-labels.sh y pregunta antes de ejecutarlo: crea o actualiza etiquetas en GitHub (gh label create ... --force). Nunca elimina etiquetas. Si el usuario quiere eliminar etiquetas antiguas, listalas con gh label list y confirma cada eliminación.
Mantén los nombres de GitHub good first issue y help wanted sin cambios: GitHub y sitios de terceros los usan para mostrar tareas para principiantes.
3. Good first issues
Reescribe issues candidatos siguiendo la guía. Cada uno necesita: contexto, los archivos exactos a tocar, criterios de aceptación, cómo probar y una oferta de ayuda. Pregunta antes de editar o etiquetar issues en GitHub; ofrece el texto como borrador primero.
Salida
- CONTRIBUTING.md (nuevo o actualizado) y una lista de comandos verificados vs. no verificados.
labels.jsonyapply-labels.sh(no ejecutados a menos que el usuario lo apruebe).- Good first issues redactados en Markdown, listos para pegar o para crear con
gh issue create --title ... --body-file ... --label "good first issue"tras la aprobación.
Conjunto de etiquetas por defecto
| Grupo | Etiquetas |
|---|---|
| type | bug, enhancement, documentation, question, performance, refactor |
| contributor | good first issue, help wanted |
| status | needs-triage, needs-repro, needs-info, confirmed, in-progress, blocked, stale |
| priority | priority: critical, priority: high, priority: low |
| resolution | duplicate, invalid, wontfix |
| dependencies | dependencies, security, breaking-change |
--prefixed cambia a nombres de estilo type: bug, status: needs triage. GitHub limita los nombres de etiquetas a 50 caracteres y las descripciones a 100; validate verifica ambos, además de colores hexadecimales de 6 dígitos y duplicados sin distinción de mayúsculas/minúsculas.