version-bump

name	version-bump
description	Bump a version in the OpenAlgo repo. Use when releasing a new OpenAlgo platform version, or when updating the pinned openalgo Python SDK dependency. These are two independent version numbers that live in different files and are frequently confused.

Version bumping

There are two independent versions in this repo. Identify which one is being asked for before editing anything.

Ask	Version	Source of truth
"Release OpenAlgo 2.0.2", "bump the platform version"	Platform	utils/version.py
"Update the SDK", "new openalgo on PyPI", "bump openalgo to 1.0.50"	SDK pin	dependency lists

They are unrelated and never move together. If the request is ambiguous, ask.

1. Platform version (e.g. 2.0.1.0)

OpenAlgo itself. Touches two files plus the lockfile. Never touch requirements.txt or requirements-nginx.txt for a platform bump - the platform version does not appear there.

1. utils/version.py - VERSION = "x.y.z.w" (runtime source of truth, read by get_version())
2. pyproject.toml - version = "x.y.z.w" (line 4, package metadata)
3. uv sync to regenerate uv.lock

# Example: 2.0.1.0 -> 2.0.1.1
# 1. Edit utils/version.py      -> VERSION = "2.0.1.1"
# 2. Edit pyproject.toml line 4 -> version = "2.0.1.1"
uv sync

# Verify
uv run python -c "from utils.version import get_version; print(get_version())"
# -> 2.0.1.1

Both files must agree. utils/version.py is what the running app reports; pyproject.toml is what packaging and CI read. A mismatch means the UI footer and the Docker tag disagree.

The platform version surfaces in the UI footer / about page (via get_version()), API responses carrying version metadata, and Docker image tags built by CI.

Release notes are part of the bump, not a follow-up

A platform bump is only half a release. Every recent release commit also adds a notes file - the last one was literally titled "bump platform to 2.0.1.6 and add release notes" and touched four paths:

utils/version.py
pyproject.toml
uv.lock
docs/releases/version-2.0.1.6-released.md      <- the user-facing half

Create docs/releases/version-<x.y.z.w>-released.md following the existing files in that directory. The established structure:

1. # Version <x.y.z.w> Released and **Date: <Nth Month Year>**
2. A one-paragraph bold summary naming the release theme
3. A prose overview stating the commit count since the previous tag and what changed at a system level
4. **Highlights** - a bullet per significant change, each citing its commit SHA (and issue number where one exists), e.g. **HDFC Sky broker integration (cb4ec7d56 + 9 follow-up fixes)** - ...
5. **Dependencies** - what moved, or an explicit "no dependencies changed"
6. **Contributors** - see below. Never optional.
7. **Links** - repository, docs, PyPI, Discord, YouTube, issue tracker

Get the commit range with:

git log --oneline v<previous>..HEAD | wc -l        # commit count for the summary
git log --oneline v<previous>..HEAD                # source material for highlights

If no tags exist, diff against the previous release notes file's date.

Always credit every contributor

Every release credits everyone who contributed to it, with no exceptions. Contributors go in all three places, not just one:

1. the release notes file, as a **Contributors** section
2. the docs/CHANGELOG.md stanza, as a ### Contributors section
3. the GitHub release body

Format is one bullet per person: **@handle (Real Name)** - what they did, with PR or issue numbers. Use the real name only where the commit or profile gives one; **@handle** alone is correct otherwise. Order by volume of work, with the maintainer first. Do not silently fold a contributor's work into someone else's bullet, and do not omit a docs-only or test-only contribution.

Collect the list from git rather than from memory:

git log --format='%an <%ae>' <previous>..HEAD | sort | uniq -c | sort -rn
git log --format='%b' <previous>..HEAD | grep -i '^Co-authored-by:' | sort -u
git log --format='%h|%an|%s' <previous>..HEAD | grep -vE 'github-actions'

Author names are not GitHub handles, and the credit needs the handle. Resolve each one:

gh pr view <PR> --json author -q .author.login       # commits merged via a PR
gh api repos/marketcalls/openalgo/commits/<sha> -q .author.login   # direct pushes

Exclude github-actions[bot] (the auto-build frontend dist commits) and the Co-authored-by: Claude ... trailers.

docs/CHANGELOG.md gets a stanza per release

Every release adds a ## [x.y.z.w] - YYYY-MM-DD stanza at the top, above the previous one, following the shape the existing stanzas use: a ### <Theme> Release heading, the commit count and a link to the full notes, then ### Highlights, the grouped fix sections that fit this release, ### Dependencies and ### Contributors. The stanza is a summary; the release notes file is where the detail lives.

Order of work

1. utils/version.py and pyproject.toml
2. uv sync
3. Collect the commit range and resolve every contributor's GitHub handle
4. Write docs/releases/version-<x.y.z.w>-released.md
5. Add the docs/CHANGELOG.md stanza
6. Verify: uv run python -c "from utils.version import get_version; print(get_version())"
7. Commit all five paths together - a version bump without its notes leaves the release undocumented, and the notes are what users actually read.
8. If the user asked for a release: tag, push, and create the GitHub release with the contributors section included.

2. OpenAlgo Python SDK pin (e.g. openalgo==1.0.49)

A separate client library published on PyPI (https://pypi.org/project/openalgo/) that the platform consumes internally. It has its own release cycle. Touches the dependency lists, not utils/version.py.

1. pyproject.toml - the openalgo==X.Y.Z entry in the dependencies list
2. requirements.txt - the openalgo==X.Y.Z line
3. requirements-nginx.txt - the openalgo==X.Y.Z line
4. uv sync to regenerate uv.lock

All three files must be updated together. Missing one means a deploy path installs a different SDK version than the others - requirements-nginx.txt is the one most often forgotten.

Committing

Use a Conventional Commit. No emojis or icons anywhere in the message.

chore(release): bump platform to 2.0.1.1

chore(deps): bump openalgo SDK to 1.0.50

Do not commit or push unless the user asked for it.

Publishing the GitHub release

Releases are titled v<x.y.z.w> and carry a descriptive tag, not a version tag: v2.0.2.1 was published on the tag openalgo-flow-upgrade. Check what the last few used before picking one.

gh release list -L 5                      # TITLE, TYPE, TAG NAME, PUBLISHED
gh release create <descriptive-tag> --title "v<x.y.z.w>" --notes-file <file>

The body is the release notes, and it must carry the contributors section. A release that thanks nobody is not finished.