# Releasing Guide

This document describes how to release a new version of OCLAWMA to PyPI.

## Prerequisites

1. You must have write access to the GitHub repository
2. The PyPI project must have trusted publishing configured with GitHub Actions

## Release Process

### 1. Update the Version

Update the version in `pyproject.toml`:

```toml
[project]
version = "0.2.0"  # Update to the new version
```

Update the version in `src/oclawma/__init__.py`:

```python
__version__ = "0.2.0"
```

### 2. Update the Changelog

Add a new section to `CHANGELOG.md`:

```markdown
## [0.2.0] - YYYY-MM-DD

### Added
- New feature description

### Changed
- Changed behavior description

### Fixed
- Bug fix description
```

### 3. Commit the Changes

```bash
git add pyproject.toml src/oclawma/__init__.py CHANGELOG.md
git commit -m "Bump version to 0.2.0"
git push origin main
```

### 4. Create a Tag

Create and push a tag matching the version:

```bash
git tag -a v0.2.0 -m "Release version 0.2.0"
git push origin v0.2.0
```

**Note:** The tag must start with `v` and match the version in `pyproject.toml` (without the `v` prefix).

### 5. Automated Release Process

Once the tag is pushed, GitHub Actions will automatically:

1. **Version Check** - Verify the tag matches the package version
2. **Build** - Create source distribution and wheel
3. **Publish to PyPI** - Upload the package using trusted publishing
4. **Create GitHub Release** - Create a release with auto-generated notes
5. **Test Installation** - Verify the package installs correctly from PyPI

### 6. Verify the Release

Check that the release was successful:

1. Visit https://pypi.org/project/oclawma/ to verify the new version is published
2. Check the GitHub releases page for the new release
3. Test installation:
   ```bash
   pip install oclawma==0.2.0
   ```

## Version Numbering

OCLAWMA follows [Semantic Versioning](https://semver.org/):

- **MAJOR** version for incompatible API changes
- **MINOR** version for new functionality (backwards compatible)
- **PATCH** version for bug fixes (backwards compatible)

Pre-release versions can be tagged with:
- `-alpha.1`, `-alpha.2` for alpha releases
- `-beta.1`, `-beta.2` for beta releases
- `-rc.1`, `-rc.2` for release candidates

Example: `v0.2.0-alpha.1`

## PyPI Trusted Publishing Setup

The project uses PyPI's trusted publishing (OIDC) instead of API tokens. This is configured in:
- PyPI Project Settings → Publishing → Add a new pending publisher
  - Owner: `openclaw`
  - Repository name: `oclawma`
  - Workflow name: `publish.yml`
  - Environment name: `pypi`

## Troubleshooting

### Version Mismatch Error

If the version check fails, ensure:
- The git tag matches the version in `pyproject.toml`
- The tag format is `v{version}` (e.g., `v0.2.0`)

### PyPI Upload Fails

If the PyPI upload fails:
- Check that the version doesn't already exist on PyPI
- Verify the trusted publisher is configured correctly
- Check the GitHub Actions logs for detailed error messages

### Installation Test Fails

If the installation test fails:
- The package may not have propagated to PyPI yet (can take a few minutes)
- The workflow retries automatically, but you can also re-run the workflow manually
