[RELEASE] - Prepare release version 0.23.0

README.md

@@ -7,9 +7,15 @@
 
 A hierarchical config using yaml in Python.
 
-Latest version is: **0.20.0**
+Latest version is: **0.23.0**
 
-### Unreleased: breaking merge behavior (deepmerge 4)
+## Release 0.23.0
+
+### Breaking changes
+
+Python 3.11 or newer is now required; Python 3.10 is no longer supported.
+
+#### Merge behavior (deepmerge 4)
 
 The upgrade from deepmerge 2.1.0 to 4.0.0 changes the default `append_unique`
 strategy. When a list is merged with an inherited list, repeated incoming values
@@ -30,6 +36,15 @@ For Python callers explicitly using `type_conflict_strategies=["override_if_not_
 incoming `0`, `False`, and `0.0` now override inherited values instead of being
 ignored. HIML's default `override` strategy is unaffected.
 
+### Other changes
+
+- Importing HIML no longer configures the root logger or changes its level.
+  CLI logging remains configured at INFO.
+- CI now discovers supported stable Python versions automatically.
+- Runtime, development, and GitHub Actions dependencies have been updated.
+
+See the [full changelog](https://github.com/adobe/himl/compare/0.22.0...0.23.0).
+
 > **⚠️ Breaking Changes in v0.18.0**
 > This version includes breaking changes:
 > - Default list merge strategy changed from `append` to `append_unique`
@@ -47,6 +62,7 @@ Idea came from puppet's hiera.
 ## Table of Contents
 
 - [himl](#himl)
+  - [Release 0.23.0](#release-0230)
   - [Description](#description)
   - [Table of Contents](#table-of-contents)
   - [Installation](#installation)
@@ -603,29 +619,22 @@ This project uses [bump-my-version](https://github.com/callowayproject/bump-my-v
 
 #### Bumping Versions
 
-Use the provided Makefile commands:
+For a release PR, preview and apply an explicit version without creating a commit
+or tag:
 
 ```bash
-# Show what version bumps would result in
-make show-bump
-
-# Dry run version bumps (to see what would change)
-make dry-bump-patch   # 0.16.4 -> 0.16.5
-make dry-bump-minor   # 0.16.4 -> 0.17.0
-make dry-bump-major   # 0.16.4 -> 1.0.0
-
-# Actually bump the version
-make bump-patch       # For bug fixes
-make bump-minor       # For new features
-make bump-major       # For breaking changes
-```
-
-The version bump will:
-1. Update the version in `pyproject.toml`
-2. Update the version in `README.md`
-3. Update the version in `himl/main.py` (CLI help)
-4. Create a Git commit with the changes
-5. Create a Git tag with the new version
+bump-my-version bump --new-version X.Y.Z --no-commit --no-tag --dry-run
+bump-my-version bump --new-version X.Y.Z --no-commit --no-tag
+```
+
+This updates the bump configuration in `pyproject.toml`, the README version, and
+the CLI version in `himl/main.py`. Update the release notes, validate the changes,
+and open a PR. Package metadata continues to use a development version until the
+merged release commit is tagged.
+
+The `make bump-patch`, `make bump-minor`, and `make bump-major` shortcuts also
+create a commit and tag; do not use them when preparing a release PR.
+See [RELEASE.md](RELEASE.md) for validation and post-merge publishing steps.
 
 ### Contributing
 

RELEASE.md

@@ -1,78 +1,117 @@
 # Release Process
 
