docs: migrate to scriv to manage changelog

.github/PULL_REQUEST_TEMPLATE.md

@@ -55,18 +55,15 @@ Check off if complete *or* not applicable:
 - [ ] All reviewers approved
 - [ ] Reviewer tested the code following the testing instructions
 - [ ] CI build is green
-- [ ] Version bumped
-- [ ] Changelog record added with short description of the change and current date
+- [ ] Changelog entry added using scriv with short description of the change
 - [ ] Documentation updated (not only docstrings)
 - [ ] Integration with other services reviewed
 - [ ] Fixup commits are squashed away
 - [ ] Unit tests added/updated
 - [ ] Noted any: Concerns, dependencies, migration issues, deadlines, tickets
 
 **Post Merge:**
-- [ ] Create a tag
-- [ ] Create a release on GitHub
-- [ ] Check new version is pushed to PyPI after tag-triggered build is
-      finished.
+- [ ] Trigger the release workflow to create a new GitHub release.
+- [ ] Check new version is pushed to PyPI after tag-triggered build is finished.
 - [ ] Delete working branch (if not needed anymore)
 - [ ] Upgrade the package in the Open edX platform requirements (if applicable)

.github/workflows/create-release-pr.yml

@@ -0,0 +1,61 @@
+name: Create a Release Pull Request
+
+on:
+  workflow_dispatch:
+    inputs:
+      bump-type:
+        description: "The type of version bump"
+        required: true
+        type: choice
+        options:
+          - "major"
+          - "minor"
+          - "patch"
+
+jobs:
+  create-release-pr:
+    runs-on: ubuntu-latest
+    env:
+      BUMP_TYPE: ${{ github.event.inputs.bump-type }}
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.11
+
+      - name: Install release requirements
+        run: pip install scriv bump-my-version
+
+      - name: Configure Git user
+        run: |
+          git config user.name 'github-actions[bot]'
+          git config user.email 'github-actions[bot]@users.noreply.github.com'
+
+      - name: Compute version bump
+        id: version
+        run: |
+          echo "CURRENT_VERSION=$(bump-my-version show current_version)" >> $GITHUB_OUTPUT
+          echo "NEW_VERSION=$(bump-my-version show --increment $BUMP_TYPE new_version)" >> $GITHUB_OUTPUT
+
+      - name: Bump version
+        run: bump-my-version bump $BUMP_TYPE
+
+      - name: Collect changelog
+        run: make changelog
+
+      - name: Create Pull Request
+        uses: peter-evans/create-pull-request@v7
+        with:
+          commit-message: "chore: bump version ${{ steps.version.outputs.CURRENT_VERSION }} → ${{ steps.version.outputs.NEW_VERSION }}"
+          title: "v${{ steps.version.outputs.NEW_VERSION }} Release"
+          body: |
+            ### Description
+
+            This PR bumps the version from `${{ steps.version.outputs.CURRENT_VERSION }}` to `${{ steps.version.outputs.NEW_VERSION }}`.
+
+            The changelog has been automatically generated using `scriv`.
+          branch: "release-${{ steps.version.outputs.NEW_VERSION }}"

.github/workflows/github-release.yml

@@ -0,0 +1,45 @@
+name: Create a new GitHub Release
+
+on:
+  workflow_dispatch:
+
+jobs:
+  github-release:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.11
+
+      - name: Install release requirements
+        run: pip install scriv bump-my-version
+
+      - name: Install pandoc for scriv
+        run: sudo apt install -y pandoc
+
+      - name: Configure Git user
+        run: |
+          git config user.name 'github-actions[bot]'
+          git config user.email 'github-actions[bot]@users.noreply.github.com'
+
+      - name: Read current version
+        id: version
+        run: |
+          echo "CURRENT_VERSION=$(bump-my-version show current_version)" >> $GITHUB_OUTPUT
+
+      - name: Create and push Git tag
+        env:
+          CURRENT_VERSION: ${{ steps.version.outputs.CURRENT_VERSION }}
+        run: |
+          git tag -a "v$CURRENT_VERSION" -m "Release v$CURRENT_VERSION"
+          git push origin "v$CURRENT_VERSION"
+
+      - name: Create GitHub release
+        run: scriv github-release --repo=openedx/openedx-events
+        env:
+          GITHUB_TOKEN: ${{ github.token }}

