Replace release target with PR-based release flow (#553)

* Replace release target with prepare-release and create-github-release

- prepare-release: validates version, bumps files, runs pre-release-check,
  commits to release/X.Y.Z branch, pushes, and opens a PR via gh pr create
- create-github-release: creates GitHub Release with auto-generated notes
  (--generate-notes) which triggers the PyPI publish workflow
- Avoids direct pushes to master

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* Document new PR-based release process in DEVELOPMENT.rst

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* Run pre-release-check before bumping version files in prepare-release

If pre-release-check fails, the working tree remains clean and no
manual rollback is needed.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* Use Unreleased section in CHANGES.rst for development workflow

- CHANGES.rst: add empty Unreleased section at the top
- Makefile: prepare-release checks for Unreleased section and renames it
  to the release version; no need to know the version during development
- DEVELOPMENT.rst: document that PRs should add entries under Unreleased

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: martin-majlis

CHANGES.rst

@@ -1,6 +1,9 @@
 Changelog
 =========
 
+Unreleased
+----------
+
 0.14.1
 ------
 

DEVELOPMENT.rst

@@ -20,7 +20,46 @@ Makefile targets
 * ``make run-coverage`` - run code coverage (pytest-cov)
 * ``make pypi-html`` - generates single HTML documentation into ``pypi-doc.html``
 * ``make html`` - generates HTML documentation similar to RTFD into folder ``_build/html/``
-* ``make release`` - creates new release as well as git tag
+* ``make prepare-release VERSION='1.2.3'`` - bumps version files, runs full pre-release checks, and opens a PR from a ``release/1.2.3`` branch
+* ``make create-github-release VERSION='1.2.3'`` - after the PR is merged, creates a GitHub Release with auto-generated notes, triggering PyPI publish
+
+Releasing a New Version
+-----------------------
+
+**During development** — as each PR is merged, add a bullet point describing the
+change under the ``Unreleased`` section at the top of ``CHANGES.rst``::
+
+    Unreleased
+    ----------
+
+    * Add support for foo - `PR 123`_
+
+    .. _PR 123: https://github.com/martin-majlis/Wikipedia-API/pull/123
+
+**When ready to release:**
+
+1. From a clean ``master`` branch, run::
+
+    make prepare-release VERSION='1.2.3'
+
+   This will:
+
+   * Validate the version format and that it is greater than the current version
+   * Check that ``CHANGES.rst`` has an ``Unreleased`` section
+   * Run the full pre-release check suite (tests, type checks, linting, examples)
+   * Create a ``release/1.2.3`` branch
+   * Rename ``Unreleased`` → ``1.2.3`` in ``CHANGES.rst`` and bump all version files
+   * Commit, push the branch, and open a pull request
+
+2. Review and merge the pull request.
+
+3. After the PR is merged, create the GitHub Release::
+
+    make create-github-release VERSION='1.2.3'
+
+   This creates a ``v1.2.3`` tag and GitHub Release with auto-generated release
+   notes (based on merged PRs since the last release), which triggers the
+   ``release.yml`` workflow to publish the package to PyPI.
 
 Usage Statistics
 ----------------

Makefile

@@ -12,7 +12,7 @@ BUILDDIR      = _build
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-.PHONY: help Makefile run-type-check run-tests extract-vcr-json
+.PHONY: help Makefile prepare-release create-github-release run-type-check run-tests extract-vcr-json
 
 process-readme:
 	awk '/^.. PYPI-BEGIN$$/,/^.. PYPI-END$$/ {next} {print}' README.rst > README_processed.rst
@@ -102,9 +102,18 @@ update-pre-commit:
 pre-release-check: run-pre-commit run-type-check run-ruff run-coverage run-tox run-example-sync run-example-async run-validate-attributes-mappping
 	echo "Pre-release check was successful"
 
-release: requirements-build process-readme pre-release-check
-	if [ "x$(MSG)" = "x" -o "x$(VERSION)" = "x" ]; then \
-		echo "Use make release MSG='some msg' VERSION='1.2.3'"; \
+prepare-release:
+	@if [ "x$(VERSION)" = "x" ]; then \
+		echo "Use make prepare-release VERSION='1.2.3' [MSG='optional PR context']"; \
+		exit 1; \
+	fi; \
+	current_branch=`git rev-parse --abbrev-ref HEAD`; \
+	if [ "x$$current_branch" != "xmaster" ]; then \
+		echo "prepare-release must be run from master (currently on $$current_branch)"; \
+		exit 1; \
+	fi; \
+	if [ -n "`git status --porcelain`" ]; then \
+		echo "Working tree is not clean. Commit or stash your changes first."; \
 		exit 1; \
 	fi; \
 	version=`grep '^__version__ = ' wikipediaapi/_version.py | sed -E 's/.*= \( *(.*), *(.*), *(.*)\)/\1.\2.\3/'`; \
@@ -136,23 +145,34 @@ release: requirements-build process-readme pre-release-check
 		echo "New version has to be greater"; \
 		exit 2; \
 	fi; \
-	has_documentation=`grep -c "^$(VERSION)\\$$" CHANGES.rst`; \
-	if [ $$has_documentation -eq 0 ]; then \
-		echo "There is no information about $(VERSION) in CHANGES.rst"; \
+	has_unreleased=`grep -c "^Unreleased\\$$" CHANGES.rst`; \
+	if [ $$has_unreleased -eq 0 ]; then \
+		echo "No 'Unreleased' section found in CHANGES.rst"; \
 		exit 3; \
 	fi; \
+	make pre-release-check; \
 	short_VERSION=`echo $(VERSION) | cut -f1-2 -d.`; \
 	commas_VERSION=`echo $(VERSION) | sed -E 's/\./, /g'`; \
 	echo "Short version: $$short_VERSION"; \
+	git checkout -b release/$(VERSION); \
+	sed -i.bak 's/^Unreleased$$/$(VERSION)/' CHANGES.rst && rm CHANGES.rst.bak && \
 	sed -i.bak -E 's/^version =.*/version = "'$(VERSION)'"/' pyproject.toml && rm pyproject.toml.bak && \
 	sed -i.bak -E 's/^release = .*/release = "'$(VERSION)'"/' conf.py && rm conf.py.bak && \
 	sed -i.bak -E 's/^version = .*/version = "'$$short_VERSION'"/' conf.py && rm conf.py.bak && \
 	sed -i.bak -E 's/^__version__ = .*/__version__ = ('"$$commas_VERSION"')/' wikipediaapi/_version.py && rm wikipediaapi/_version.py.bak; \
 	make build-package check-package && \
-	git commit .github CHANGES.rst pyproject.toml uv.lock conf.py wikipediaapi/_version.py -m "Update version to $(VERSION) for new release." && \
-	git push && \
-	git tag v$(VERSION) -m "$(MSG)" && \
-	git push --tags origin master
+	git commit CHANGES.rst pyproject.toml uv.lock conf.py wikipediaapi/_version.py -m "Update version to $(VERSION) for new release." && \
+	git push -u origin release/$(VERSION) && \
+	pr_body="Release $(VERSION)"; \
+	if [ -n "$(MSG)" ]; then pr_body="$$pr_body\n\n$(MSG)"; fi; \
+	gh pr create --title "Release $(VERSION)" --body "$$pr_body"
+
+create-github-release:
+	@if [ "x$(VERSION)" = "x" ]; then \
+		echo "Use make create-github-release VERSION='1.2.3'"; \
+		exit 1; \
+	fi
+	gh release create v$(VERSION) --title "v$(VERSION)" --generate-notes
 
 
 build-package: process-readme