Configuration (YAML)
====================

This page documents the YAML configuration format for config-driven mode.

Overview
--------

The configuration file is a YAML document with the following top-level sections:

1. ``version_source`` (required/per-project) - Version source configuration
2. ``spec_manager`` (required/per-project) - Spec manager configuration  
3. ``git`` (optional) - Git user configuration
4. ``work_dir`` (optional) - Working directory for cloning repositories
5. ``projects`` (required) - List of projects to manage

.. note::
   ``version_source`` and ``spec_manager`` can be specified globally OR per-project.
   Per-project settings override global settings.

Version Source Configuration
----------------------------

The version source determines where to fetch upstream version information.

Global Configuration
~~~~~~~~~~~~~~~~~~~~

.. code-block:: yaml

   version_source:
     type: anitya  # or: crates_io, pypi
     config:
       token: "your-api-token"  # source-specific config

Types
~~~~~

Anitya
^^^^^^

Monitor releases via Anitya Release Monitoring.

.. code-block:: yaml

   version_source:
     type: anitya
     config:
       token: "optional-api-token"

**Config options:**

- ``token`` (string, optional): API token for authenticated requests
  - Provides higher rate limits
  - Can also be set via ``ANITYA_API_TOKEN`` environment variable

**Project requirements:**

- Must specify ``identifier`` as Anitya project ID (integer)

crates.io
^^^^^^^^^

Fetch versions directly from crates.io sparse index.

.. code-block:: yaml

   version_source:
     type: crates_io
     config: {}

**Config options:** None

**Project requirements:**

- Must specify ``identifier`` as crate name (string)

PyPI
^^^^

Fetch versions from PyPI JSON API.

.. code-block:: yaml

   version_source:
     type: pypi
     config: {}

**Config options:** None

**Project requirements:**

- Must specify ``identifier`` as package name (string)

Spec Manager Configuration
---------------------------

The spec manager determines how RPM spec files are updated.

Global Configuration
~~~~~~~~~~~~~~~~~~~~

.. code-block:: yaml

   spec_manager:
     type: packit  # or: rust2rpm, pyp2spec
     config: {}

Types
~~~~~

Packit
^^^^^^

Update existing spec files using Packit.

.. code-block:: yaml

   spec_manager:
     type: packit
     config: {}

**Config options:** None

**Project requirements:**

- Must specify ``upstream_project_url``
- Must specify ``upstream_tag_template``

**Automatic .packit.yaml creation:**

If ``.packit.yaml`` doesn't exist, dist-git-manager will automatically create one using
the ``upstream_project_url`` and ``upstream_tag_template`` values.

rust2rpm
^^^^^^^^

Generate specs from crates.io metadata.

.. code-block:: yaml

   spec_manager:
     type: rust2rpm
     config: {}

**Config options:** None

**Project requirements:** None beyond standard fields

**Prerequisites:**

- ``rust2rpm`` must be installed: ``dnf install rust2rpm``

pyp2spec
^^^^^^^^

Generate specs from PyPI metadata.

.. code-block:: yaml

   spec_manager:
     type: pyp2spec
     config: {}

**Config options:** None

**Project requirements:** None beyond standard fields

**Prerequisites:**

- ``pyp2spec`` must be installed: ``dnf install pyp2spec``

Git Configuration
-----------------

Git configuration for commits and pushes.

.. code-block:: yaml

   git:
     user_name: "Dist Git Manager Bot"
     user_email: "distgit-bot@example.com"
     auto_push: false

**Fields:**

- ``user_name`` (string, optional): Git user name for commits
- ``user_email`` (string, optional): Git user email for commits  
- ``auto_push`` (boolean, optional): Whether to automatically push changes (default: ``false``)

Working Directory
-----------------

.. code-block:: yaml

   work_dir: "/var/lib/dist-git-manager"

**Type:** string

**Default:** ``/tmp/dist-git-manager``

Supports tilde (``~``) expansion. Created automatically if it doesn't exist.
Lock file is created in this directory.

Projects
--------

List of dist-git projects to manage.

.. code-block:: yaml

   projects:
     - name: "htop"
       identifier: 1234
       repo_url: "https://src.fedoraproject.org/rpms/htop.git"
       release_type: "semver"
       default_branch: "rawhide"
       upstream_project_url: "https://github.com/htop-dev/htop"
       upstream_tag_template: "v{version}"

Required Fields
~~~~~~~~~~~~~~~

- ``name`` (string): Project name for logging and directory naming
- ``identifier`` (string|int): Package identifier (Anitya ID or package name)
- ``repo_url`` (string): Dist-git repository URL
- ``release_type`` (string): ``semver`` or ``rolling``
- ``default_branch`` (string): Default branch name (e.g., ``rawhide``, ``main``)