-This project uses [bump-my-version](https://github.com/callowayproject/bump-my-version) for automated version management and releases.
+This project uses [bump-my-version](https://github.com/callowayproject/bump-my-version)
+to update release versions and setuptools_scm to derive package versions from Git
+tags. Prepare and merge a release PR before pushing a release tag. Pushing a tag
+publishes to PyPI and GHCR; opening or merging the PR does not publish a release.
 
 ## Prerequisites
 
-1. Ensure you have the development dependencies installed:
+1. Use Python 3.11 or newer and install the development dependencies in a virtual environment:
    ```bash
-   pip install -e .[dev]
+   python3 -m venv .venv
+   source .venv/bin/activate
+   python -m pip install -e '.[dev]'
    ```
 
 2. Ensure your working directory is clean (all changes committed)
 
 3. Ensure you're on the `main` branch and up to date:
    ```bash
    git checkout main
-   git pull origin main
+   git pull --ff-only origin main
+   git fetch origin --tags
    ```
 
 ## Release Steps
 
 ### 1. Choose Version Type
 
-Determine the type of release based on the changes:
-- **Patch** (`0.16.4 → 0.16.5`): Bug fixes, documentation updates
-- **Minor** (`0.16.4 → 0.17.0`): New features, backward-compatible changes
-- **Major** (`0.16.4 → 1.0.0`): Breaking changes
+Review changes since the latest published release and choose the next unused
+version. Do not rely only on `tool.bumpversion.current_version`: older releases
+may have been tagged without updating it.
 
-### 2. Preview the Release
+- **Patch**: Bug fixes and documentation updates
+- **Minor**: New features and backward-compatible changes
+- **Major**: Breaking changes for stable releases
 
-Check what the version bump would do:
-```bash
-# See all possible version bumps
-make show-bump
+While the project is pre-1.0, breaking changes may ship in a minor release, but
+must be called out with migration guidance. Release 0.23.0 requires Python 3.11+
+and changes merge behavior; see [README.md](README.md#release-0230).
+
+### 2. Prepare the Release PR
 
-# Dry run the specific bump you want to make
-make dry-bump-patch   # For patch releases
-make dry-bump-minor   # For minor releases
-make dry-bump-major   # For major releases
+Replace `X.Y.Z` with the chosen version in the commands below:
+```bash
+git checkout -b release/X.Y.Z
+bump-my-version bump --new-version X.Y.Z --no-commit --no-tag --dry-run
+bump-my-version bump --new-version X.Y.Z --no-commit --no-tag
 ```
 
-### 3. Execute the Version Bump
+This updates:
+- `tool.bumpversion.current_version` in `pyproject.toml`
+- The latest version in `README.md`
+- The CLI version in `himl/main.py`
+
+Update the README release notes, including breaking changes, migration guidance,
+and a comparison link from the previous release. Do not edit the generated
+`himl/_version.py`; setuptools_scm generates it from Git metadata.
+
+The `make bump-*` shortcuts create a commit and tag automatically. Do not use
+them for a release PR, and do not push tags before the PR is merged.
+
+### 3. Validate and Open the PR
 
-Run the appropriate bump command:
+Run the same core checks as CI:
 ```bash
-make bump-patch   # For patch releases
-make bump-minor   # For minor releases
-make bump-major   # For major releases
+make lint
+python -m pytest tests/ -v --tb=short --cov=himl --cov-report=term-missing --cov-fail-under=80
+python -m build
+python -m twine check dist/*
+himl --version
+himl --help
+himl-config-merger --help
+himl examples/simple/production --format yaml
 ```
 
-This will automatically:
-- Update the version in `pyproject.toml`
-- Update the version in `README.md`
-- Update the version in `himl/main.py` (CLI help)
-- Create a Git commit with message `[RELEASE] - Release version X.Y.Z`
-- Create a Git tag `X.Y.Z`
+Before tagging, package metadata will contain a development version even though
+`himl --version` reports the prepared release version. To validate release
+artifacts without creating a tag, build with
+`SETUPTOOLS_SCM_PRETEND_VERSION=X.Y.Z python -m build` and inspect the resulting
+wheel and source distribution.
 
-### 4. Push the Release
+Commit the release files, push only the branch, and open a PR using
+`.github/pull_request_template.md`. Include the exact validation commands and
+their results. Wait for CI and review before merging.
 
-Push the commit and tags to trigger the release:
+### 4. Tag the Merged Release
+
+After the release PR is merged, update `main`, verify the release versions and
+CI results, then tag the reviewed release commit:
 ```bash
-git push --follow-tags
+git checkout main
+git pull --ff-only origin main
+git tag -a X.Y.Z -m "Release X.Y.Z"
+git push origin X.Y.Z
 ```
 
+Push only the intended release tag, not all local tags.
+
 ### 5. Monitor Automated Release
 
 Wait for GitHub Actions to complete:
 1. **PyPI Release**: A new version will be published at https://pypi.org/project/himl/#history
 2. **Docker Image**: Published at https://github.com/adobe/himl/pkgs/container/himl
-3. **GitHub Release**: Automatically created at https://github.com/adobe/himl/releases
+
+The publishing workflows do not create a GitHub Release. Create it from the
+pushed tag, then review the generated notes and add the README migration guidance:
+```bash
+gh release create X.Y.Z --verify-tag --title "Release X.Y.Z" --generate-notes
+```
 
 ### 6. Verify Release
 
 1. Check that the new version appears on PyPI
 2. Verify the Docker image is available
 3. Test install the new version: `pip install himl==X.Y.Z`
-4. Update the GitHub release notes if needed
-
+4. Verify the GitHub release notes include breaking changes and migration guidance

himl/main.py

@@ -82,7 +82,7 @@ def get_parser(parser=None):
                             help='override default merge strategy for list')
         parser.add_argument('--allow-unicode', dest='allow_unicode', action='store_true', default=False,
                             help='allow unicode characters in output (default: False, outputs escape sequences)')
-        parser.add_argument('--version', action='version', version='%(prog)s v{version}'.format(version="0.20.0"),
+        parser.add_argument('--version', action='version', version='%(prog)s v{version}'.format(version="0.23.0"),
                             help='print himl version')
         return parser
 

pyproject.toml

@@ -68,7 +68,7 @@ Documentation = "https://github.com/adobe/himl#readme"
 write_to = "himl/_version.py"
 
 [tool.bumpversion]
-current_version = "0.20.0"
+current_version = "0.23.0"
 parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)"
 serialize = ["{major}.{minor}.{patch}"]
 search = "{current_version}"