Skip to content

Refactor CI workflows, improve typing, and enhance documentation - #12

Merged
krypton-byte merged 24 commits into
masterfrom
dev
Aug 23, 2026
Merged

Refactor CI workflows, improve typing, and enhance documentation#12
krypton-byte merged 24 commits into
masterfrom
dev

Conversation

@krypton-byte

@krypton-byte krypton-byte commented Aug 23, 2026

Copy link
Copy Markdown
Owner

This pull request makes significant improvements to CI/CD workflows, documentation deployment, and build configuration. The main changes include restructuring the GitHub Actions workflows for better reliability and maintainability, updating dependency management to use uv consistently, and optimizing the Rust build profile for performance. Several jobs and steps are consolidated or simplified, and unnecessary or redundant configuration options are removed.

CI/CD Workflow Improvements:

  • Added a dedicated tests job to .github/workflows/CI.yml, ensuring tests run separately and upstream of build jobs; all build jobs (linux, android, windows, macos, sdist) now depend on both quality and tests for improved reliability. [1] [2] [3] [4] [5]
  • Introduced a concurrency group to prevent duplicate CI runs on the same ref and removed the workflow_run trigger for simplification.
  • Updated the release job to only trigger on tag pushes, removing the conditional for workflow runs.

Dependency and Linting Consistency:

  • Standardized all uv run invocations to use the --no-project flag in both pre-commit hooks and workflow steps for consistent environment isolation. [1] [2] [3] [4]
  • Updated the release.yml workflow to install all dev dependencies via uv instead of only python-semantic-release.

Documentation Deployment Enhancements:

  • Expanded documentation deployment triggers to include the dev branch and improved deployment logic for both push and manual triggers, consolidating manual deploy logic into the main workflow and simplifying version handling. [1] [2] [3]
  • Switched to using uv run for all type checking and documentation build steps, and replaced mkdocs with zensical for doc builds. [1] [2]

Rust Build Configuration:

  • Updated the [profile.release] section in Cargo.toml to optimize for maximum runtime performance (opt-level=3, lto=fat, panic=unwind), replacing the previous size-optimized settings.
  • Clarified comments regarding feature flags and dependency choices to avoid unnecessary default features and ensure stable builds. [1] [2]

Cleanup and Simplification:

  • Removed unused workflow inputs and deleted redundant or obsolete steps from the documentation workflow, reducing maintenance overhead. [1] [2]

Let me know if you want to dive deeper into any of these changes!## Summary

Type of Change

  • feat
  • fix
  • docs
  • refactor
  • chore
  • ci/build
  • breaking change

Checklist

  • PR title follows Conventional Commits (type(scope): summary)
  • Local checks pass (ruff, formatting, stub parity)
  • Docs updated if behavior/API changed
  • Relevant tests added/updated
  • No secrets or generated build artifacts committed

Linked Issues

Notes for Reviewer

krypton-byte and others added 24 commits August 22, 2026 11:37
@krypton-byte @codebuff-team
fix(docs): remove redundant deploy_pages job
9af9ffd 
mike deploy --push already pushes to gh-pages branch directly.
The deploy_pages job (actions/deploy-pages@v4) was redundant and
only triggered on tag pushes, causing confusion.

Generated with Codebuff
Co-Authored-By: Codebuff <noreply@codebuff.com>
@krypton-byte @codebuff-team
fix(typing): make Tryx.on() decorator strictly typed
ca2b63f 
Replace Callable[..., Any] with precise type annotations:
- Tryx.on(): returns Callable[[Callable[[TryxClient, EventT], Awaitable[None]]], ...]
- Dispatcher.__call__: typed callback parameter and return
- handlers field typed as Dispatcher instead of Any
- Removed unused Any import from client.pyi

🤖 Generated with Codebuff
Co-Authored-By: Codebuff <noreply@codebuff.com>
@krypton-byte @codebuff-team
fix(typing): replace ellipsis defaults with explicit Rust-matched values
85e5dc9 
Audit against Rust #[pyo3(signature)] to fix all placeholder defaults:
- VideoFrame.orientation: ... -> 0
- AudioPlayer.__init__(buffer_frames): ... -> 3
- AudioPlayer.play(mode): str = ... -> str | None = None
- VideoPlayer.__init__(fps): ... -> 15
- client.pyi: remove duplicate AudioPlayer/VideoPlayer stubs, import from media.pyi
- events.pyi: tighten Dispatcher.__call__ return type

🤖 Generated with Codebuff
Co-Authored-By: Codebuff <noreply@codebuff.com>
@krypton-byte @codebuff-team
fix(typing): remove all Any from Dispatcher.__call__ signature
9d5177f 
Replace Callable[..., Any] with Callable[..., object] for sync callbacks.
Added docstring clarifying callback receives (client, event) args.
Removed unused Any import from events.pyi.

🤖 Generated with Codebuff
Co-Authored-By: Codebuff <noreply@codebuff.com>
@krypton-byte @codebuff-team
fix(typing): revert Dispatcher.__call__ to Any (Rust accepts any call…
c41439d 
…able)