Conditional Fields
~~~~~~~~~~~~~~~~~~

**For Packit spec manager:**

- ``upstream_project_url`` (string): Upstream repository URL
- ``upstream_tag_template`` (string): Template for git tags (use ``{version}`` placeholder)

Optional Fields  
~~~~~~~~~~~~~~~

- ``version_source`` (dict): Override global version source for this project
- ``spec_manager`` (dict): Override global spec manager for this project

Release Types
~~~~~~~~~~~~~

**semver**

For Semantic Versioning (X.Y.Z format):

- Creates ``release-X.Y`` branches for each series
- Updates spec in appropriate release branch
- Fast-forward merges when aligned

**rolling**

For rolling releases:

- Updates default branch only
- No release branch creation

Complete Examples
-----------------

Anitya + Packit (Traditional Fedora)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: yaml

   version_source:
     type: anitya
     config:
       token: "your-token"

   spec_manager:
     type: packit
     config: {}

   git:
     user_name: "Fedora Packager Bot"
     user_email: "packager@example.com"
     auto_push: false

   work_dir: "/var/lib/dist-git-manager"

   projects:
     - name: "htop"
       identifier: 1234
       repo_url: "https://src.fedoraproject.org/rpms/htop.git"
       release_type: "semver"
       default_branch: "rawhide"
       upstream_project_url: "https://github.com/htop-dev/htop"
       upstream_tag_template: "{version}"

crates.io + rust2rpm (Rust)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: yaml

   version_source:
     type: crates_io

   spec_manager:
     type: rust2rpm

   git:
     user_name: "Rust Packager Bot"
     user_email: "rust-bot@example.com"
     auto_push: false

   work_dir: "/var/lib/dist-git-manager"

   projects:
     - name: "serde"
       identifier: "serde"
       repo_url: "https://src.fedoraproject.org/rpms/rust-serde.git"
       release_type: "semver"
       default_branch: "rawhide"

PyPI + pyp2spec (Python)
~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: yaml

   version_source:
     type: pypi

   spec_manager:
     type: pyp2spec

   git:
     user_name: "Python Packager Bot"
     user_email: "python-bot@example.com"
     auto_push: false

   work_dir: "/var/lib/dist-git-manager"

   projects:
     - name: "requests"
       identifier: "requests"
       repo_url: "https://src.fedoraproject.org/rpms/python-requests.git"
       release_type: "semver"
       default_branch: "rawhide"

Mixed Mode
~~~~~~~~~~

Different projects can use different version sources and spec managers:

.. code-block:: yaml

   # No global version_source or spec_manager

   git:
     user_name: "Multi-Language Bot"
     user_email: "bot@example.com"
     auto_push: false

   work_dir: "/var/lib/dist-git-manager"

   projects:
     # Anitya + Packit
     - name: "htop"
       identifier: 1234
       repo_url: "https://src.fedoraproject.org/rpms/htop.git"
       release_type: "semver"
       default_branch: "rawhide"
       version_source:
         type: anitya
       spec_manager:
         type: packit
       upstream_project_url: "https://github.com/htop-dev/htop"
       upstream_tag_template: "v{version}"

     # crates.io + rust2rpm
     - name: "serde"
       identifier: "serde"
       repo_url: "https://src.fedoraproject.org/rpms/rust-serde.git"
       release_type: "semver"
       default_branch: "rawhide"
       version_source:
         type: crates_io
       spec_manager:
         type: rust2rpm

     # PyPI + pyp2spec
     - name: "requests"
       identifier: "requests"
       repo_url: "https://src.fedoraproject.org/rpms/python-requests.git"
       release_type: "semver"
       default_branch: "rawhide"
       version_source:
         type: pypi
       spec_manager:
         type: pyp2spec

Validation
----------

The tool validates configuration on startup:

- ``projects`` field must exist and be a list
- Each project must have all required fields
- Global or per-project ``version_source`` must be specified
- Global or per-project ``spec_manager`` must be specified
- ``release_type`` must be ``semver`` or ``rolling``

If validation fails, the tool exits with an error message.

Best Practices
--------------

1. **Start with dry-run**: Always test with ``--dry-run`` first
2. **Disable auto-push**: Keep ``auto_push: false`` until confident
3. **Use API tokens**: Get better rate limits with Anitya tokens
4. **Persistent work_dir**: Use a persistent directory (not /tmp) for production
5. **Test one project**: Start with a single project before adding more
6. **Version control**: Keep your config.yaml in version control
7. **Separate configs**: Use different configs for different package sets

Environment Variables
---------------------

- ``ANITYA_API_TOKEN``: API token for Anitya (overrides config file)

Example:

.. code-block:: bash

   export ANITYA_API_TOKEN="your-token-here"
   dist-git-manager -c config.yaml