Versioning Policy¶

Standard versioning conventions for the Odoo 15 system.

Overview¶

This project uses Semantic Versioning (SemVer) adapted for Odoo modules.

ODOO.MAJOR.MINOR.PATCH
  │     │     │     │
  │     │     │     └── Bug fixes, small changes
  │     │     └──────── New features (backward compatible)
  │     └────────────── Breaking changes
  └──────────────────── Odoo version (always 15)

Odoo Module Versioning¶

Format¶

15.0.MAJOR.MINOR.PATCH

Segment	When to Increment
`15.0`	Fixed - matches Odoo version
`MAJOR`	Breaking changes, database migrations, removed features
`MINOR`	New features, new fields, new views (backward compatible)
`PATCH`	Bug fixes, small improvements, documentation

Examples¶

# Initial release
'version': '15.0.1.0.0',

# Added new feature (backward compatible)
'version': '15.0.1.1.0',

# Bug fix
'version': '15.0.1.1.1',

# Breaking change (requires migration)
'version': '15.0.2.0.0',

Real-World Scenarios¶

Change	Version Bump	Example
Fix typo in view	PATCH	`15.0.1.0.0` → `15.0.1.0.1`
Add new optional field	MINOR	`15.0.1.0.1` → `15.0.1.1.0`
Add new menu item	MINOR	`15.0.1.1.0` → `15.0.1.2.0`
Rename required field	MAJOR	`15.0.1.2.0` → `15.0.2.0.0`
Change field type	MAJOR	`15.0.2.0.0` → `15.0.3.0.0`
Remove feature	MAJOR	`15.0.3.0.0` → `15.0.4.0.0`

Project-Level Versioning¶

For the overall project (not individual modules), use git tags:

Format¶

v1.0.0

Tag Naming¶

Tag	Meaning
`v1.0.0`	First stable release
`v1.1.0`	New features added
`v1.1.1`	Bug fixes
`v2.0.0`	Major overhaul, breaking changes

Creating Tags¶

# Create annotated tag
git tag -a v1.0.0 -m "Release v1.0.0: Initial production release"

# Push tag to GitHub
git push origin v1.0.0

# List all tags
git tag -l

# View tag details
git show v1.0.0

When to Tag¶

Event	Action
First production deployment	`v1.0.0`
New feature set deployed	Increment MINOR (`v1.1.0`)
Bug fix release	Increment PATCH (`v1.1.1`)
Major infrastructure change	Increment MAJOR (`v2.0.0`)

CHANGELOG Management¶

File Location¶

CHANGELOG.md  (project root)

