# 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:

```bash
pip install uv && uv sync --dev
```

2. **Test the Server**: Ensure the server runs correctly on your local machine:

```bash
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:

```bash
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:

```bash
uv add requests
```

### Adding a Development Dependency

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

```bash
uv add pytest –-group dev
```

### Remove a Dependency

To remove a package, use the `uv remove` command:

```bash
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.

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

CONFIGURED TASKS

```bash
  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.
