Plantilla de CONTRIBUTING.md — Guía de Contribución

Descripción general

Una guía de contribución — por convención un archivo CONTRIBUTING.md en la raíz del repositorio — es el documento que explica a las personas cómo reportar bugs, proponer funcionalidades, enviar pull requests y cumplir los estándares de código del proyecto. GitHub lo muestra automáticamente cada vez que alguien abre un issue o un pull request, así que es el primer contrato entre el proyecto y sus contribuidores.

Este recurso te da una plantilla de CONTRIBUTING.md completa y lista para copiar, un ejemplo rellenado para ver cómo queda en la práctica, y guía para mantenedores sobre las partes que suelen salir mal: estándares no escritos, reportes de seguridad abiertos como issues públicos y guías que nadie actualiza.

Cuándo usarla

• Proyectos open-source — todo repositorio público que acepta PRs externos la necesita; GitHub la enlaza automáticamente en el formulario del PR.
• Repositorios internos — el mismo documento sirve de onboarding: los ingenieros nuevos aprenden el modelo de ramas, las reglas de lint y la etiqueta de review en una sola página.
• Tras el primer PR externo — si te pillaste explicando el flujo de trabajo en un comentario de review, esa explicación pertenece a la guía.

Si el proyecto es privado y todo el equipo ya conoce las convenciones, suele bastar una sección corta dentro del README — un archivo aparte no aporta hasta que alguien fuera del equipo núcleo empieza a contribuir.

Flujo de contribución

El camino de un contribuidor desde la idea hasta el merge se parece en casi todos los repositorios:

Todo lo que hay en la plantilla existe para mantener ese ciclo rápido: las plantillas de issue alimentan el primer paso, los estándares de código y el checklist de PR acortan las revisiones, y la sección de comunidad explica al contribuidor qué pasa después del merge.

Plantilla

Copia todo el bloque siguiente en un archivo CONTRIBUTING.md en la raíz de tu repositorio y luego reemplaza cada [placeholder] por los valores reales de tu proyecto.

# Contribuir a [Nombre del Proyecto]

¡Gracias por tu interés en contribuir! Este documento explica cómo
reportar bugs, sugerir funcionalidades y enviar cambios.

## Tabla de contenidos

