# Managing Python Releases

> Gestiona lanzamientos de librerías Python: versionado semántico, changelog (Keep a Changelog), automatización con GitHub Actions y deprecaciones. Úsalo al planificar lanzamientos, escribir changelogs o comunicar breaking changes.

Fuente: https://skillsagentes.com/skills/kajisho5/ffmpeg-skill/managing-python-releases
Markdown: https://skillsagentes.com/skills/kajisho5/ffmpeg-skill/managing-python-releases.md

Repositorio: https://github.com/kajisho5/ffmpeg-skill
Autor: kajisho5
Licencia: MIT
Actualizado: hace 5 días
Coste de contexto: 73 tok instalada, 1.1k tok al activarse, 1.1k tok con todos los archivos del bundle
Bundle: 1 archivo, 4 KB
Permisos que pide: ninguno declarado

## Instalación

Un skill son archivos markdown: los mismos archivos valen para cualquier agente y lo único que cambia es el directorio de destino, es decir la bandera `--agent`. Añade `-g` para instalarlo en todos los proyectos de la máquina.

```bash
# Claude Code
npx -y skills add kajisho5/ffmpeg-skill --skill release-management --agent claude-code
# Cursor
npx -y skills add kajisho5/ffmpeg-skill --skill release-management --agent cursor
# Codex
npx -y skills add kajisho5/ffmpeg-skill --skill release-management --agent codex
# Gemini CLI
npx -y skills add kajisho5/ffmpeg-skill --skill release-management --agent gemini
# Windsurf
npx -y skills add kajisho5/ffmpeg-skill --skill release-management --agent windsurf
# Cline
npx -y skills add kajisho5/ffmpeg-skill --skill release-management --agent cline
```

## Qué hace

- Te guía en la elección del número de versión según el versionado semántico (MAJOR.MINOR.PATCH).
- Mantiene el changelog en formato Keep a Changelog con sus categorías: Added, Changed, Deprecated, Removed, Fixed, Security.
- Automatiza el lanzamiento de una release con GitHub Actions, incluyendo la publicación por trusted publishing.
- Aplica el proceso de deprecación con warnings y stacklevel=2, y revisa el checklist pre y post release.

## Cuándo usarla

- Cuando planifiques una release de una librería Python.
- Al escribir o actualizar un changelog en formato Keep a Changelog.
- Cuando quieras automatizar el pipeline de publicación con GitHub Actions.
- Para comunicar cambios incompatibles o deprecar funciones.

## Qué la activa

- "Ayúdame a planificar la release 1.4.0 de mi librería Python."
- "Pasa mi changelog al formato Keep a Changelog."
- "Crea un workflow de GitHub Actions que publique en PyPI al hacer push de un tag."
- "¿Cómo deprecar una función para que el warning apunte a quien la llama?"
- "Prepárame el checklist de lanzamiento de la versión 2.0.0."

## Antes de instalar

- Requiere un repositorio Git; para el flujo automatizado, GitHub Actions y acceso al registro de paquetes (PyPI, npm, etc.).
- Necesita en el PATH: git
- makes network requests

## Archivos

- SKILL.md — 4 KB

## SKILL.md

Reproducido tal cual desde kajisho5/ffmpeg-skill bajo MIT. Esta sección es el documento original y está en inglés.

# Release Management

## Semantic Versioning

```
MAJOR.MINOR.PATCH (e.g., 1.2.3)

PATCH: Bug fixes, no API changes
MINOR: New features, backward compatible
MAJOR: Breaking changes
```

## Changelog Format (Keep a Changelog)

```markdown
# Changelog

## [Unreleased]
### Added
- New `batch_encode()` function

## [1.2.0] - 2024-03-15
### Added
- Support for custom formats (#123)

### Fixed
- Edge case at -180 longitude (#145)

### Deprecated
- `old_function()` - use `new_function()` instead

[Unreleased]: https://github.com/user/repo/compare/v1.2.0...HEAD
[1.2.0]: https://github.com/user/repo/releases/tag/v1.2.0
```

