# Release Checklist

Use this checklist before creating a new release of `neng-temp-logger`.

## Pre-Release Verification

### 1. Code Quality ✓

Run the verification script to ensure all checks pass:

```bash
./verify-code.sh
```

This checks:

- ✅ **Ruff linting**: Python code style (E, F, W, I, UP, B, SIM rules)
- ✅ **Unit tests**: All 35+ pytest tests pass
- ✅ **Code formatting**: Consistent style (line length: 100)

**Expected output:**

```txt
════════════════════════════════════════════════
  ✓ Code Verification Complete!
════════════════════════════════════════════════
```

❌ **DO NOT PROCEED** if verification fails. Fix issues first.

### 2. Version Update

Use the project version management script:

```bash
# From project root directory
./manage_subproject_versions.py bump tmp117 <patch|minor|major>

# Examples:
./manage_subproject_versions.py bump tmp117 patch   # 0.3.0 → 0.3.1
./manage_subproject_versions.py bump tmp117 minor   # 0.3.0 → 0.4.0
./manage_subproject_versions.py bump tmp117 major   # 0.3.0 → 1.0.0
```

Version follows [Semantic Versioning](https://semver.org/):

- **patch**: Bug fixes (0.3.0 → 0.3.1)
- **minor**: New features, backward compatible (0.3.0 → 0.4.0)
- **major**: Breaking changes (0.3.0 → 1.0.0)

This script automatically updates `src/temp_logger/__init__.py`.

### 3. Update CHANGELOG.md

Move items from `## [Unreleased]` to a new version section:

```markdown
## [Unreleased]

## [0.X.Y] — 2026-MM-DD

### Added
- Feature descriptions

### Fixed
- Bug fix descriptions

### Changed
- Breaking changes or modifications
```

Update version links at bottom:

```markdown
[Unreleased]: https://gitlab.flavio.be/flavio/temp-logger/-/compare/v0.X.Y...HEAD
[0.X.Y]: https://gitlab.flavio.be/flavio/temp-logger/-/compare/v0.X.Y-1...v0.X.Y
```

### 4. Documentation Review

Ensure README.md and other docs reflect current features:

- [ ] All tools listed in command table
- [ ] New features documented
- [ ] Examples are accurate
- [ ] Links work (especially GitLab URLs)

### 5. Test Installation (Optional but Recommended)

Test the package installation locally:

```bash
# Clean build
rm -rf dist/ build/ *.egg-info

# Build package
python3 -m build

# Test install in isolated environment
python3 -m venv /tmp/test-env
source /tmp/test-env/bin/activate
pip install dist/neng_temp_logger-0.X.Y-py3-none-any.whl

# Quick smoke test
tmp117-scan --version
scpi-client --version
temp-logger-gui --version

# Clean up
deactivate
rm -rf /tmp/test-env
```

## Release Process

### 6. Commit and Tag

```bash
# Stage changes
git add src/temp_logger/__init__.py CHANGELOG.md

# Commit
git commit -m "chore: Bump version to 0.X.Y for release"

# Create annotated tag
git tag -a v0.X.Y -m "Release v0.X.Y - Brief description"

# Push to remote (triggers CI/CD)
git push origin main
git push origin v0.X.Y
```

### 7. Monitor CI/CD Pipeline

Watch the GitLab CI pipeline: <https://gitlab.flavio.be/flavio/temp-logger/-/pipelines>

Pipeline stages:

1. **lint** — Ruff code checks (must pass)
2. **test** — Unit tests (must pass)
3. **build** — Build sdist + wheel (auto on tag)
4. **publish-gitlab** — Publish to GitLab registry (auto on tag)
5. **publish-pypi** — Publish to PyPI (manual trigger)

❌ **If pipeline fails:**

- Review errors in failed job logs
- Fix issues locally
- Delete the tag: `git tag -d v0.X.Y && git push origin :v0.X.Y`
- Repeat from step 6

### 8. Publish to PyPI (Manual)

**Only after GitLab pipeline succeeds:**

1. Go to: <https://gitlab.flavio.be/flavio/temp-logger/-/pipelines>
2. Find the pipeline for tag `v0.X.Y`
3. Click on **publish-pypi** job
4. Click **Play** (▶️) button

**Requirements:**

- GitLab CI variable `PYPI_TOKEN` must be set (admin only)
- Package version must not already exist on PyPI

### 9. Verify Release

After successful publish:

**Check GitLab Package Registry:**

```txt
https://gitlab.flavio.be/flavio/temp-logger/-/packages
```

**Check PyPI (if published):**

```txt
https://pypi.org/project/neng-temp-logger/
```

**Test installation from PyPI:**

```bash
pip install --upgrade neng-temp-logger
tmp117-scan --version  # Should show new version
```

## Post-Release

### 10. Create Release Notes (Optional)

Create a GitLab release with changelog:

```txt
https://gitlab.flavio.be/flavio/temp-logger/-/releases/new
```

### 11. Update Unreleased Section

Add new `## [Unreleased]` section to CHANGELOG.md:

```markdown
## [Unreleased]

(empty - awaiting new changes)

## [0.X.Y] — 2026-MM-DD
...
```

Commit:

```bash
git add CHANGELOG.md
git commit -m "docs: Prepare changelog for next release"
git push origin main
```

## Troubleshooting

### Build Fails on Tag

**Symptom:** Build stage fails even though tests pass locally

**Solution:**

- Check Python version in CI (may differ from local)
- Review `pyproject.toml` dependencies
- Check for missing files in package (use `MANIFEST.in` if needed)

### Ruff Not Found in CI

**Symptom:** CI fails with "ruff not found!" even though it's installed

**Solution:**

- The `verify-code.sh` script uses `python3 -m ruff` for CI compatibility
- This works regardless of PATH configuration
- If you see this error, ensure ruff is installed: `pip install -e ".[dev]"`

### Version Already Exists on PyPI

**Symptom:** `twine upload` fails with "File already exists"

**Solution:**

- PyPI does not allow re-uploading same version
- Bump to next patch version (e.g., 0.3.0 → 0.3.1)
- Update `__init__.py` and CHANGELOG
- Create new tag

### Tests Pass Locally But Fail in CI

**Symptom:** `./verify-code.sh` passes locally, CI test job fails

**Solution:**

- Check for environment-specific code (file paths, OS-specific imports)
- Review CI logs for missing dependencies
- Ensure all test files are committed to git
- Check Python version compatibility (CI may use different version)

---

## Quick Reference

**Files to update for each release:**

1. Version number — Use `./manage_subproject_versions.py bump tmp117 <patch|minor|major>`
2. `CHANGELOG.md` — Release notes and version links
3. Optional: `README.md` — If new features need documentation

**Commands:**

```bash
# Verify code
cd TMP117/Python/temp-logger
./verify-code.sh

# Update version (from project root)
cd ../../../
./manage_subproject_versions.py bump tmp117 patch

# Update CHANGELOG.md
# (manual edit)

# Commit, tag, and push
cd TMP117/Python/temp-logger
git add src/temp_logger/__init__.py CHANGELOG.md
git commit -m "chore: Bump version to 0.X.Y for release"
git tag -a v0.X.Y -m "Release v0.X.Y"
git push origin main v0.X.Y
```

**CI/CD Pipeline URL:**
<https://gitlab.flavio.be/flavio/temp-logger/-/pipelines>

---

(c) 2026 Prof. Flavio ABREU ARAUJO. All rights reserved.
