nwp500-python 4.7__tar.gz → 4.7.1__tar.gz

{nwp500_python-4.7 → nwp500_python-4.7.1}/.github/copilot-instructions.md

@@ -17,6 +17,33 @@
 - **Type checking**: `python3 -m mypy src/nwp500 --config-file pyproject.toml` (static type analysis)
 - **Build docs**: `tox -e docs` (Sphinx docs in `docs/`)
 - **Preview docs**: `python3 -m http.server --directory docs/_build/html`
+- **Version management**: `make version-bump BUMP=patch|minor|major` (creates git tags, see Version Management section)
+
+### Version Management
+
+**CRITICAL**: This project uses `setuptools_scm` to derive versions from git tags. 
+
+**Never manually edit version numbers!** The `version` field in `setup.cfg`'s `[pyscaffold]` section is the PyScaffold TOOL version (4.6), NOT the package version. Changing it will cause incorrect releases.
+
+#### Creating a New Release
+
+1. **Update CHANGELOG.rst** with the new version and changes
+2. **Commit the changelog**: `git add CHANGELOG.rst && git commit -m "Update changelog for vX.Y.Z"`
+3. **Bump version**: Use the version bump script:
+   ```bash
+   make version-bump BUMP=patch   # For bug fixes (3.1.4 -> 3.1.5)
+   make version-bump BUMP=minor   # For new features (3.1.4 -> 3.2.0)
+   make version-bump BUMP=major   # For breaking changes (3.1.4 -> 4.0.0)
+   ```
+4. **Push the tag**: `git push origin vX.Y.Z`
+
+The version bump script:
+- Gets the current version from git tags
+- Validates the new version progression (prevents large jumps)
+- Prompts for confirmation with checklist
+- Creates a git tag (e.g., `v3.1.5`)
+
+**Validation**: Run `make validate-version` to check for version-related mistakes before committing.
 
 ### Before Committing Changes
 Always run these checks before finalizing changes to ensure your code will pass CI:

{nwp500_python-4.7 → nwp500_python-4.7.1}/CHANGELOG.rst

@@ -2,6 +2,14 @@
 Changelog
 =========
 
+Version 4.7.1 (2025-10-27)
+==========================
+
+Changed
+-------
+
+- **Patch Release**: No code changes, updated version format to full semantic versioning
+
 Version 4.7 (2025-10-27)
 ========================
 

{nwp500_python-4.7 → nwp500_python-4.7.1}/Makefile

@@ -1,4 +1,4 @@
-.PHONY: help install install-dev lint format test clean build release check-release ci-lint ci-format ci-check
+.PHONY: help install install-dev lint format test clean build release check-release ci-lint ci-format ci-check version-bump validate-version
 
 help:  ## Show this help message
 	@echo 'Usage: make [target]'
@@ -50,7 +50,7 @@ clean:  ## Remove build artifacts and cache files
 build: clean  ## Build distribution packages
 	python -m build
 
-check-release: lint format-check test  ## Run all checks before release (lint, format check, tests)
+check-release: lint format-check test validate-version  ## Run all checks before release (lint, format check, tests, version validation)
 	@echo "✓ All checks passed! Ready for release."
 
 release: check-release build  ## Prepare and build a release (run checks, then build)
@@ -80,3 +80,19 @@ docs:  ## Build documentation
 
 docs-clean:  ## Clean documentation build
 	rm -rf docs/_build
+
+version-bump:  ## Bump version (usage: make version-bump BUMP=patch|minor|major|X.Y.Z)
+	@if [ -z "$(BUMP)" ]; then \
+		echo "Error: BUMP parameter required"; \
+		echo "Usage: make version-bump BUMP=patch|minor|major|X.Y.Z"; \
+		echo "Examples:"; \
+		echo "  make version-bump BUMP=patch   # Bump patch version"; \
+		echo "  make version-bump BUMP=minor   # Bump minor version"; \
+		echo "  make version-bump BUMP=major   # Bump major version"; \
+		echo "  make version-bump BUMP=3.1.5   # Set explicit version"; \
+		exit 1; \
+	fi
+	python3 scripts/bump_version.py $(BUMP)
+
+validate-version:  ## Validate version configuration (checks for common mistakes)
+	python3 scripts/validate_version.py

