diff --git a/RELENG.md b/RELENG.md new file mode 100644 index 0000000..f564ecf --- /dev/null +++ b/RELENG.md @@ -0,0 +1,142 @@ +# Chainlit Community Release Engineering Guide + +## Version Management Strategy + +### Monorepo Versioning with Hatch +- **Hatch-managed versions** using dynamic source from `__init__.py` +- Configure per-package in `pyproject.toml`: + ```toml + [tool.hatch.version] + source = "regex" + path = "src/chainlit_/__init__.py" + pattern = '^__version__ = "(.+)"$' + ``` + +### Version Bumping Protocol +For each package (e.g. `chainlit-sqlalchemy`): +```bash +# Bump specific version +hatch version 1.2.3 + +# Semantic increments +hatch version minor # 0.1.0 → 0.2.0 +hatch version micro # 0.1.0 → 0.1.1 +hatch version major,rc # 1.0.0 → 2.0.0rc0 +hatch version release # 2.0.0rc0 → 2.0.0 +``` + +## Package Release Process + +### Pre-Release Validation +1. Verify workspace integrity: + ```bash + uv sync --all-packages + uv run pip check + ``` + +2. Run full test matrix: + ```bash + ./scripts/ci.sh + ``` + +### Build Process Updates +```bash +# Ensure Hatch recognizes dynamic version +uv pip install hatch + +# Build with version from Hatch +uv build --no-sources --strict \ + --exclude-extras all \ + --build-constraint ../../constraints.txt +``` + +Key flags: +- `--no-sources`: Ignore workspace sources +- `--strict`: Fail on dependency resolution issues +- `--exclude-extras`: Build base package only + +### Publishing Workflow +1. Configure credentials: + ```bash + export UV_PUBLISH_TOKEN="pypi-xxxxxxxx" + ``` + +2. Dry run validation: + ```bash + uv publish --dry-run --strict \ + --index-url https://upload.pypi.org/legacy/ + ``` + +3. Publish package: + ```bash + uv publish --no-sources --strict \ + --index-url https://upload.pypi.org/legacy/ + ``` + +4. Verify publication: + ```bash + uv pip install --force-reinstall chainlit-sqlalchemy==1.2.3 + uv run python -c "from chainlit_sqlalchemy import __version__; print(__version__)" + ``` + +## Workspace Management + +### Cross-Package Dependencies +When package A (e.g. `pytest`) depends on package B (e.g. `sqlalchemy`): +1. Release dependency first: + ```bash + uv publish -p packages/data_layers/sqlalchemy + ``` + +2. Update dependent package constraints: + ```toml + # packages/pytest/pyproject.toml + dependencies = [ + "chainlit-sqlalchemy>=1.2.3,<2.0.0" + ] + ``` + +### Batch Publishing +Publish all modified packages: +```bash +uv publish --workspace \ + --index-url https://upload.pypi.org/legacy/ \ + --strict +``` + +## Security & Compliance + +### PyPI Configuration +```toml +# Single token in root .env +UV_PUBLISH_TOKEN="pypi-xxxxxxxx" +``` + +### Dependency Pinning +Maintain `constraints.txt` in root: +```bash +uv pip compile requirements.txt --output-file constraints.txt \ + --generate-hashes --no-sources +``` + +## Post-Release Actions + +1. Tag releases with package prefixes: + ```bash + git tag sqlalchemy/v1.2.3 -m "chainlit-sqlalchemy 1.2.3" + git push origin sqlalchemy/v1.2.3 + ``` + +## Troubleshooting + +Common Issues | Resolution +---|--- +`BuildError: Missing build dependency` | `uv pip install "setuptools>=65" --resolution=lowest-direct` +`PublishError: Invalid API token` | Verify token has `pypi-` prefix and package scope +`VersionConflict` | Run `uv sync --all-packages --upgrade` +`FileExistsError` | Remove `dist/` and `build/` directories before rebuilding + +--- + +[uv Publishing Reference](https://docs.astral.sh/uv/guides/publish/) | +[PEP 440 Spec](https://peps.python.org/pep-0440/) diff --git a/packages/data_layers/sqlalchemy/src/chainlit_sqlalchemy/__init__.py b/packages/data_layers/sqlalchemy/src/chainlit_sqlalchemy/__init__.py index af0f822..29075d8 100644 --- a/packages/data_layers/sqlalchemy/src/chainlit_sqlalchemy/__init__.py +++ b/packages/data_layers/sqlalchemy/src/chainlit_sqlalchemy/__init__.py @@ -1,3 +1,4 @@ +__version__ = "0.1.0" from .data_layer import SQLAlchemyDataLayer __all__ = ["SQLAlchemyDataLayer"] diff --git a/packages/storage_clients/s3/pyproject.toml b/packages/storage_clients/s3/pyproject.toml index 93bb565..7bd0282 100644 --- a/packages/storage_clients/s3/pyproject.toml +++ b/packages/storage_clients/s3/pyproject.toml @@ -19,5 +19,12 @@ dev = [ pytest-chainlit = { workspace = true } [build-system] -requires = ["hatchling"] +requires = ["hatchling", "hatch-regex-commit"] build-backend = "hatchling.build" + +[tool.hatch.version] +source = "regex_commit" +path = "src/chainlit_sqlalchemy/__init__.py" +pattern = '^__version__ = "(.+)"$' +commit_message = "chore(sqlalchemy): bump version {current_version} → {new_version}" +tag_name = "sqlalchemy/v{new_version}" diff --git a/pyproject.toml b/pyproject.toml index 0d3770a..1e398d8 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -33,6 +33,7 @@ dev = [ "pytest>=8.3.4", "ruff>=0.8.3", "pre-commit>=4.1.0", + "hatch>=1.9.1", ] [tool.pytest.ini_options]