# Quick Reference — neng-temp-logger Releases

## TL;DR

```bash
# One-time setup
mkdir -p ~/.config/temp-logger
cp release.env.example ~/.config/temp-logger/release.env
# Edit and fill in GITLAB_PROJECT_ID, GITLAB_TOKEN, PYPI_TOKEN

# Make a release
./release.sh patch                    # GitLab only
./release.sh minor --pypi             # GitLab + PyPI
./release.sh major --dry-run          # Test first
```

---

## Release Levels

| Command | Version bump | Use case |
| ------- | ------------ | -------- |
| `patch` | 0.1.2 → 0.1.3 | Bug fixes, minor improvements |
| `minor` | 0.1.2 → 0.2.0 | New features, backward compatible |
| `major` | 0.1.2 → 1.0.0 | Breaking changes, major release |

---

## Flags

| Flag | Effect |
| ---- | ------ |
| `--pypi` | Also upload to PyPI (requires TWINE_PASSWORD) |
| `--dry-run` | Simulate only, don't modify files or push |
| (none) | Upload to GitLab Package Registry (default) |

---

## What release.sh does

1. Checks working tree is clean (`git status`)
2. Bumps version in `src/temp_logger/__init__.py`
3. Updates `CHANGELOG.md` with release header + links
4. Commits with message: `release: vX.Y.Z`
5. Creates annotated tag: `vX.Y.Z`
6. Builds sdist + wheel: `python3 -m build`
7. Uploads to GitLab Package Registry (always)
8. Uploads to PyPI (only with `--pypi`)
9. Pushes commit + tag to `origin` (remote)

---

## Examples

### Bug-fix release (GitLab only)

```bash
./release.sh patch
```

- 0.1.2 → 0.1.3
- Commit: "release: v0.1.3"
- Tag: v0.1.3
- Uploaded to GitLab Package Registry
- Pushed to origin

### Feature release (with PyPI)

```bash
./release.sh minor --pypi
```

- 0.1.2 → 0.2.0
- Uploaded to both GitLab + PyPI
- Install: `pip install neng-temp-logger==0.2.0`

### Test before releasing

```bash
./release.sh major --dry-run
```

- Bumps version locally
- Builds package
- Does NOT commit, tag, or push
- Does NOT upload anywhere
- Restore with: `git checkout -- src/temp_logger/__init__.py CHANGELOG.md`

---

## Token setup

### GitLab token

1. Go to <https://gitlab.flavio.be/flavio/temp-logger>
2. Settings → Access Tokens
3. Create token with scopes: **api** + **write_repository**
4. Copy and save to `~/.config/temp-logger/release.env` as `GITLAB_TOKEN`

### PyPI token (optional)

1. Go to <https://pypi.org/manage/account/token/>
2. Create token
3. Either:
   - Save to `~/.config/temp-logger/release.env` as `TWINE_PASSWORD`
   - Or, in GitLab: Settings → CI/CD → Variables → `PYPI_TOKEN` (masked)

### GitLab project ID

1. Go to <https://gitlab.flavio.be/flavio/temp-logger>
2. Settings → General
3. Look for "Project ID" (numeric value)
4. Save to `~/.config/temp-logger/release.env` as `GITLAB_PROJECT_ID`

---

## Troubleshooting

### "Working tree is not clean"

```bash
git status
git add .
git commit -m "..."
# Then try release.sh again
```

### "GITLAB_PROJECT_ID not set"

```bash
export GITLAB_PROJECT_ID=123456
./release.sh patch
# Or save to ~/.config/temp-logger/release.env
```

### "Cannot read \_\_version\_\_"

```bash
cat src/temp_logger/__init__.py
# Should have: __version__ = "0.1.2"
```

### CI job failed: "python: command not found"

This means the runner is using shell executor. Already fixed in `.gitlab-ci.yml` — uses `python3`.

---

## Version check

```bash
temp-logger --version
temp-logger-gui --version
pid-controller-gui --version
scpi-client --version
```

All should return the version from `src/temp_logger/__init__.py`.

---

## Install from releases

### From GitLab Package Registry (private)

```bash
pip install --index-url https://gitlab.flavio.be/api/v4/projects/PROJECT_ID/packages/pypi neng-temp-logger
```

### From PyPI (public)

```bash
pip install neng-temp-logger
```

---

## CI/CD automation

When you push a tag matching `v0.1.2` pattern:

- ✅ Tests run (pytest + ruff)
- ✅ Package builds (sdist + wheel)
- ✅ GitLab Package Registry updated
- 🔘 PyPI upload requires manual approval (click "Trigger" in CI)

---

## File locations

| File | Purpose |
| ---- | ------- |
| `release.sh` | Automated release script (this directory) |
| `release.env.example` | Token template |
| `~/.config/temp-logger/release.env` | Your actual tokens (secret) |
| `src/temp_logger/__init__.py` | Version source of truth |
| `CHANGELOG.md` | Release notes (auto-updated) |
| `.gitlab-ci.yml` | CI/CD pipeline |

---

## Semantic versioning

```txt
v0.1.2
├─ 0 = MAJOR (breaking changes)
├─ 1 = MINOR (new features, backward compatible)
└─ 2 = PATCH (bug fixes)
```

See <https://semver.org/> for details.