- [Formas de contribuir](#formas-de-contribuir)
- [Configuración de desarrollo](#configuración-de-desarrollo)
- [Estándares de código](#estándares-de-código)
- [Proceso de pull request](#proceso-de-pull-request)
- [Reportar bugs](#reportar-bugs)
- [Sugerir funcionalidades](#sugerir-funcionalidades)
- [Vulnerabilidades de seguridad](#vulnerabilidades-de-seguridad)
- [Directrices de la comunidad](#directrices-de-la-comunidad)
- [Preguntas](#preguntas)

## Formas de contribuir

El código no es la única forma de ayudar:

- **Reportar bugs** — abre un issue con la plantilla de reporte de bug.
- **Sugerir funcionalidades** — describe el problema antes de proponer una solución.
- **Mejorar la documentación** — corrige erratas, ejemplos desactualizados o pasos confusos.
- **Clasificar issues** — reproduce reportes, añade detalles que falten o sugiere etiquetas.
- **Responder preguntas** — ayuda a otras personas en Discussions o en el issue tracker.

### Encontrar issues en los que trabajar

Busca las etiquetas `good first issue` o `help wanted` — los mantenedores las
curan para contribuidores nuevos. Comenta en un issue antes de empezar para
que nadie duplique tu trabajo.

## Configuración de desarrollo

    # 1. Haz fork del repositorio en GitHub y clona TU fork
    git clone https://github.com/[tu-usuario]/[repo].git
    cd [repo]

    # 2. Añade el repo original como upstream para sincronizar después
    git remote add upstream https://github.com/[org]/[repo].git

    # 3. Instala dependencias y verifica el entorno
    [comando de instalación]
    [comando de tests]

    # 4. Crea una rama para tu cambio
    git checkout -b feature/nombre-de-tu-feature

## Estándares de código

- Sigue las convenciones de estilo del lenguaje y framework en uso.
- Ejecuta el linter antes de hacer commit: `[comando de lint]`
- Formatea el código con: `[comando de formato]`
- Añade tests para cada funcionalidad nueva; mantén la cobertura por encima de [objetivo de cobertura]%.

### Mensajes de commit

Usamos [Conventional Commits](https://www.conventionalcommits.org/):

    feat: añade validación de email al formulario de registro
    fix: resuelve null pointer en el reintento de pago
    docs: actualiza los ejemplos de la API para endpoints v2

Firma tus commits si el proyecto requiere un DCO (`git commit -s`). Revisa
`CLA.md` o `DCO.md` en el repositorio para conocer la política — algunos
proyectos aceptan contribuciones sin ningún acuerdo formal.

## Proceso de pull request

1. Crea la rama desde `main` con prefijo `feature/`, `fix/` o `docs/`.
2. Mantén el PR enfocado — un cambio por pull request.
3. Sube a tu fork y abre un PR con la plantilla provista.
4. Enlaza el issue relacionado: escribe `Closes #123` en la descripción.
5. Espera a que pase el CI y luego atiende el feedback de los revisores.
6. Un mantenedor hace merge cuando se aprueba. Haz squash si te lo piden.

### Checklist de PR

- [ ] Tests añadidos o actualizados
- [ ] Documentación actualizada
- [ ] El linter y el formatter pasan
- [ ] Los mensajes de commit siguen la convención
- [ ] La descripción del PR explica el qué y el por qué

## Reportar bugs

1. Busca primero entre los issues existentes — los duplicados se cierran.
2. Abre un issue nuevo con la plantilla de reporte de bug.
3. Incluye pasos para reproducir, comportamiento esperado frente al real,
   detalles del entorno (SO, versión) y logs o capturas cuando aplique.

## Sugerir funcionalidades

1. Abre un issue describiendo el problema que quieres resolver, no solo la
   API que quieres añadir.
2. Espera el feedback del mantenedor antes de escribir la implementación —
   las funcionalidades grandes pueden necesitar un RFC primero.
3. Una vez acordado, sigue el proceso de pull request de arriba.

## Vulnerabilidades de seguridad

**No abras un issue público para problemas de seguridad.** En su lugar:

- Reporta en privado a través de la política `SECURITY.md` o
  [contacto de seguridad / URL del advisory].
- Incluye una prueba de concepto o pasos de reproducción cuando sea posible.
- Espera una confirmación en un plazo de [tiempo de respuesta] días.

## Directrices de la comunidad

Este proyecto sigue el [Código de Conducta](CODE_OF_CONDUCT.md). Sé
respetuoso, asume buena intención y enfoca el feedback en el código — no en
la persona.

Los contribuidores aparecen como créditos en el README o en el archivo
`CONTRIBUTORS` y en las notas de release.

## Preguntas

- Abre una Discussion para preguntas generales.
- Únete a [URL de Discord/Slack] para chat en tiempo real.
- Escribe a [email de contacto] para consultas privadas.

Ejemplo rellenado

Así quedan las primeras secciones de la plantilla una vez rellenada para una librería cliente de Python ficticia, acme/requests-toolkit:

# Contribuir a requests-toolkit

¡Gracias por tu interés en contribuir! Este documento explica cómo
reportar bugs, sugerir funcionalidades y enviar cambios.

## Configuración de desarrollo

    git clone https://github.com/tu-usuario/requests-toolkit.git
    cd requests-toolkit
    git remote add upstream https://github.com/acme/requests-toolkit.git

    python -m venv .venv && source .venv/bin/activate
    pip install -e ".[dev]"
    pytest                    # todos los tests deben pasar antes de empezar

## Estándares de código

- Estilo: black, línea de 88 caracteres, forzado por pre-commit.
- Tipado: mypy --strict en `src/`.
- Tests: un test por función pública; la cobertura debe mantenerse sobre el 90%.

### Mensajes de commit

Usamos Conventional Commits: `feat:`, `fix:`, `docs:`, `refactor:`, `test:`.
Firma tus commits (`git commit -s`) — este proyecto sigue la DCO.

## Vulnerabilidades de seguridad

Reporta en privado vía GitHub Security Advisories — nunca como issue público.
Confirmamos la recepción de los reportes en menos de 48 horas.

Secciones de la plantilla explicadas

Sección	Qué hace	Qué personalizar
Intro + Tabla de contenidos	Orienta al lector en un documento largo	Nada — déjala corta
Formas de contribuir	Amplía el embudo más allá de programadores	Tus canales reales (Discussions, foro, chat)
Configuración de desarrollo	Reproduce un entorno funcional	Comandos de install/test/lint, versiones de Node/Python
Estándares de código	Quita los debates de estilo de las reviews	Comandos de lint/formato, objetivo de cobertura, DCO vs CLA
Proceso de pull request	Marca las expectativas de revisión	Prefijos de rama, número de reviews, política de squash
Vulnerabilidades de seguridad	Mantiene los exploits fuera de issues públicos	URL del advisory o email de seguridad, SLA de respuesta
Directrices de la comunidad	Apunta a las reglas de convivencia	Enlaza tu código de conducta y contacto de moderación

Hay dos secciones que la gente olvida con frecuencia: reporte de seguridad (un issue público anunciando una vulnerabilidad es en sí mismo un incidente de seguridad) y la nota de licencia (declara que las contribuciones se aceptan bajo la licencia del proyecto — es una protección legal de una línea).

Cómo adaptar la guía a tu proyecto

Una guía de contribución debería reflejar la capacidad real del equipo que la sostiene, no la ambición del proyecto. Una guía que promete “los mantenedores revisan en 48 horas” de un equipo de dos voluntarios de fin de semana erosiona la confianza más rápido que no tener guía. Escribe las reglas que de verdad puedes cumplir y endurécelas a medida que el proyecto crece.

Tamaño del proyecto	Mantén de la plantilla	Añade	Omite por ahora
Proyecto solo / hobby	Configuración, estándares, proceso de PR, contacto de seguridad	Una nota de “lo que no aceptaré” ahorra rechazos incómodos	CLA/DCO, proceso de RFC, reglas de clasificación
Equipo pequeño (2-10)	Todo lo anterior + código de conducta	SLA de revisión, nombrado de ramas, nota sobre releases	RFCs formales, reglas de aprobación multi-mantenedor
Proyecto OSS popular	La plantilla entera	DCO o CLA, sección de clasificación dedicada, escalera de contribuidor	Nada — invierte en automatización

Etiquetas que vale la pena crear

Las etiquetas son la parte más barata de la infraestructura de contribución. Estas cubren lo que casi todo proyecto necesita desde el primer día:

Etiqueta	Propósito
good first issue	Puntos de entrada curados — la etiqueta más eficaz para atraer contribuidores nuevos
help wanted	Tareas que un mantenedor revisaría pero no puede priorizar ahora
bug / enhancement	Separa defectos de ideas de funcionalidad al clasificar
documentation	Agrupa las correcciones que no requieren código — combina con “Formas de contribuir”
needs-triage	Marca reportes a los que les faltan pasos de reproducción o detalles del entorno
breaking change	Señala PRs que requieren release major y notas de migración

Hay dos hábitos que hacen funcionar a las etiquetas: mantener good first issue con contenido (un contribuidor que la encuentra vacía asume que el proyecto está muerto) y quitarla de todo lo que deje de ser apto para principiantes — nada mata la buena voluntad como un “first issue” que exige dos semanas de contexto.

Ejemplos reales de los que aprender

Antes de publicar tu guía, mira cómo resuelven el mismo documento los proyectos grandes. Cada uno resuelve bien un problema distinto:

• Guía del contribuidor de Kubernetes — la referencia para la escala: un documento de entrada corto que deriva a docs detallados por tema. Vale copiarlo cuando tu guía desborda un solo archivo.
• CONTRIBUTING.md de Rails — el enfoque opuesto: una sola página ajustada con opiniones fuertes (qué harán y no harán merge). Buen modelo para equipos pequeños que quieren rechazar trabajo pronto.
• CONTRIBUTING.md de VS Code — la mejor sección de “Formas de contribuir” en su clase: lista primero las vías sin código y mantiene el umbral amable sin bajar los estándares.

Fíjate en lo que ninguno de ellos hace: ninguno entierra la vía de reporte de seguridad, ninguno deja los comandos de configuración ambiguos y ninguno promete tiempos de revisión que no puede cumplir. Esos tres detalles son donde la mayoría de guías de contribución fallan en silencio.

Errores comunes

• Escribir la guía una vez y no actualizarla nunca. Una guía de contribución que todavía referencia el antiguo comando de tests enseña a los contribuidores a ignorarla. Revísala con cada release, igual que el changelog.
• Estándares que solo viven en la cabeza de los revisores. Si el linter no fuerza una regla, el contribuidor no puede conocerla — documéntala o no la exijas en review.
• Un CLA que asusta a los contribuidores. Documentos legales largos presentados en el momento del PR ahuyentan a los primerizos; una DCO (git commit -s) cubre a la mayoría de proyectos. Si legal exige un CLA, dilo claramente al principio de la guía.
• Tratar todas las contribuciones igual. Una errata no necesita un RFC, pero una refactorización de 40 archivos sí. Marca el umbral de “habla con nosotros primero” para que nadie queme días en un PR rechazado.
• Sin canal de seguridad. Sin una vía de reporte privada, una vulnerabilidad aterriza en un issue público donde cualquiera puede leerla.

Solución de problemas

• Los PRs llevan semanas sin respuesta: casi siempre es un problema de capacidad del mantenedor, no del contribuidor. Responde a issues y PRs nuevos en menos de una semana, aunque sea para decir “todavía no podemos mirarlo” — el silencio mata la contribución más rápido que el rechazo.
• Los contribuidores fallan el CI una y otra vez: la sección de configuración está mal o incompleta. Reprodúcela tú mismo desde un clon limpio; si la guía dice “ejecuta los tests” pero los tests necesitan una base de datos semilla, el bug está en la guía.
• Solo recibes código, nunca clasificación ni documentación: las formas no-code de contribuir están enterradas o ausentes. Sube “Formas de contribuir” cerca del principio y etiqueta los issues de documentación explícitamente.
• Debates de estilo repetidos en las reviews: el estándar no está escrito (o no está automatizado). Pon la regla en la guía y deja que el linter diga que no — los revisores no deberían hacer de policía de estilo.
• Un contribuidor abre un PR tamaño RFC sin avisar: el umbral de “habla primero” no está claro. Decláralo explícitamente — por ejemplo, “todo cambio que toque más de 3 archivos o añada una dependencia necesita un issue antes”.

Variantes

Contexto	Enfoque	Notas
Open source	Guía pública con DCO/CLA	Incluye código de conducta y política de seguridad
Proyecto interno	Guía con flujo de CI/CD	Enfócate en estándares internos y gates de despliegue
Monorepo	Guía con reglas de alcance	Documenta qué pertenece a cada paquete
Librería / SDK	Guía con política semver	Añade una sección de comunicación de breaking changes

Lecturas recomendadas

• GitHub Docs — Establecer directrices para los contribuidores del repositorio
• Especificación Conventional Commits
• Developer Certificate of Origin (DCO)
• Código de conducta Contributor Covenant
• opensource.guide — Construir comunidades acogedoras

Ver también

• Plantilla de Pull Request — la otra mitad del flujo de contribución.
• Plantilla de Código de Conducta — el documento al que enlaza tu guía.
• Plantillas de Reporte de Bug y Solicitud de Funcionalidad — los formularios de issue que referencia la guía.
• Plantilla de README — donde suele vivir el resumen de contribución y la lista de créditos.
• Archivos listos para copiar en el repo de recursos: CONTRIBUTING.md.