Metadata-Version: 2.4
Name: django-release-wizard
Version: 0.1.0
Summary: Safe, reusable release preparation for Django projects
Keywords: django,release,versioning,git,uv
Author: Vince / LHnDEV
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Framework :: Django
Classifier: Framework :: Django :: 5.2
Classifier: Framework :: Django :: 6.0
Classifier: Framework :: Django :: 6.1
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Build Tools
Requires-Dist: django>=5.2,<6.2
Requires-Dist: packaging>=24,<27
Requires-Dist: tomlkit>=0.13,<1
Requires-Python: >=3.12
Project-URL: Homepage, https://gitlab.com/lhndev1/django-release-wizard
Project-URL: Repository, https://gitlab.com/lhndev1/django-release-wizard
Project-URL: Issues, https://gitlab.com/lhndev1/django-release-wizard/-/issues
Description-Content-Type: text/markdown

# Django Release Wizard

Django Release Wizard prepares and verifies versioned releases from a trusted
local Git checkout. It exposes the same workflow through a standalone command
and a reusable Django management command.

The initial backend targets projects managed with
[uv](https://docs.astral.sh/uv/). Project versions use the standard static
`[project].version` field from `pyproject.toml`; additional structured mirrors
can be discovered and configured explicitly.

## Status

The project is under initial development. Version `0.1.0` establishes the
configuration format and the local release workflow. Review the generated diff
before accepting any Git operation.

## Requirements

- Python 3.12 or newer;
- Django 5.2, 6.0, or 6.1;
- Git;
- uv for the initial backend.

## Installation

Once published, install the package as a development dependency:

```bash
uv add --dev django-release-wizard
```

Until then, install it directly from its Git repository or from a local clone.

To expose the Django management command, add the application only to settings
used by maintainers and CI when possible:

```python
INSTALLED_APPS += ["django_release_wizard"]
```

The package has no models or migrations and does not access the application
database.

## Commands

The standalone command works in any configured project:

```bash
uv run django-release-wizard --discover
uv run django-release-wizard --configure
uv run django-release-wizard --prepare
uv run django-release-wizard --verify
```

An installed Django application exposes the equivalent management command:

```bash
uv run python manage.py release_version --discover
uv run python manage.py release_version --configure
uv run python manage.py release_version --prepare
uv run python manage.py release_version --verify
```

Use `--project-root` when the command is not launched from the repository root.
The verification command accepts `--tag`; otherwise it reads `CI_COMMIT_TAG` or
uses the configured prefix with the canonical project version.

## Configuration

Configuration is versioned with the consuming project in `pyproject.toml`:

```toml
[tool.django-release-wizard]
backend = "uv"
tag-prefix = "v"
remote = "origin"
release-files = ["pyproject.toml", "uv.lock"]
prepare-commands = [["uv", "lock"]]
verify-commands = [["uv", "lock", "--check"]]
quality-commands = [
    ["uv", "run", "ruff", "check", "."],
    ["uv", "run", "pytest"],
]

[[tool.django-release-wizard.targets]]
path = "pyproject.toml"
format = "toml"
selector = "project.version"
role = "canonical"

[[tool.django-release-wizard.targets]]
path = "src/example/__init__.py"
format = "python"
selector = "__version__"
role = "mirror"
```

Exactly one target is canonical. Every mirror must hold the same version before
and after preparation. Generated files such as `uv.lock` belong in
`release-files` and are updated by their owning command; they are not direct
version targets.

All commands are stored as argument arrays and are executed without a shell.
The configuration currently supports `toml` and `python` targets.

## Discovery and configuration

`--discover` scans Git-tracked UTF-8 text files without modifying them. It
recognizes the standard project version, legacy Poetry metadata, top-level
Python `__version__` assignments, and Sphinx-style `version` or `release`
assignments. Unstructured textual occurrences are reported for review but are
not automatically editable.

The scanner ignores generated, vendored, binary, oversized, and unsafe paths.
It never imports project source code and never follows a symlink outside the
repository.

`--configure` presents editable candidates, lets the maintainer accept or skip
them, permits explicit structured targets to be added, and writes the confirmed
configuration. It stops after configuration so that this change can be reviewed
and committed separately from a release.

## Release preparation

`--prepare` requires a clean default branch synchronized with its upstream. It:

1. reads and compares every configured target;
2. proposes the current version for the first tag, an already prepared version,
   or the next patch version;
3. updates the canonical uv version without synchronizing the running process;
4. updates configured mirrors and runs preparation commands;
5. runs verification and project quality commands;
6. rejects unexpected changed files;
7. displays the release summary and Git diff;
8. asks separately before the preparation commit, annotated tag, and atomic
   push.

Declining a confirmation never advances to the next Git operation. The tool does
not create a commit, tag, or push without an explicit interactive confirmation.

`--verify` is the non-interactive CI entry point. It checks the requested tag,
the canonical version, every mirror, and the configured verification commands.
It does not update version targets.

Accepted versions use `X.Y.Z` and optional `-alpha.N`, `-beta.N`, or `-rc.N`
suffixes. Tags add the configured prefix, normally `v`.

## Package-manager scope

Version `0.1.x` provides an uv backend only. A `requirements.txt` file describes
items installed by pip and is not treated as project-version metadata. Modern
Poetry projects using `[project].version` can already use the structured target
model; native Poetry lock and command integration can be added when required.

The backend, target handlers, and discovery rules are kept separate so support
can evolve without changing the public workflow.

## Self-hosting the version workflow

This repository contains its own `[tool.django-release-wizard]` configuration.
After the bootstrap commit exists on the synchronized default branch, the
standalone command can prepare the package's subsequent versions:

```bash
uv run django-release-wizard --prepare
```

The installed metadata provides `django_release_wizard.__version__`; it is not a
second source file that needs to be rewritten.

## Development

```bash
uv sync --locked
uv run ruff check .
uv run ruff format --check .
uv run mypy .
uv run pytest
uv build --no-sources
```

The GitLab pipeline runs only for merge requests and supported version tags, not
for ordinary branch pushes.

## License

Django Release Wizard is distributed under the [MIT License](LICENSE).
