Summary
OSPR creators need clear guidance on commit expectations. We should capture the details and relevant references in one standalone doc.
Proposed work
Create a docs.openedx.org page covering:
- How Python Semantic Release (PSR) derives the version from commit history, so contributors never bump versions manually.
- How PSR parses commit messages to pick the version bump and build the changelog.
- The Conventional Commits mapping to patch, minor, and major releases, following OEP-0051.
- Why commit messages must be accurate: PSR reads them to generate release notes and changelogs.
- How to signal a breaking change and where to document it.
- It will be great if the PR is squashed when pushed for the final merge. (Nice to have)
Reference the real guidance from xblocks-extra#29: version comes from the SCM tag and breaking change → major bump.
Acceptance criteria
Follow-up: #567 links this doc from OSPR templates.
Summary
OSPR creators need clear guidance on commit expectations. We should capture the details and relevant references in one standalone doc.
Proposed work
Create a docs.openedx.org page covering:
Reference the real guidance from
xblocks-extra#29: version comes from the SCM tag and breaking change → major bump.Acceptance criteria
Follow-up: #567 links this doc from OSPR templates.