Dispatcher.__call__ literally does push(func) with no type validation.
Any is the correct type here — the strict typing lives in Tryx.on()
which is the user-facing API with proper Callable[..., EventT] inference.

🤖 Generated with Codebuff
Co-Authored-By: Codebuff <noreply@codebuff.com>
@krypton-byte @codebuff-team
docs(typing): add PEP 257 + Google Style docstrings to client.pyi
62366c3 
Add comprehensive Google Style docstrings to all 180 methods in client.pyi
including Tryx, TryxClient, CallHandle, VoipClient, all sub-clients, and
constructor methods. Docstrings include Args, Returns, Raises, and Example
sections where applicable, based on actual Rust source code.

🤖 Generated with Codebuff
Co-Authored-By: Codebuff <noreply@codebuff.com>
@krypton-byte @codebuff-team
docs(typing): add PEP 257 + Google Style docstrings to all .pyi files
7f2f00e 
Complete Google Style docstrings across all 585 classes and methods:

- events.pyi: 45 property getters (data, source, node, proto, action)
- types.pyi: 47 property getters (source, timestamp, media_type, etc.)
- wacore.pyi: NodeValue.value()
- backend.pyi: SqliteStore.__init__() with Args/Example
- helpers.pyi: 15 static methods (build_participant, decrypt_vote, etc.)
- media.pyi: 25 source/sink methods (frames, write, play, stop, etc.)

All docstrings follow PEP 257 + Google Style with Args, Returns,
Raises, and Example sections where applicable.

🤖 Generated with Codebuff
Co-Authored-By: Codebuff <noreply@codebuff.com>
@krypton-byte @codebuff-team
docs(typing): add Example:: and Raises: to all .pyi method docstrings
182c370 
Add complete Google Style docstrings with Args:, Returns:, Raises:,
and Example:: sections to all client methods in client.pyi and
wacore.pyi. Verify exception patterns from Rust source to ensure
accurate Raises: documentation.

Co-Authored-By: Codebuff <noreply@codebuff.com>
@krypton-byte @codebuff-team
chore: update submodule and dependencies, fix Rust compilation
0d04c57 
- Update whatsapp-rust submodule to latest (1489b7da)
- Update all Cargo and Python dependencies to latest versions
- Fix PushNameUpdate -> RetiredPushNameUpdate rename in upstream
- Fix CompactString/SmallVec type conversions in types.rs

Co-Authored-By: Codebuff <noreply@codebuff.com>
@krypton-byte @codebuff-team
feat: update proto, config_json, split README, add examples
1919d22 
- Regenerate Python protobuf bindings from submodule proto (2.3000.1045368834)
- Rename connect_string -> config_json in FfiStoreProtocol (Rust + .pyi + docs)
- Update pyproject.toml protobuf version constraint to >=5.28.3,<7
- Clean up stale SIMD comments in Cargo.toml (feature removed upstream)
- Split README.md into English (README.md), Chinese (README.zh.md),
  and Indonesian (README.id.md)
- Add structured examples: basic_bot.py, media_bot.py, group_bot.py

Co-Authored-By: Codebuff <noreply@codebuff.com>
@krypton-byte @codebuff-team
perf(release): optimize release profile for maximum runtime performance
2f34106 
- opt-level = 3 (was "z"): full inlining and loop-unrolling for crypto/protocol workloads
- lto = "fat" (was true): explicit full cross-crate link-time optimization
- strip = "symbols" (was true): strip debug symbols, keep minimal info
- panic = "unwind" (was abort): MANDATORY for PyO3 catch_unwind → Python exceptions

🤖 Generated with Codebuff
Co-Authored-By: Codebuff <noreply@codebuff.com>
@krypton-byte @codebuff-team
docs: migrate to Zensical, redesign theme, rewrite all documentation …
fea2169 
…pages

- Migrate from MkDocs Material to Zensical (modern theme variant)
- Update pyproject.toml: replace mkdocs/mkdocs-material with zensical
- Redesign CSS: clean teal accent, solid borders, no glass effects
- Rewrite index.md: improved hero, feature grid, namespace table
- Rewrite installation.md: prerequisites table, build options, troubleshooting
- Rewrite quickstart.md: step-by-step with error handling patterns
- Rewrite architecture.md: source-code references, layered design explanation
- Rewrite event-model.md: comprehensive event taxonomy, handler patterns
- Rewrite type-system.md: complete type reference with examples
- Rewrite client.md: namespace router, practical flow by goal
- Rewrite command-bot.md: production patterns, idempotency, admin controls
- Enhance authentication.md: pairing flow, recovery playbook
- Enhance contributing.md: development workflow, code style guidelines
- Enhance error-handling.md: exception reference, namespace-aware patterns
- Enhance glossary.md: comprehensive term definitions
- Enhance FAQ: more questions, structured answers with code examples

