Guías de Contribución
Las guías de contribución definen cómo se integran los cambios en los repositorios de servicios de Python y esta base de conocimiento de SME: nomenclatura de ramas, expectativas de PR, reglas de revisión y CODEOWNERS, para que el mantenimiento escale más allá de un solo autor.
Receta
Tarjeta de receta de referencia rápida, lista para copiar y pegar.
## Plantilla de pull request
### Intención
### Riesgo (migración/seguridad/rendimiento)
### Evidencia de prueba (`uv run pytest path`)
### Plan de reversión
### Enlaces (RFC, ADR, ticket)# CODEOWNERS
/src/billing/ @billing-team
/docs/runbooks/ @sre-oncall
/alembic/ @billing-team @dba-reviewCuándo usar esto:
- Código abierto de una biblioteca interna
- Contribuciones externas al cookbook de SME
- Nuevos ingenieros preguntando "¿cómo hago un PR?"
- Auditoría de control de cambios
Ejemplo de Trabajo
# Flujo de trabajo del contribuyente (interno)
git checkout -b feat/ENG-550-billing-retry
uv sync
uv run pytest tests/billing -q
uv run ruff check .
git commit -m "feat(billing): backoff exponencial en errores transitorios de DB"
git push -u origin feat/ENG-550-billing-retry
# Abrir PR; completar plantilla; solicitar revisión de CODEOWNERS## Contribución al cookbook de SME (site/python/)
- Un artículo por PR cuando sea posible
- Frontmatter: etiquetas únicas, slug de sección correcto
- Ejecutar `npx tsx scripts/lint-docs.ts`
- Sin guion largo; pie de página al final
- Enlaces relativos solo a páginas existentesLo que esto demuestra:
- Puertas de calidad locales antes del PR
- El mensaje de commit vincula el dominio para herramientas de registro de cambios
- CODEOWNERS solicita automáticamente a billing + DBA para migraciones
- Las contribuciones de documentación tienen un paso de lintado explícito
Análisis Profundo
Cómo Funciona
- Nomenclatura de ramas -
feat/,fix/,chore/+ ID de ticket. - Política de revisión - Una aprobación por defecto; dos para seguridad/migraciones.
- CI requerida - pytest, ruff, pyright (rutas modificadas), compilación de imagen opcional.
- Estrategia de fusión - Fusión squash para historial lineal; SHA etiquetado en el despliegue.
- Contribuyentes externos - Fork PR; bot de CLA si es de código abierto.
Tipos de Contribución
| Tipo | Requisito adicional |
|---|---|
| Característica | Enlace a especificación si es M/L |
| Migración | Revisión de expansión-contracción |
| Dependencia | pip-audit limpio |
| Solo documentación | lint-docs en verde |
Notas de Python
# Extracto de .github/workflows/ci.yml
- run: uv sync --frozen
- run: uv run pytest
- run: uv run ruff check .Trampas Comunes
- Fusión sin revisión de CODEOWNER - Ignora la experiencia. Solución: Reglas de protección de ramas.
- PRs gigantes de última hora - No revisables. Solución: Dividir por corte vertical.
- Omitir pruebas "solo documentación" - Se envían enlaces rotos. Solución: lint-docs obligatorio.
- Push directo a main - Aumenta la tasa de fallos de CFR. Solución: Proteger main; lanzar desde etiquetas.
- Sin nota de reversión - On-call atascado. Solución: Campo de plantilla requerido para
feat/fixen servicios.
Alternativas
| Alternativa | Usar Cuándo | No Usar Cuándo |
|---|---|---|
| Commit en pareja basado en trunk | Equipo pequeño de seniors | Regulación de separación de funciones |
| Fork incluso para internos | Estilo de código abierto | Cultura de confianza en monorepo privado |
| Ramas de lanzamiento | Versiones de soporte a largo plazo | Despliegue continuo de main |
| Sin CODEOWNERS | Mantenedor único | Monorepo multi-equipo |
Preguntas Frecuentes
¿Quién puede aprobar migraciones?
CODEOWNER del servicio + grupo de revisores de DBA según la política.
¿PRs de Dependabot?
Auto-merge de parches si CI está en verde; menores revisados semanalmente.
¿Proceso de hotfix?
Crear rama desde etiqueta; PR con DoD reducido; backport a main.
¿Contribuir al cookbook?
Seguir las formas de artículo/lista de sme-content; manifestar categoría python.
¿Commits firmados?
Opcional; requerido si la política de la organización lo exige.
¿Incidencia antes del PR?
Recomendado para trabajo grande; pequeñas correcciones OK solo con PR.
¿Licencia para libs OSS?
Apache-2.0 o MIT según legal; se requiere archivo LICENSE.
¿Commits co-autorizados?
Se anima el crédito de emparejamiento; ambos revisaron el PR.
¿Política de PRs obsoletos?
Cerrar después de 30 días de inactividad; el autor reabre cuando esté listo.
¿Divulgaciones de seguridad?
Canal privado según SECURITY.md; sin incidencia pública para vulnerabilidades.
Relacionado
- Cultura de Revisión de Código - normas de revisión
- Convenciones de Documentación - PRs de documentación
- Gobernanza de Dependencias y Cadena de Suministro - PRs de dependencias
- Estándares de Codificación y Guías de Estilo - estándares de CI
- Git y GitHub - flujo de trabajo de git
Versiones de Stack: Esta página fue escrita para Python 3.14.0 (estable 3.14, mantenimiento 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, y uv 0.6+.