**Categories:** Added, Changed, Deprecated, Removed, Fixed, Security

## Version in Code

```python
# src/package/__init__.py
__version__ = "1.2.3"

# Or use importlib.metadata
from importlib.metadata import version
__version__ = version("my-package")
```

## GitHub Actions Release (PyPI example)

A tag-triggered workflow builds and publishes to a registry via trusted
publishing (no stored token) is the general shape — swap the publish step for
whatever registry the project actually uses (PyPI, npm, crates.io, ...):

```yaml
# .github/workflows/release.yml
on:
  push:
    tags: ['v*']

jobs:
  release:
    runs-on: ubuntu-latest
    permissions:
      contents: write      # create the GitHub release
      id-token: write      # trusted publishing (no token)
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v5
      - run: uv build
      - uses: softprops/action-gh-release@v2
        with:
          files: dist/*
      - uses: pypa/gh-action-pypi-publish@release/v1
```

## Deprecation Process

Warn with `stacklevel=2` so the message points at the caller.

```python
import warnings

def old_function():
    """Deprecated: Use new_function() instead."""
    warnings.warn(
        "old_function() deprecated, will be removed in 2.0.0",
        DeprecationWarning,
        stacklevel=2,
    )
    return new_function()
```

## Release Process

```bash
# 1. Update CHANGELOG.md (move Unreleased to version)
# 2. Bump version in the project manifest
# 3. Commit and tag
git commit -am "Release v1.2.0"
git tag -a v1.2.0 -m "Release v1.2.0"
git push origin main --tags
# 4. CI publishes automatically (if automated) or publish manually
```

## Checklist

```
Before Release:
- [ ] All tests pass
- [ ] CHANGELOG updated
- [ ] Version bumped
- [ ] Documentation current

After Release:
- [ ] Registry shows new version
- [ ] A fresh install actually works (not just that the tag/publish succeeded)
- [ ] GitHub release created
- [ ] Docs updated
```

## Note for this repository (ffmpeg-skill)

`CHANGELOG.md` here already follows Keep a Changelog's dated-section format
(`## 0.10.0 — 2026-09-06 — ...`), so the format guidance above matches this
repo exactly. Two real differences from the generic PyPI example:

- **No automated release workflow exists.** There is no
  `.github/workflows/release.yml` — the 0.10.0 release this session did every
  step by hand: bump `package.json`'s `version`, convert the CHANGELOG's
  `## Unreleased` into a dated section, `git tag`, create the GitHub Release,
  then `npm publish` separately. This is exactly the gap `managing-python-releases`
  is meant to close with automation — worth considering if releases become
  frequent enough that a manual miss (like 0.9.2 sitting un-published to npm
  for a while, discovered this session) becomes a recurring problem.
- **The registry is npm, not PyPI**, and there is no `__version__` in code —
  `scripts/_contract.py`'s `skill_version()` and `doctor`'s `version` field
  both read `package.json` directly (see this repo's own `concurrent-branches`
  and `build-artifacts` skill notes for the related merge-conflict and
  publish-verification patterns this touches).

