Contribuir a Pyzed

¡Gracias por ayudar! Esta sección es la guía de desarrollo de Pyzed: cómo compilarlo desde el código fuente, cómo está organizado, cómo añadir un componente al editor visual, cómo documentarlo y cómo editar esta web. La versión corta también está en CONTRIBUTING.md, en la raíz del repositorio.

Entorno de desarrollo

Necesitas Python 3.10+, Rust 1.88+ (rustup update actualiza una toolchain más antigua) y, en Linux, las bibliotecas de desarrollo habituales de X11/Wayland. Pyzed es una extensión de Rust (PyO3 + Iced) con un paquete de Python encima, compilada con maturin.

Con uv:

git clone https://github.com/albakore/pyzed
cd pyzed
uv sync                       # crea .venv, compila el núcleo de Rust (release) e instala pyzed editable
uv run pytest tests
uv run python examples/gallery.py
uv run pyzed design           # el editor visual, Pyzed Design

Con pip:

python -m venv .venv
source .venv/bin/activate     # Windows: .venv\Scripts\activate
pip install maturin pytest ty
maturin develop --release     # compila el núcleo de Rust e instala pyzed en el venv
pytest tests

Compila siempre con --release: las compilaciones de depuración de Iced son demasiado lentas para usar una ventana real.
En Linux, una build desde el código no suena por defecto, así que compila sin paquetes extra del sistema: pyzed.audio renderiza offline y con su reloj silencioso. Para dispositivos de audio y MIDI, instala las cabeceras de ALSA (sudo apt install libasound2-dev pkg-config; Fedora: sudo dnf install alsa-lib-devel) y compila con maturin develop --release --features alsa (con uv, deja exportado MATURIN_PEP517_ARGS="--features alsa" y ejecuta uv sync --reinstall-package pyzed-ui).
Los cambios en los archivos de Python de python/pyzed/ se aplican directamente (el paquete se instala en modo editable).
Después de cambiar código de Rust en src/, vuelve a compilar: maturin develop --release (con uv, el siguiente uv run o uv sync recompila el núcleo solo).

Comprobaciones

Ejecuta las mismas comprobaciones que la CI antes de hacer push:

cargo fmt --check             # formato de Rust
cargo clippy -- -D warnings   # lints de Rust; los avisos son errores
pytest tests                  # o: uv run pytest tests

Los tests se ejecutan sin pantalla: las ventanas se dibujan con App.screenshot en archivos PNG, así que no necesitan GPU ni display. tests/test_visual.py compara capturas con imágenes de referencia; si cambias el aspecto de un componente, regenéralas con pytest tests/test_visual.py --update-snapshots (mira Tests). Opcionales:

uv run ty check                            # comprueba los tipos del paquete de Python
python docs/scripts/gen_api.py --check     # nombres públicos sin documentación en la API

La CI ejecuta el lint, los tests en Linux, macOS y Windows, una vista previa de las notas de la versión y la comprobación del título del PR. Los cambios que solo tocan la documentación no compilan el paquete.

La web de la documentación

La documentación es una web de Astro Starlight en docs/:

cd docs
npm install
npm run dev        # http://localhost:4321/pyzed/
npm run build      # la web estática en docs/dist (lo que publica GitHub Pages)

Los dos scripts ejecutan primero scripts/sync-changelog.mjs, que convierte CHANGELOG.md en la página Novedades. Lee Editar la documentación para la estructura de la web, las traducciones y los scripts que regeneran la referencia y las imágenes.

Arquitectura del proyecto

flowchart LR
    subgraph RS["src/ (Rust, PyO3 + Iced)"]
        W["widget.rs<br/>Widget, Kind"] --> R["render.rs<br/>Kind → iced::Element"]
        A["app.rs<br/>mensajes, Command, run, screenshot"]
    end
    subgraph PY["python/pyzed/"]
        UI["ui/<br/>componentes listos"] --> CORE["pyzed._core"]
        D["designer/<br/>Pyzed Design"] --> UI
        APP["app.py, theme.py,<br/>component.py…"] --> CORE
    end
    CORE --> W

Ruta	Qué contiene
`src/`	Núcleo en Rust (PyO3 + Iced): el árbol de widgets, el puente con el renderer, el runtime y el editor de código
`python/pyzed/`	Paquete de Python: `App`, temas, iconos, `pz.Component`, CLI
`python/pyzed/ui/`	Los componentes listos para usar (`ui.button`, `ui.select`, `ui.table`…), funciones que devuelven widgets
`python/pyzed/designer/`	El editor visual: modelo del formulario, registro de la caja de herramientas, comandos del documento, runtime, paneles
`tests/`	Tests de pytest (sin pantalla ni GPU)
`examples/`	Ejemplos ejecutables y el código de los tutoriales
`docs/`	Esta web, con sus scripts generadores en `docs/scripts/`
`scripts/`	Scripts de publicación y mantenimiento

Lee Cómo funciona para el puente entre Python e Iced y Pyzed Design → Archivos, plantillas y scripts para las clases del editor.

Commits y pull requests

Pyzed sigue el estilo de FastAPI: cada commit en main, es decir, cada título de PR, empieza con un gitmoji seguido de una frase corta en imperativo, en inglés y sin punto final:

✨ Add a Rating component to the designer
🐛 Fix line numbers when the editor wraps lines
📝 Document the Rating component

Los PR se integran con Squash and merge, así que el título se convierte en el commit de main y en la línea de las notas de la versión. El emoji decide la sección de las notas:

Emoji	Úsalo para	Sección de las notas
💥	Un cambio incompatible (explícalo también en el PR)	Breaking Changes
✨	Una funcionalidad, widget o componente nuevo	Features
🐛 🚑️ 🔒️	Una corrección, un hotfix crítico, una corrección de seguridad	Fixes
♻️ ⚡️ 🎨 🔥	Refactorizaciones, rendimiento, estructura, eliminar código	Refactors
⬆️ ⬇️ 📌	Actualizar, bajar de versión o fijar una dependencia	Upgrades
📝 ✏️	Documentación, erratas	Docs
🌐	Traducciones de la documentación	Translations
✅ 👷 💚 🔧 🔨	Tests, CI, configuración, scripts de desarrollo	Internal

El workflow PR title (.github/workflows/pr-title.yml) rechaza los títulos que no empiezan con un gitmoji (o un shortcode como :sparkles:) y un espacio.

El flujo de un cambio:

Haz un fork del repositorio y crea una rama desde main (feature/rating, fix/editor-scroll, docs/tutorial-typo). Para cualquier cosa más grande que una corrección pequeña, abre antes un issue.
Mantén cada PR centrado en un solo cambio. Añade o actualiza tests para los cambios de comportamiento y documentación para los que ve el usuario.
Ejecuta cargo fmt --check, cargo clippy -- -D warnings y pytest tests.
Abre el PR con un título con gitmoji y completa la plantilla: qué cambia, cómo se probó (capturas para los cambios de interfaz) y la lista de comprobación. Enlaza el issue que cierra (Closes #123).
Sube los commits de seguimiento a la misma rama; no hace falta que los juntes tú.

Los commits deben ser de tu autoría: no añadas trailers Co-authored-by ni pies de «generado por».

Siguientes pasos

Añadir un componente al editor: de una función de pyzed.ui a una entrada de la caja de herramientas con propiedades, eventos y tests, con un ejemplo completo.
Documentar un componente: docstrings, referencia de la API, biblioteca de componentes, capturas, traducciones y el changelog.
Editar la documentación: cómo está organizada y cómo se compila esta web.
Tests: probar componentes de ui y los tests de regresión visual con sus imágenes de referencia.