CHANGELOG.rst

@@ -3,19 +3,41 @@ Change Log
 
 ..
    All enhancements and patches to openedx_events will be documented
-   in this file.  It adheres to the structure of https://keepachangelog.com/ ,
+   in this file. It adheres to the structure of https://keepachangelog.com/,
    but in reStructuredText instead of Markdown (for ease of incorporation into
    Sphinx documentation and the PyPI description).
 
    This project adheres to Semantic Versioning (https://semver.org/).
 
 .. There should always be an "Unreleased" section for changes pending release.
 
+..
+   ⚠️ PLEASE, DO NOT ADD YOUR CHANGES TO THIS FILE! (unless you want to modify
+   existing changelog entries in this file) Changelog entries are managed by
+   scriv.
+
+   If you need to add a changelog entry:
+
+   - Run `make changelog-entry` to create a new changelog entry.
+   - Edit and commit the newly-created file in the `changelog.d` folder
+     following the instructions in the file.
 
+   If you need to create a new release:
+
+   - There is a `relese.yml` workflow to create a new release. You can trigger
+     it manually in the Actions tab in GitHub. The workflow will bump the
+     version, update the changelog, create a tag, and create a new GitHub
+     release! 🚀
 
 Unreleased
 __________
 
+See the fragment files in the `changelog.d directory`_.
+
+.. _changelog.d directory: https://github.com/openedx/openedx-events/tree/master/changelog.d
+
+.. scriv-insert-here
+
 [10.5.0] - 2025-08-19
 ---------------------
 
@@ -33,7 +55,6 @@ Added
 
 * Added new ``ENTERPRISE_GROUP_DELETED`` event in enterprise.
 
-
 [10.3.0] - 2025-05-23
 ---------------------
 
@@ -76,10 +97,13 @@ Added
 * Added new ``EXTERNAL_GRADER_SCORE_SUBMITTED`` event in learning.
 * Add ``ExternalGraderScoreData`` to support this event
 
+
 [10.0.0] - 2024-04-04
 ---------------------
+
 Changed
 ~~~~~~~
+
 * **Breaking change**: LibraryCollectionData now takes only a LibraryCollectionLocator.
 * **Breaking change**: LibraryContainerData now takes only a LibraryContainerLocator.
 

Makefile

@@ -1,6 +1,7 @@
 .PHONY: clean clean_tox compile_translations coverage diff_cover docs dummy_translations \
         extract_translations fake_translations help pull_translations push_translations \
-        quality requirements selfcheck test test-all upgrade validate install_transifex_client
+        quality requirements selfcheck test test-all upgrade validate install_transifex_client \
+		changelog-entry changelog
 
 .DEFAULT_GOAL := help
 
@@ -32,6 +33,12 @@ docs: ## generate Sphinx HTML documentation, including API docs
 	tox -e docs
 	$(BROWSER)docs/_build/html/index.html
 
+changelog-entry: ## Create a new changelog entry
+	scriv create
+
+changelog: ## Collect changelog entries in the CHANGELOG.rst file
+	scriv collect
+
 # Define PIP_COMPILE_OPTS=-v to get more information during make upgrade.
 PIP_COMPILE = pip-compile --upgrade $(PIP_COMPILE_OPTS)
 

changelog.d/20250929_221720_bryann.valderrama_scriv.rst

@@ -0,0 +1,3 @@
+Added
+~~~~~
+* Migrate to scriv to manage changelog. (by @bryanttv in #472)

changelog.d/scriv.ini

@@ -0,0 +1,6 @@
+[scriv]
+version = literal: openedx_events/__init__.py: __version__
+format = rst
+entry_title_template = file: changelog.d/scriv/entry_title.${config:format}.j2
+new_fragment_template = file: changelog.d/scriv/new_fragment.${config:format}.j2
+rst_header_chars = -~

changelog.d/scriv/entry_title.rst.j2

@@ -0,0 +1 @@
+{% if version %}[v{{ version }}] - {% endif %}{{ date.strftime('%Y-%m-%d') }}

changelog.d/scriv/new_fragment.rst.j2

@@ -0,0 +1,44 @@
+.. Create a new changelog entry for every new user-facing change.
+
+.. Please respect the following instructions:
+.. * Add a new bullet item for the category that best describes the change.
+.. * You may optionally append "(by @<author> in #<pr-number>)" at the end of
+..   the bullet item. This will be used to credit the PR author in the bullet
+..   item, where <author> is the GitHub username of the author of the change
+..   and <pr-number> is the PR number of the change. These affiliations will
+..   be displayed in the release notes for every release.
+.. * The accepted categories are: Added, Changed, Deprecated, Removed, Fixed,
+..   and Security.
+.. * Indicate breaking changes with a "**BREAKING CHANGE:**" prefix in the
+..   bullet item.
+
+.. For example:
+
+.. Added
+.. ~~~~~
+.. * Added new ``COURSE_DOWNLOADED_COMPLETED`` event.
+.. * Added support for annotated Python dictionaries as Avro Map type. (by @developer in #1)
+
+.. Changed
+.. ~~~~~~~
+.. * Added support for Python 3.12.
+.. * **BREAKING CHANGE:** Updated from Django 3.x to 4.x. (by @developer #2)
+
+.. Deprecated
+.. ~~~~~~~~~~
+.. * Deprecated ``COURSE_DOWNLOADED_STARTED`` event
+.. * Deprecated use of non-annotated dictionaries in events. (by @developer #3)
+
+.. Removed
+.. ~~~~~~~
+.. * Removed support for Python 3.8.
+.. * Removed unused ``COURSE_DOWNLOADED_STARTED`` event. (by @developer #4)
+
+.. Fixed
+.. ~~~~~
+.. * Fixed event validation in background processes.
+.. * Fixed incorrect handling of event payloads. (by @developer #4)
+
+.. Security
+.. ~~~~~~~~
+.. * Updated dependencies to patch security vulnerabilities.

requirements/base.txt

@@ -4,13 +4,13 @@
 #
 #    make upgrade
 #
-asgiref==3.9.1
+asgiref==3.9.2
     # via django
 attrs==25.3.0
     # via -r requirements/base.in
 cffi==2.0.0
     # via pynacl
-click==8.2.1
+click==8.3.0
     # via edx-django-utils
 django==4.2.24
     # via
@@ -27,19 +27,19 @@ dnspython==2.8.0
     # via pymongo
 edx-ccx-keys==2.0.2
     # via -r requirements/base.in
-edx-django-utils==8.0.0
+edx-django-utils==8.0.1
     # via -r requirements/base.in
 edx-opaque-keys[django]==3.0.0
     # via
     #   -r requirements/base.in
     #   edx-ccx-keys
 fastavro==1.12.0
     # via -r requirements/base.in
-psutil==7.0.0
+psutil==7.1.0
     # via edx-django-utils
 pycparser==2.23
     # via cffi
-pymongo==4.15.0
+pymongo==4.15.1
     # via edx-opaque-keys
 pynacl==1.6.0
     # via edx-django-utils

requirements/dev.in

@@ -6,3 +6,4 @@
 -r ci.txt             # dependencies needed to setup testing environment on CI
 
 diff-cover                # Changeset diff test coverage
+scriv                     # Changelog management tool