Skip to main content
Syft-Flwr follows Semantic Versioning 2.0.0 and uses Conventional Commits for automated version management.

​
Semantic Versioning

Version numbers follow the format MAJOR.MINOR.PATCH: 
v0.5.0
│ │ │
│ │ └─ PATCH: Bug fixes and small improvements
│ └─── MINOR: New features, backward compatible
└───── MAJOR: Breaking changes

​
Version Types

Patch

0.3.1 → 0.3.2
  • Bug fixes
  • Documentation updates
  • Performance improvements
  • Internal refactoring
  • No breaking changes
  • No new features

Minor

0.3.1 → 0.4.0
  • New features
  • New functionality
  • Backward compatible
  • Deprecations (with warnings)
  • No breaking changes

Major

0.3.1 → 1.0.0
  • Breaking changes
  • API changes
  • Removed deprecated features
  • Not backward compatible
  • Significant architectural changes

​
Version Bumping

Use the just bump command to increment versions: 
# For bug fixes and small improvements
just bump patch

# Example: 0.5.0 → 0.5.1

​
What Happens During a Version Bump

When you run just bump <type>, the following occurs:
1

Commitizen updates version

Uses Commitizen to:
  • Calculate the new version number
  • Update version in all configured files
  • Create a git commit with the version change
  • Create a git tag (e.g., v0.5.1)
2

Lock file updates

  • Updates main project’s uv.lock file
  • Updates notebook pyproject.toml dependency versions
  • Amends changes into the version bump commit
3

Post-publish updates

After publishing to PyPI:
  • Notebook uv.lock files are updated with the published version
  • Separate commit created for lock file updates

​
Version Files

Version numbers are automatically updated in these files:
Main project version:
[project]
name = "syft-flwr"
version = "0.5.0"
Package __version__ variable:
__version__ = "0.5.0"
Notebook dependencies:
dependencies = [
    "syft-flwr>=0.5.0",
    # other dependencies...
]

​
Conventional Commits

Syft-Flwr uses Conventional Commits for commit messages. This enables automated version bumping and changelog generation.

​
Commit Message Format

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

​
Commit Types

feat

New featureTriggers: MINOR version bump
git commit -m "feat: add model aggregation strategy"
git commit -m "feat(client): support custom data loaders"

fix

Bug fixTriggers: PATCH version bump
git commit -m "fix: resolve memory leak in training loop"
git commit -m "fix(server): handle connection timeout"

docs

DocumentationNo version bump
git commit -m "docs: update installation guide"
git commit -m "docs(api): add examples for DataOwner"

refactor

Code refactoringNo version bump
git commit -m "refactor: simplify config parsing"
git commit -m "refactor(client): extract helper functions"

test

TestsNo version bump
git commit -m "test: add integration tests for FL workflow"
git commit -m "test(unit): improve coverage for utils"

chore

MaintenanceNo version bump
git commit -m "chore: update dependencies"
git commit -m "chore(ci): optimize GitHub Actions"

perf

PerformanceTriggers: PATCH version bump
git commit -m "perf: optimize model serialization"
git commit -m "perf(training): reduce memory usage"

build

Build systemNo version bump
git commit -m "build: update build configuration"
git commit -m "build(deps): upgrade flwr to 1.25.0"

​
Breaking Changes

Breaking changes trigger a MAJOR version bump: 
git commit -m "feat: redesign client API

BREAKING CHANGE: Client initialization now requires a config object"

​
Examples

git commit -m "feat(strategy): add FedProx aggregation algorithm

Implements the FedProx federated learning strategy with configurable
proximal term coefficient."

git commit -m "fix: prevent race condition in model upload

Adds proper locking mechanism to prevent concurrent uploads
from different clients.

Fixes #123"

git commit -m "feat!: change configuration file format

Configuration now uses TOML instead of JSON for better readability
and support for comments.

BREAKING CHANGE: Existing JSON config files must be converted to TOML.
Migration script provided in scripts/migrate-config.py"

git commit -m "docs: add tutorial for custom strategies

Includes step-by-step guide with code examples for implementing
custom federated learning strategies."

​
Commitizen Configuration

Commitizen is configured in pyproject.toml:
pyproject.toml
[tool.commitizen]
name = "cz_conventional_commits"
version_provider = "pep621"
tag_format = "v$version"
update_changelog_on_bump = false
version_files = [
    "pyproject.toml:^version\\s*=\\s*\"(?P<version>.*)\"$",
    "src/syft_flwr/__init__.py:^__version__\\s*=\\s*\"(?P<version>.*)\"$",
    "notebooks/*/pyproject.toml:\"syft-flwr>=(?P<version>[^\"]+)\"",
]

​
Configuration Options

  • name: Uses conventional commits specification
  • version_provider: Reads version from pyproject.toml (PEP 621)
  • tag_format: Creates git tags like v0.5.0
  • update_changelog_on_bump: Disabled (can be enabled for automated changelogs)
  • version_files: List of files to update during version bump

​
Pre-release Versions

For alpha, beta, or release candidate versions: 
# Manually edit pyproject.toml
version = "0.6.0a1"

# Create tag
git tag v0.6.0a1
git push origin v0.6.0a1
Pre-release versions are not currently automated. They require manual version editing and tagging.

​
Version History

View version history using git: 
git tag -l "v*"

​
Best Practices

  • Patch: Bug fixes, documentation updates, performance improvements
  • Minor: New features that don’t break existing code
  • Major: Breaking changes, API redesigns, removed features
If unsure, start with a patch and upgrade to minor/major if needed.
  • Use present tense: “add feature” not “added feature”
  • Be concise but descriptive
  • Reference issues when applicable: “Fixes #123”
  • Add body for complex changes
  • Always mark breaking changes clearly
  • Don’t release too frequently (batch related changes)
  • Don’t wait too long (get fixes out quickly)
  • Consider impact on downstream users
  • Coordinate major releases with documentation updates
During 0.x.x versions:
  • Minor version bumps may include breaking changes
  • API is not yet stable
  • Major version 1.0.0 indicates stable API
Once at 1.0.0, strictly follow semantic versioning.

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us