🤖 Generated with Codebuff
Co-Authored-By: Codebuff <noreply@codebuff.com>
@krypton-byte @codebuff-team
fix: add CI test gate, SECURITY.md, fix typos, expand retry docs
e4159c8 
- Add pytest job to CI workflow so tests run before wheel builds
- All platform build jobs now depend on [quality, tests]
- Add SECURITY.md with vulnerability disclosure policy
- Fix typo DeviceNottificationInfo → DeviceNotificationInfo
- Fix typo PinUpdatedata → PinUpdateData
- Expand reliability.md with exponential backoff, rate limit, and
  temporary ban handling guidance

🤖 Generated with Codebuff
Co-Authored-By: Codebuff <noreply@codebuff.com>
@krypton-byte @codebuff-team
fix(docs): use zensical emoji extensions instead of material
ea23da9 
mkdocs.yml referenced material.extensions.emoji which is not installed;
replace with zensical.extensions.emoji that ships with zensical.

🤖 Generated with Codebuff
Co-Authored-By: Codebuff <noreply@codebuff.com>
@krypton-byte @codebuff-team
fix(docs): use venv for mkdocs/mike in CI workflows
843c679 
- Remove --no-project from uv run commands so they use the project
  venv where zensical and mike are installed
- Remove --system from uv pip install so packages install into venv
- Remove redundant uv pip install mike (already in docs group)

🤖 Generated with Codebuff
Co-Authored-By: Codebuff <noreply@codebuff.com>
@krypton-byte @codebuff-team
fix(docs): add pyright to dev group, use uv run in CI
9c1cb7a 
- Add pyright to dev dependency group so it's available via uv run
- Sync both dev and docs groups in docs CI workflow
- Use uv run for pyright/mypy so they resolve from the venv
- Remove redundant uv pip install step

🤖 Generated with Codebuff
Co-Authored-By: Codebuff <noreply@codebuff.com>
@krypton-byte @codebuff-team
fix(docs): skip project build in docs CI with --no-project
0d5dfd4 
uv run resolves project deps and triggers maturin build. Use
--no-project for mike/mkdocs commands so they only use the
installed venv binaries without building the Rust extension.
Sync both dev and docs groups so pyright/mypy are available.

🤖 Generated with Codebuff
Co-Authored-By: Codebuff <noreply@codebuff.com>
@krypton-byte @codebuff-team
fix(docs): replace mkdocs/mike with zensical in CI workflow
e47593b 
mike depends on mkdocs internally which can't find the 'material'
theme because zensical doesn't register as a mkdocs theme entry
point. Switch to zensical's native build and GitHub Pages deployment.

- Build with `zensical build` instead of `mkdocs build`
- Deploy with actions/upload-pages-artifact + actions/deploy-pages
- Remove mike plugin and version config from mkdocs.yml
- Remove manual_deploy job (use GitHub Pages instead)

🤖 Generated with Codebuff
Co-Authored-By: Codebuff <noreply@codebuff.com>
@krypton-byte @codebuff-team
fix(docs): add --no-project to pyright/mypy in CI
c152b28 
uv run without --no-project resolves the project and triggers
maturin build. Use --no-project for type checking tools.

🤖 Generated with Codebuff
Co-Authored-By: Codebuff <noreply@codebuff.com>
@krypton-byte @codebuff-team
fix(docs): allow workflow_dispatch to trigger deploy job
cbb4705 
🤖 Generated with Codebuff
Co-Authored-By: Codebuff <noreply@codebuff.com>
@krypton-byte @codebuff-team
fix(docs): use zensical's forked mike for versioned docs deployment
efac69c 
- Add mkdocs-material to docs dependencies (needed by mike for theme)
- Use squidfunk/mike fork that's adapted for zensical
- Add tool.uv.sources for git dependency
- Restore mike plugin + version config in mkdocs.yml
- CI uses zensical build for validation, forked mike for deploy
- Deploy to gh-pages via mike (versioned docs with dropdown)

🤖 Generated with Codebuff
Co-Authored-By: Codebuff <noreply@codebuff.com>
@krypton-byte @codebuff-team
fix(ci): resolve 6 workflow issues across CI, release, and docs
ee5182f 
- CI tests job: add --no-install-project to avoid double maturin build
- CI quality job: remove ruff version pin, use dev group version
- release.yml: replace pip install with uv sync --group dev
- docs.yml: add dev branch to push/PR triggers
- docs.yml: add Rust toolchain to validate job

🤖 Generated with Codebuff
Co-Authored-By: Codebuff <noreply@codebuff.com>
@krypton-byte @codebuff-team
fix(pre-commit): add --no-project to all uv run hooks
66c7918 
Prevents maturin build trigger on every commit.

🤖 Generated with Codebuff
Co-Authored-By: Codebuff <noreply@codebuff.com>
@krypton-byte @codebuff-team
fix(ci): tighten release workflow to prevent race conditions
552bbe6 
- Remove workflow_run trigger (was causing potential double publish)
- Remove workflow_dispatch (prevents manual publish from wrong branch)
- Add concurrency group to CI to prevent parallel runs
- Simplify release job condition to tag-push only

🤖 Generated with Codebuff
Co-Authored-By: Codebuff <noreply@codebuff.com>
@krypton-byte
krypton-byte merged commit 0a60899 into master Aug 23, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@krypton-byte