# openSUSE Maintainership Generator

## Purpose

This repository generates the `_maintainership.json` file used by openSUSE Leap and Package Hub.

Maintainership information currently exists in several different places:

* OBS maintainers and bugowners
* OBS groups
* Gitea development project `_maintainership.json` files
* Local overrides and exceptions

The goal of this project is to combine all available sources into a single authoritative `_maintainership.json` file.

Whenever possible, ownership information should be reused from development projects instead of duplicated. Unfortunately, maintainership data is currently scattered across multiple systems and requires additional processing.

We generally iterate over packages / submodules in products/PackageHub repository leap-16.1 branch and fetch maintainership from sources desribed bellow. PackageHub git repo is fetched as part of `make fetch`.

## Ownership Precedence

Sources are processed in the following order:

```text
exceptions.sh
↓
Gitea development project _maintainership.json
↓
OBS maintainer / bugowner
↓
Expanded OBS groups
```

Higher-priority sources override lower-priority sources.

## Data Sources

### `exceptions.sh`

Local overrides always win.

This file can be used to:

* Override ownership of a specific package
* Remove a specific maintainer from a package
* Exclude users that only appear as maintainers because of OBS permission limitations

Examples:

```bash
declare -A OVERRIDE_PKG_MAINTAINERS=(
  ["matrix-synapse"]="okurz"
)

IGNORE_USERS=(
  "dimstar_suse"
)
```

### `gitea_devproj_ownership/`

Contains `_maintainership.json` files fetched from development projects hosted in Gitea.

Files are merged into:

```text
gitea_devproj_ownership/all_devproj_merged.json
```

If a package is present in one of these files, that ownership information is preferred over OBS.

### `osc_maintainer_out/`

Cached output of:

```bash
osc maintainer <project> <package>
```

More than 6500 packages currently inherit ownership from their development project in OBS.

### `groups/`

Gitea does not currently understand OBS groups.

Group references are expanded into individual users using files stored in:

```text
groups/
```

For example:

```text
groups/hpc-team.txt
groups/python-maintainers.txt
```

Each file contains one username per line.

Some groups represent permissions rather than ownership. For example, `factory-maintainers` is intentionally expanded to an empty file to avoid assigning ownership to all members of the group.

### `non_factory_packages.txt`

Some packages shipped in Leap are no longer present in Factory.

For these packages, ownership information is retrieved from manually maintained development project mappings:

```text
network:telephony/linphone
science/opencv3
GNOME:STABLE:48/librest0_7
```

The list currently contains roughly 150 packages.

## Generated Files

### `_maintainership.json`

Final ownership file generated by this project.

### `osc_maintainer_out/`

Cached OBS ownership information.

### `groups/`

Expanded OBS group membership.

### `gitea_devproj_ownership/`

Cached development project ownership information fetched from Gitea.

## Warning About `make clean`

Rebuilding ownership information from scratch can take some time.

The current cache contains more than 6500 package ownership records:

```bash
ls osc_maintainer_out | wc -l
```

Running:

```bash
make clean
```

will remove cached data and force ownership information to be downloaded again.

## Usage

Review local overrides:

```bash
vim exceptions.sh
```

Update non-Factory package mappings:

```bash
vim non_factory_packages.txt
```

Add additional Gitea development projects if needed:

```bash
vim fetch_gitea_devproj_ownership.sh
```

Regenerate ownership information:

```bash
make all
```

The resulting file will be written to:

```text
_maintainership.json
```

## Directory Layout

```text
.
├── exceptions.sh
├── non_factory_packages.txt
├── groups/
├── osc_maintainer_out/
├── gitea_devproj_ownership/
├── fetch_gitea_devproj_ownership.sh
├── fetch_groups.sh
├── fetch_pkg_maintainer_from_factory.sh
├── fetch_pkg_maintainer_non_factory.sh
├── generate_maintainers_json_from_pkgs.sh
└── _maintainership.json
```