{nwp500_python-4.7/src/nwp500_python.egg-info → nwp500_python-4.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nwp500-python
-Version: 4.7
+Version: 4.7.1
 Summary: A library for controlling Navien NWP500 Water Heaters via NaviLink
 Home-page: https://github.com/eman/nwp500-python
 Author: Emmanuel Levijarvi

{nwp500_python-4.7 → nwp500_python-4.7.1}/RELEASE.md

@@ -95,15 +95,74 @@ This runs:
 
 ### 4. Update Version and Changelog
 
-1. Update version in relevant files (handled by setuptools_scm)
-2. Update `CHANGELOG.rst` with changes for this release
-3. Commit changes:
+#### Understanding Version Management
+
+**IMPORTANT**: This project uses `setuptools_scm` to manage versions from git tags.
+The version is **NOT** stored in any Python files or config files.
+
+**DO NOT** edit the `version` field in `setup.cfg`'s `[pyscaffold]` section!
+That field stores the PyScaffold tool version (4.6), not the package version.
+
+#### Version Bump Process
+
+1. Update `CHANGELOG.rst` with changes for this release:
+
+```bash
+# Get current date
+date +"%Y-%m-%d"
+
+# Edit CHANGELOG.rst and add a new section:
+# Version X.Y.Z (YYYY-MM-DD)
+# ==========================
+```
+
+2. Commit the changelog:
 
 ```bash
 git add CHANGELOG.rst
 git commit -m "Update changelog for vX.Y.Z"
 ```
 
+3. Use the version bump script to create a git tag:
+
+```bash
+# For a patch release (X.Y.Z -> X.Y.Z+1)
+make version-bump BUMP=patch
+
+# For a minor release (X.Y.Z -> X.Y+1.0)
+make version-bump BUMP=minor
+
+# For a major release (X.Y.Z -> X+1.0.0)
+make version-bump BUMP=major
+
+# Or specify an explicit version
+make version-bump BUMP=3.1.5
+```
+
+The script will:
+- Get the current version from git tags
+- Calculate the new version
+- Validate the version progression (prevents large jumps)
+- Create a git tag (e.g., `v3.1.5`)
+- Display next steps
+
+4. Push the tag to trigger the release:
+
+```bash
+git push origin vX.Y.Z
+```
+
+#### Manual Version Tagging (Not Recommended)
+
+If you need to create a tag manually:
+
+```bash
+git tag -a vX.Y.Z -m "Release version X.Y.Z"
+git push origin vX.Y.Z
+```
+
+**Warning**: Manual tagging bypasses validation checks. Use the version bump script instead.
+
 ### 5. Build Distribution
 
 Clean and build distribution packages:
@@ -152,13 +211,15 @@ python -m twine upload dist/*
 
 ### 8. Tag the Release
 
-Create and push a git tag:
+**Note**: If you used the version bump script, the tag is already created.
+Just push it:
 
 ```bash
-git tag -a vX.Y.Z -m "Release version X.Y.Z"
 git push origin vX.Y.Z
 ```
 
+If you created a tag manually, push it now.
+
 ## Using Tox
 
 You can also use tox directly for all steps:
@@ -243,8 +304,9 @@ Before releasing, ensure:
 - [ ] All code is formatted: `make format`
 - [ ] Linting passes: `make lint`
 - [ ] All tests pass: `make test`
+- [ ] Version configuration is valid: `make validate-version`
 - [ ] Changelog is updated
-- [ ] Version is bumped appropriately
+- [ ] Version is bumped appropriately using `make version-bump`
 - [ ] Documentation is up to date
 - [ ] Examples work correctly
 - [ ] Build succeeds: `make build`
@@ -310,6 +372,7 @@ Example GitHub Actions workflow could run:
 
 | Command | Description |
 |---------|-------------|
+| `make version-bump` | Bump version (requires BUMP=patch/minor/major/X.Y.Z) |
 | `make help` | Show all available commands |
 | `make install-dev` | Install with dev dependencies |
 | `make format` | Format code with ruff |

nwp500_python-4.7.1/scripts/README.md

@@ -0,0 +1,206 @@
+# Development Scripts
+
+This directory contains helper scripts for development and release management.
+
+## Version Management Scripts
+
+### bump_version.py
+
+Creates new releases by bumping version numbers and creating git tags.
+
+**Usage:**
+```bash
+# Via Makefile (recommended)
+make version-bump BUMP=patch   # 3.1.4 -> 3.1.5
+make version-bump BUMP=minor   # 3.1.4 -> 3.2.0
+make version-bump BUMP=major   # 3.1.4 -> 4.0.0
+make version-bump BUMP=3.1.5   # Explicit version
+
+# Direct invocation
+python3 scripts/bump_version.py patch
+python3 scripts/bump_version.py minor
+python3 scripts/bump_version.py major
+python3 scripts/bump_version.py 3.1.5
+```
+
+**Features:**
+- Reads current version from git tags
+- Calculates next version based on bump type
+- Validates version progression (warns on large jumps)
+- Prompts for confirmation with pre-release checklist
+- Creates annotated git tag
+- Shows next steps for publishing
+
+**Important:** This project uses `setuptools_scm` to derive versions from git tags. Never manually edit version numbers in config files!
+
+### validate_version.py
+
+Validates version-related configuration to prevent common mistakes.
+
+**Usage:**
+```bash
+# Via Makefile (recommended)
+make validate-version
+
+# Direct invocation
+python3 scripts/validate_version.py
+```
+
+**Checks:**
+- Verifies `setup.cfg` `[pyscaffold]` version hasn't been modified (should be 4.6)
+- Ensures no hardcoded `__version__` strings in source code
+- Confirms `setup.py` uses `setuptools_scm`
+
+**When to run:**
+- Before creating a release
+- As part of `make check-release`
+- In CI/CD pipelines (recommended)
+
+## Code Quality Scripts
+
+### lint.py
+
+Runs ruff linting via tox, mirroring the CI environment exactly.
+
+**Usage:**
+```bash
+# Via Makefile (recommended)
+make ci-lint
+
+# Direct invocation
+python3 scripts/lint.py
+```
+
+This ensures local linting results match CI results, preventing "passes locally but fails in CI" issues.
+
+### format.py
+
+Formats code with ruff via tox, mirroring the CI environment exactly.
+
+**Usage:**
+```bash
+# Via Makefile (recommended)
+make ci-format
+
+# Direct invocation
+python3 scripts/format.py
+```
+
+This automatically fixes code formatting issues using the same configuration as CI.
+
+### setup-dev.py
+
+Sets up a minimal development environment with essential tools.
+
+**Usage:**
+```bash
+# Via Makefile (recommended)
+make setup-dev
+
+# Direct invocation
+python3 scripts/setup-dev.py
+```
+
+Installs minimal dependencies needed for development (ruff for linting/formatting).
+
+## Common Workflows
+
+### Creating a New Release
+
+1. **Update changelog:**
+   ```bash
+   # Edit CHANGELOG.rst with new version and changes
+   git add CHANGELOG.rst
+   git commit -m "Update changelog for vX.Y.Z"
+   ```
+
+2. **Validate everything:**
+   ```bash
+   make check-release  # Runs lint, format-check, tests, and validate-version
+   ```
+
+3. **Bump version:**
+   ```bash
+   make version-bump BUMP=patch  # or minor/major
+   ```
+
+4. **Push tag:**
+   ```bash
+   git push origin vX.Y.Z
+   ```
+
+5. **Build and publish:**
+   ```bash
+   make build
+   make publish-test  # Test on TestPyPI first
+   make publish       # Publish to PyPI
+   ```
+
+### Before Committing
+
+Always run these checks:
+```bash
+make ci-lint              # Check code style
+make validate-version     # Check version config
+python3 -m mypy src/nwp500 --config-file pyproject.toml  # Type checking
+pytest                    # Run tests
+```
+
+Or run all checks at once:
+```bash
+make check-release
+```
+
+## Version Management Details
+
+### How Versions Work
+
+This project uses `setuptools_scm` which:
+- Derives the package version from git tags
+- Automatically handles development versions (e.g., `3.1.5.dev1+g1234567`)
+- Requires no manual version editing in source files
+
+### What NOT to Do
+
+❌ **Never edit the version in `setup.cfg`'s `[pyscaffold]` section!**
+   - That field is the PyScaffold tool version (4.6), not the package version
+   - Changing it to 4.7 was the bug that caused the version jump from 3.1.4 to 4.7
+
+❌ **Never add `__version__` to source code**
+   - Version is derived from git tags, not hardcoded
+
+❌ **Never create tags manually without validation**
+   - Use `make version-bump` which validates version progression
+
+### What TO Do
+
+✅ Use `make version-bump BUMP=<type>` to create new versions
+
+✅ Run `make validate-version` before releases
+
+✅ Let `setuptools_scm` derive versions from git tags
+
+✅ Follow semantic versioning:
+   - **Patch** (X.Y.Z+1): Bug fixes, no API changes
+   - **Minor** (X.Y+1.0): New features, backward compatible
+   - **Major** (X+1.0.0): Breaking changes
+
+## Script Maintenance
+
+### Adding New Scripts
+
+1. Create script in `scripts/` directory
+2. Make it executable: `chmod +x scripts/yourscript.py`
+3. Add usage to this README
+4. Add Makefile target if appropriate
+5. Consider adding to `make check-release` if it's a validation script
+
+### Testing Scripts
+
+Test scripts manually before committing:
+```bash
+python3 scripts/validate_version.py  # Should pass
+python3 scripts/bump_version.py      # Should show usage
+python3 scripts/lint.py              # Should run linting
+python3 scripts/format.py            # Should format code
+```

nwp500_python-4.7.1/scripts/bump_version.py

@@ -0,0 +1,228 @@
+#!/usr/bin/env python3
+"""
+Version bump script for nwp500-python.
+
+This script helps create new releases by:
+1. Getting the current version from git tags
+2. Computing the next version based on bump type (major, minor, patch)
+3. Validating the new version
+4. Creating a new git tag
+
+Usage:
+    python scripts/bump_version.py patch   # 3.1.4 -> 3.1.5
+    python scripts/bump_version.py minor   # 3.1.4 -> 3.2.0
+    python scripts/bump_version.py major   # 3.1.4 -> 4.0.0
+    python scripts/bump_version.py 3.1.5   # Explicit version
+
+The script uses setuptools_scm to derive versions from git tags.
+DO NOT manually edit version numbers in setup.cfg - the [pyscaffold] version
+field is for the PyScaffold tool version, not the package version!
+"""
+
+import re
+import subprocess
+import sys
+from typing import Tuple
+
+
+def run_git_command(args: list) -> str:
+    """Run a git command and return the output."""
+    try:
+        result = subprocess.run(
+            ["git"] + args,
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+        return result.stdout.strip()
+    except subprocess.CalledProcessError as e:
+        print(f"Error running git command: {e}", file=sys.stderr)
+        print(f"stderr: {e.stderr}", file=sys.stderr)
+        sys.exit(1)
+
+
+def get_current_version() -> str:
+    """Get the current version from git tags."""
+    # Get all tags sorted by version
+    tags_output = run_git_command(["tag", "-l", "v*", "--sort=-version:refname"])
+    
+    if not tags_output:
+        print("No version tags found. Starting from v0.0.0")
+        return "0.0.0"
+    
+    # Get the most recent tag
+    latest_tag = tags_output.split("\n")[0]
+    
+    # Remove the 'v' prefix
+    version = latest_tag[1:] if latest_tag.startswith("v") else latest_tag
+    
+    return version
+
+
+def parse_version(version_str: str) -> Tuple[int, int, int]:
+    """Parse a version string into (major, minor, patch) tuple."""
+    match = re.match(r"^(\d+)\.(\d+)\.(\d+)$", version_str)
+    if not match:
+        print(f"Error: Invalid version format: {version_str}", file=sys.stderr)
+        print("Version must be in format: X.Y.Z", file=sys.stderr)
+        sys.exit(1)
+    
+    return int(match.group(1)), int(match.group(2)), int(match.group(3))
+
+
+def bump_version(version_str: str, bump_type: str) -> str:
+    """Bump a version string according to the bump type."""
+    major, minor, patch = parse_version(version_str)
+    
+    if bump_type == "major":
+        return f"{major + 1}.0.0"
+    elif bump_type == "minor":
+        return f"{major}.{minor + 1}.0"
+    elif bump_type == "patch":
+        return f"{major}.{minor}.{patch + 1}"
+    else:
+        # Assume it's an explicit version number
+        parse_version(bump_type)  # Validate format
+        return bump_type
+
+
+def validate_version_progression(current: str, new: str) -> None:
+    """Validate that the new version is a proper progression from current."""
+    curr_major, curr_minor, curr_patch = parse_version(current)
+    new_major, new_minor, new_patch = parse_version(new)
+    
+    # Check if new version is greater than current
+    curr_tuple = (curr_major, curr_minor, curr_patch)
+    new_tuple = (new_major, new_minor, new_patch)
+    
+    if new_tuple <= curr_tuple:
+        print(f"Error: New version {new} is not greater than current version {current}", file=sys.stderr)
+        sys.exit(1)
+    
+    # Check for unreasonable jumps (more than 1 major version or unusual patterns)
+    major_jump = new_major - curr_major
+    minor_jump = new_minor - curr_minor
+    patch_jump = new_patch - curr_patch
+    
+    if major_jump > 1:
+        print(f"Warning: Large major version jump detected ({current} -> {new})")
+        print(f"This will jump from {curr_major}.x.x to {new_major}.x.x")
+        response = input("Are you sure? (yes/no): ")
+        if response.lower() != "yes":
+            print("Version bump cancelled.")
+            sys.exit(1)
+    
+    if major_jump == 0 and minor_jump > 5:
+        print(f"Warning: Large minor version jump detected ({current} -> {new})")
+        print(f"This will jump from x.{curr_minor}.x to x.{new_minor}.x")
+        response = input("Are you sure? (yes/no): ")
+        if response.lower() != "yes":
+            print("Version bump cancelled.")
+            sys.exit(1)
+    
+    if major_jump == 0 and minor_jump == 0 and patch_jump > 10:
+        print(f"Warning: Large patch version jump detected ({current} -> {new})")
+        print(f"This will jump from x.x.{curr_patch} to x.x.{new_patch}")
+        response = input("Are you sure? (yes/no): ")
+        if response.lower() != "yes":
+            print("Version bump cancelled.")
+            sys.exit(1)
+
+
+def check_working_directory_clean() -> None:
+    """Check if the git working directory is clean."""
+    status = run_git_command(["status", "--porcelain"])
+    if status:
+        print("Error: Working directory is not clean.", file=sys.stderr)
+        print("Please commit or stash your changes before bumping version.", file=sys.stderr)
+        sys.exit(1)
+
+
+def create_tag(version: str, message: str = None) -> None:
+    """Create a git tag for the version."""
+    tag_name = f"v{version}"
+    
+    # Check if tag already exists
+    try:
+        subprocess.run(
+            ["git", "rev-parse", tag_name],
+            capture_output=True,
+            check=True,
+        )
+        print(f"Error: Tag {tag_name} already exists.", file=sys.stderr)
+        sys.exit(1)
+    except subprocess.CalledProcessError:
+        # Tag doesn't exist, which is what we want
+        pass
+    
+    # Create the tag
+    if message:
+        run_git_command(["tag", "-a", tag_name, "-m", message])
+    else:
+        run_git_command(["tag", "-a", tag_name, "-m", f"Release version {version}"])
+    
+    print(f"✓ Created tag: {tag_name}")
+
+
+def main() -> None:
+    """Main entry point."""
+    if len(sys.argv) != 2:
+        print("Usage: python scripts/bump_version.py [major|minor|patch|X.Y.Z]", file=sys.stderr)
+        print("\nExamples:", file=sys.stderr)
+        print("  python scripts/bump_version.py patch   # Bump patch version", file=sys.stderr)
+        print("  python scripts/bump_version.py minor   # Bump minor version", file=sys.stderr)
+        print("  python scripts/bump_version.py major   # Bump major version", file=sys.stderr)
+        print("  python scripts/bump_version.py 3.1.5   # Set explicit version", file=sys.stderr)
+        sys.exit(1)
+    
+    bump_type = sys.argv[1]
+    
+    # Validate bump type
+    if bump_type not in ["major", "minor", "patch"]:
+        # Check if it's a valid version number
+        try:
+            parse_version(bump_type)
+        except SystemExit:
+            print(f"Error: Invalid bump type: {bump_type}", file=sys.stderr)
+            print("Must be one of: major, minor, patch, or X.Y.Z", file=sys.stderr)
+            sys.exit(1)
+    
+    # Check working directory is clean
+    check_working_directory_clean()
+    
+    # Get current version
+    current_version = get_current_version()
+    print(f"Current version: {current_version}")
+    
+    # Calculate new version
+    new_version = bump_version(current_version, bump_type)
+    print(f"New version:     {new_version}")
+    
+    # Validate version progression
+    validate_version_progression(current_version, new_version)
+    
+    # Confirm with user
+    print(f"\nThis will create tag v{new_version}")
+    print("Make sure you have:")
+    print("  1. Updated CHANGELOG.rst")
+    print("  2. Committed all changes")
+    print("  3. Run tests and linting")
+    response = input("\nProceed with version bump? (yes/no): ")
+    
+    if response.lower() != "yes":
+        print("Version bump cancelled.")
+        sys.exit(0)
+    
+    # Create the tag
+    create_tag(new_version)
+    
+    print("\n✓ Version bump complete!")
+    print("\nNext steps:")
+    print(f"  1. Push the tag:    git push origin v{new_version}")
+    print("  2. Build release:   make build")
+    print("  3. Test on TestPyPI: make publish-test")
+    print("  4. Publish to PyPI:  make publish")
+
+
+if __name__ == "__main__":
+    main()