Development Guide

This document outlines the branching strategy and commit message guidelines for the project.
Please follow these rules to ensure smooth collaboration and maintainability.

1) Develop Project

  1. Setup Your Environment: Before you start making changes, set up your local development environment. Run:
pip install uv && uv sync --dev
  1. Test the Server: Ensure the server runs correctly on your local machine:
framex run --load-builtin-plugins echo

3、Making Changes：

  • Start Coding: Once you’ve confirmed everything is set up correctly, you can start coding. Make sure to work on a new branch created from the latest main or dev branch.
  • Validate Your Changes: After making your changes, ensure all tests pass:
poe test-all

2) How to Manage a Package with uv

To add a new package to the project, use the uv add command. This will update the pyproject.toml file and install the new dependency.

Adding a Regular Dependency

To add a package as a regular dependency, run uv add with the package name:

uv add requests

Adding a Development Dependency

To add a package to a specific group like dev, use the --group flag:

uv add pytest –-group dev

Remove a Dependency

To remove a package, use the uv remove command:

uv remove requests

Update a specific dependency package

Use the uv lock --upgrade-package <package> command. For example, to upgrade sqlmodel:

uv lock --upgrade-package sqlmodel
uv sync # or `uv sync --dev`

3) Poe Help

Use poe help to get more help.

USAGE
  poe [-h] [-v | -q] [-C PATH] [--ansi | --no-ansi] task [task arguments]

CONFIGURED TASKS

  style                 Auto-fix and format the code using ruff.
  lint                  Check for style and type violations using ruff and mypy.
  clean                 Remove all files generated by builds and tests.
  test                  Run tests quickly using the default Python environment.
  test-all              Run all tests.
  test-ci               Run ci tests.
  build                 Build source and wheel package
  tag                   Create a new version tag
  publish               Publish the package to PyPI
  release               Build source and wheel package

4) About Branches

Master (master | main)

  • The master branch is the stable version of the project.
  • It contains the official releases ready for production.
  • Only administrators are allowed to merge into master.

Development (dev)

  • The dev branch is used for day-to-day development.
  • New features and bug fixes should be merged into dev.
  • Beta versions are managed and released from the dev branch for testing before promotion to master.

Personal / Feature Branches

  • Developers should create a personal branch or feature branch:
    • Personal branch: named after the developer, e.g., username.
    • Feature branch: named with a clear prefix, e.g., feat-login, fix-bug-xxx.
  • When development is complete, submit a Pull Request (PR) targeting the dev branch for review.

5) Commit Message Guidelines

All commits must follow the format:

<tag>: <Message>

Allowed Tags

  • feat: New features
  • fix: Bug fixes
  • build: Build process or dependency changes
  • chore: Routine tasks with no code changes (e.g., configs)
  • ci: Continuous Integration / pipeline changes
  • docs: Documentation updates
  • perf: Performance improvements
  • style: Code style changes (formatting, whitespace, etc.)
  • refactor: Code refactoring without functional changes
  • test: Adding or updating tests
  • update: Minor updates or improvements

Example

feat: add support for plugin configuration loading
fix: resolve bug in cross-plugin API call
docs: update README with setup instructions

6) Versioning Rules

  • Minor version bumps

    • Triggered by commits tagged with: update.
    • Represents major feature additions, significant enhancements, or a large batch of changes.
    • Example: if the current version is 1.1.0, the next release will be 1.2.0.

  • Patch version bumps

    • Triggered by commits tagged with: feat, fix, perf, refactor, build.
    • feat: small/new feature additions.
    • fix: bug fixes.
    • perf: performance improvements.
    • refactor: internal code refactoring.
    • build: dependency/build-related adjustments.
    • Example: if the current version is 1.1.0, the next release will be 1.1.1.

Examples

  • Current version: 1.1.0
    • A commit with update: improve plugin loading speed → new version 1.2.0
    • A commit with fix: resolve proxy plugin crash → new version 1.1.1

By following these rules, the team ensures consistency, easier reviews, and automated version management.