Source: [wdm0006/python-skills](https://github.com/wdm0006/python-skills) (MIT).

## Dónde encaja

- Categoría: [Herramientas para desarrolladores](https://skillsagentes.com/categorias/herramientas-desarrollo.md) — Skills que cambian cómo tu agente escribe, revisa y despliega código.
- Creador: [kajisho5](https://skillsagentes.com/creators/kajisho5.md) — 0 skills en el directorio
- [Todas las skills](https://skillsagentes.com/skills.md)
- [Ranking de instalaciones](https://skillsagentes.com/ranking.md)

## Otras skills del mismo repositorio

- [Ffmpeg Skill](https://skillsagentes.com/skills/kajisho5/ffmpeg-skill/ffmpeg-skill.md): Edita vídeo y audio con FFmpeg local desde lenguaje natural: cortes, unión, reframe 9:16/1:1, velocidad, subtítulos, overlays, multicámara/sync, LUFS, HDR→SDR, LUTs, export y verificación. Python 3.9 stdlib, sin nube ni API keys.
- [Concurrent Branches](https://skillsagentes.com/skills/kajisho5/ffmpeg-skill/concurrent-branches.md): Resuelve conflictos de merge con varias ramas abiertas: unión, recomputación y reconstrucción como resoluciones correctas; artefactos generados, serialización no determinista e IDs renumerados; un auto-merge limpio no es un test que pasa.
- [Ci Pipeline Synthesizer](https://skillsagentes.com/skills/kajisho5/ffmpeg-skill/ci-pipeline-synthesizer.md): Genera configuraciones de CI/CD para GitHub Actions: compilación y pruebas de librerías y paquetes. Úsalo al crear o actualizar workflows de npm, Python, Go o Rust con caché de dependencias, pruebas en matriz y publicación de artefactos.
- [Guarding Destructive Operations](https://skillsagentes.com/skills/kajisho5/ffmpeg-skill/guarding-destructive-operations.md): Guarda operaciones destructivas: borrados, sobrescrituras, reescritura de historial o resolución de nombres a rutas; rechaza en vez de avisar, comprueba antes de mutar, clasifica por estructura y prueba cada mitad.
- [Building Python Mcp Servers](https://skillsagentes.com/skills/kajisho5/ffmpeg-skill/building-python-mcp-servers.md): Crea servidores MCP robustos en Python con FastMCP: diseño de herramientas, contratos de error, trabajo bloqueante, subprocesos/CLI, distribución, pruebas e inyección de prompts. Úsalo al escribir, exponer, depurar o probar servidores MCP.

## Skills relacionadas

- [Building Python Mcp Servers](https://skillsagentes.com/skills/kajisho5/ffmpeg-skill/building-python-mcp-servers.md): Crea servidores MCP robustos en Python con FastMCP: diseño de herramientas, contratos de error, trabajo bloqueante, subprocesos/CLI, distribución, pruebas e inyección de prompts. Úsalo al escribir, exponer, depurar o probar servidores MCP.
- [Concurrent Branches](https://skillsagentes.com/skills/kajisho5/ffmpeg-skill/concurrent-branches.md): Resuelve conflictos de merge con varias ramas abiertas: unión, recomputación y reconstrucción como resoluciones correctas; artefactos generados, serialización no determinista e IDs renumerados; un auto-merge limpio no es un test que pasa.
- [Guarding Destructive Operations](https://skillsagentes.com/skills/kajisho5/ffmpeg-skill/guarding-destructive-operations.md): Guarda operaciones destructivas: borrados, sobrescrituras, reescritura de historial o resolución de nombres a rutas; rechaza en vez de avisar, comprueba antes de mutar, clasifica por estructura y prueba cada mitad.
- [Keeping Git Repos Clean](https://skillsagentes.com/skills/kajisho5/ffmpeg-skill/keeping-git-repos-clean.md): Previene, detecta y corrige la subida a git de secretos (.env, API tokens, credenciales) y artefactos dev (builds, BD de trabajo, editor/SO). Cubre .gitignore (por qué no deja de trackear), git rm --cached, auditoría, historial y rotación.
- [Reproducing Ci Locally](https://skillsagentes.com/skills/kajisho5/ffmpeg-skill/reproducing-ci-locally.md): Reproduce el gate de CI en local a partir del workflow: comando, rutas, marcadores y entorno exactos; desbloquea pasos cortocircuitados, fija la versión del linter que resuelve CI y confirma que el run es verde.

---

Skills Agentes · [Índice de páginas en markdown](https://skillsagentes.com/sitemap.md) · [Inicio](https://skillsagentes.com/index.md)