Format (Keep a Changelog)¶

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/),
and this project adheres to [Semantic Versioning](https://semver.org/).

## [Unreleased]

### Added
- New SMS retry logic in justcall_sms module

### Changed
- Updated PWA job list performance

### Fixed
- S3 upload timeout in service signature

## [1.1.0] - 2025-12-15

### Added
- MMS support for JustCall SMS
- Technician notes field in FSM orders
- New inventory report module

### Changed
- Improved error handling in REST API
- Updated documentation portal

### Fixed
- Signature upload failing for large files
- Calendar sync timezone issues

## [1.0.0] - 2025-12-01

### Added
- Initial production release
- JustCall SMS integration
- Service Signature module
- Field Service PWA
- Documentation portal

Categories¶

Category	Description
`Added`	New features
`Changed`	Changes to existing functionality
`Deprecated`	Features to be removed in future
`Removed`	Features removed in this release
`Fixed`	Bug fixes
`Security`	Security vulnerability fixes

Version Bump Workflow¶

Step 1: Update Module Version¶

Edit __manifest__.py:

{
    'name': 'My Module',
    'version': '15.0.1.2.0',  # Bumped from 15.0.1.1.0
    # ...
}

Step 2: Update CHANGELOG¶

Add entry under [Unreleased]:

## [Unreleased]

### Added
- New customer phone field in FSM orders

Step 3: Commit with Version Reference¶

git commit -m "feat(fsm): Add customer phone field

- Added phone field to fsm.order model
- Added field to form and tree views
- Version: 15.0.1.2.0"

Step 4: For Releases, Tag and Update CHANGELOG¶

# Move unreleased to version section
# Edit CHANGELOG.md:
## [1.2.0] - 2025-12-20
(move unreleased items here)

# Commit
git commit -m "chore: Release v1.2.0"

# Tag
git tag -a v1.2.0 -m "Release v1.2.0"

# Push
git push origin main --tags

Pre-release Versions¶

For testing before official release:

Alpha (early testing)¶

15.0.1.0.0-alpha.1
15.0.1.0.0-alpha.2

Beta (feature complete, testing)¶

15.0.1.0.0-beta.1
15.0.1.0.0-beta.2

Release Candidate (final testing)¶

15.0.1.0.0-rc.1
15.0.1.0.0-rc.2

Git Tags for Pre-releases¶

git tag -a v1.2.0-beta.1 -m "Beta release for v1.2.0"
git push origin v1.2.0-beta.1

Version Queries¶

Find All Module Versions¶

# List all module versions
grep -r "version" extra-addons/*/\*/__manifest__.py | grep -v ".pyc"

# Find specific module version
grep "version" extra-addons/odoo/justcall_sms/__manifest__.py

Check Git Tags¶

# List all tags
git tag -l

# List tags matching pattern
git tag -l "v1.*"

# Show commits since last tag
git log $(git describe --tags --abbrev=0)..HEAD --oneline

Compare Versions¶

# Changes between tags
git diff v1.0.0..v1.1.0

# Files changed between tags
git diff --name-only v1.0.0..v1.1.0

Best Practices¶

Do¶

Practice	Reason
Bump version on every change	Tracks what's deployed
Use consistent format	`15.0.x.x.x` for all modules
Update CHANGELOG	Documents changes for users
Tag releases	Creates restore points
Include version in commits	Easy to search history

Don't¶

Anti-pattern	Problem
Skip version bumps	Can't track what's deployed
Use dates as versions	Not semantic, hard to compare
Mix version formats	Confusing, inconsistent
Forget to tag releases	No rollback points
Leave CHANGELOG outdated	Users don't know what changed

Migration from Current State¶

The project currently has inconsistent versions. To standardize:

Phase 1: Audit Current Versions¶

# Generate version report
for f in extra-addons/*/__manifest__.py extra-addons/*/*/__manifest__.py; do
  echo "=== $f ==="
  grep "version" "$f"
done

Phase 2: Standardize Format¶

Update all modules to use 15.0.x.x.x format:

Current	Standardized
`'1.4'`	`'15.0.1.4.0'`
`'2.0'`	`'15.0.2.0.0'`
`'15.0.0.1'`	`'15.0.0.0.1'`

Phase 3: Create Initial CHANGELOG¶

Document current state as v1.0.0:

## [1.0.0] - 2025-12-12

### Added
- Initial documented release
- All existing modules standardized

Phase 4: Create Initial Tag¶

git tag -a v1.0.0 -m "Initial standardized release"
git push origin v1.0.0

Quick Reference¶

Module Version Format¶

15.0.MAJOR.MINOR.PATCH

When to Bump¶

Change Type	Bump
Bug fix	PATCH
New feature	MINOR
Breaking change	MAJOR

Commit with Version¶

git commit -m "type(scope): description

Version: 15.0.x.x.x"

Tag Release¶

git tag -a v1.2.0 -m "Release v1.2.0"
git push origin v1.2.0

Versioning Policy¶

Overview¶

Odoo Module Versioning¶

Format¶

Examples¶

Real-World Scenarios¶

Project-Level Versioning¶

Format¶

Tag Naming¶

Creating Tags¶

When to Tag¶

CHANGELOG Management¶

File Location¶

Format (Keep a Changelog)¶

Categories¶

Version Bump Workflow¶

Step 1: Update Module Version¶

Step 2: Update CHANGELOG¶

Step 3: Commit with Version Reference¶

Step 4: For Releases, Tag and Update CHANGELOG¶

Pre-release Versions¶

Alpha (early testing)¶

Beta (feature complete, testing)¶

Release Candidate (final testing)¶

Git Tags for Pre-releases¶

Version Queries¶

Find All Module Versions¶

Check Git Tags¶

Compare Versions¶

Best Practices¶

Do¶

Don't¶

Migration from Current State¶

Phase 1: Audit Current Versions¶

Phase 2: Standardize Format¶

Phase 3: Create Initial CHANGELOG¶

Phase 4: Create Initial Tag¶

Quick Reference¶

Module Version Format¶

When to Bump¶

Commit with Version¶

Tag Release¶

References¶