drafteleu 0.6.0
Add your description here
Requires Python: >=3.12

# Drafteleu

<img alt="drafteleu.png" height="512" src="docs/drafteleu.png" width="512"/>

Drafteleu is a tool designed to maintain and update draft releases on GitHub repositories. It automates the process 
of keeping draft releases current with the latest changes in the repository, ensuring that they are always ready for 
publication.

## Features

- Creates or updates draft releases for the next pre-release *and* the next minor release.
- Automatically generates release notes based on PR titles.
- Supports semantic versioning.
- Supports filtering of PRs by labels and releases by tag prefix.
- Everything is done via the GitHub API.
- Multiple releases can be managed in one configuration file.
- Fast!


## Command-Line Interface (CLI)

Drafteleu provides a CLI for managing draft releases.

### Prerequisites

The CLI requires the `gh` (GitHub CLI) tool to be installed and authenticated. You can download it from 
[GitHub CLI](https://cli.github.com/).

### Basic Usage

```bash
uvx drafteleu owner/repo
```

This command updates or creates draft releases for the specified GitHub repository, using the configuration in `drafteleu.yaml`.

### Options

- **repo_slug**  
  The GitHub repository in `owner/repo` format (required).

- **--stage**  
  Select which releases to process:  
  - `pre`: Only prereleases  
  - `final`: Only final releases  
  - `both`: Both prereleases and final releases (default)

- **--verbosity, -v**  
  Set log verbosity:  
  - `0`: Warnings only  
  - `1`: Info (default)  
  - `2`: Debug

- **--dry-run**  
  Run without making changes (for testing).

- **--config**  
  Path to the configuration file (default: `drafteleu.yaml`).

### Example

```bash
uvx drafteleu myorg/myrepo --stage final --verbosity 2 --dry-run --config custom.yaml
```

This runs Drafteleu for `myorg/myrepo`, processes only final releases, shows debug output, does not make changes, 
and uses `custom.yaml` for configuration.

## Github Actions

You can run Drafteleu as part of your CI/CD pipeline using GitHub Actions. Below is an example workflow configuration.

```yaml
name: Drafteleu
on:
  push:
    branches:
      - main
  release:
    types: [published]

jobs:
  drafteleu:
    name: Drafteleu
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: read
    steps:
      - uses: actions/checkout@v5
        with:
          sparse-checkout: |
            .github/drafteleu.yaml
          sparse-checkout-cone-mode: false

      - uses: astral-sh/setup-uv@v7
        with:
          enable-cache: false
      - name: Run drafteleu
        run: |
          uvx drafteleu --config .github/drafteleu.yaml ${{ github.repository }}
        env:
          GH_TOKEN: ${{ github.token }}
```

Put your configuration file in `.github/drafteleu.yaml` and adjust the workflow as needed. Notice that you don't need
to check out the whole repository, just the configuration file.

## Configuration

Create a `drafteleu.yaml` file in your project root to configure release generation. Each configuration option is 
shown below with its default value and an example.

```yaml
---
title_template: 'Release v{next_version}'         # Default: 'Release {next_version}'
tag_template: 'v{next_version}'                   # Default: 'v{next_version}'
tag_regex: 'v(?P<version>.+)'                     # Default: 'v(?P<version>.+)'
version_template: '{major}.{minor}.{patch}'       # Default: '{major}.{minor}.{patch}'
rc_template: '-{pre_label}{pre_number}'           # Default: '-{pre_label}{pre_number}'
bump_part: 'minor'                                # Default: 'minor'
include_labels: ['feature', 'bugfix']             # Default: [], meaning: all PRs
```

### Options

- `title_template`  
  Template for the release title. Supports placeholders like `{next_version}`, `{next_tag}`, `{current_version}`, `{current_tag}`, `{current_date}`, `{stage}`.  
  **Default:** `Release {next_version}`  
  **Example:**  
  ```yaml
  title_template: 'Release v{next_version} ({stage})'
  ```

- `tag_template`  
  Template for the release tag.  
  **Default:** `v{next_version}`  
  **Example:**  
  ```yaml
  tag_template: 'release-{next_version}'
  ```

- `tag_regex`  
  Regex to match existing release tags and extract the version.  
  **Default:** `v(?P<version>.+)`  
  **Example:**  
  ```yaml
  tag_regex: 'release-(?P<version>.+)'
  ```

- `rc_template`  
  Template for pre-release (release candidate) suffix.  
  **Default:** `-{pre_label}{pre_number}`  
  **Example:**  
  ```yaml
  rc_template: '.rc{pre_number}'
  ```
  
- `version_template`
  Template for the version string. Use this to customize how versions are formatted. Do not include the pre-release 
  suffix here; that is handled by `rc_template`.
  **Default:** `{major}.{minor}.{patch}'`
  **Example:**
  ```yaml
  version_template: '{major}.{minor}'
  ```

- `bump_part`  
  Which part of the version to bump for the next release.  
  **Default:** `minor`  
  **Example:**  
  ```yaml
  bump_part: 'patch'
  ```

- `include_labels`  
  List of PR labels to include in the changelog.  
  **Default:** `[]` (all PRs)  
  **Example:**  
  ```yaml
  include_labels: ['feature', 'bugfix']
  ```

You can specify multiple configurations in a list for advanced usage. This is useful for monorepos or when you want to manage
multiple releases with different settings.

Example:

```yaml
---
title_template: 'App One v{next_version}'
tag_template: 'app-one/v{next_version}'
tag_regex: 'app-one/v(?P<version>.+)'
include_labels: 
  - app-one
---
title_template: 'App Two v{next_version}'
tag_template: 'app-two/v{next_version}'
tag_regex: 'app-two/v(?P<version>.+)'
include_labels:
  - app-two
```

See the [examples directory](examples/) for more configuration examples.