Metadata-Version: 2.4
Name: backlog-atlas
Version: 0.17
Summary: Generate a self-hosted backlog snapshot and dashboard for maintainers.
License-Expression: MIT
Project-URL: Homepage, https://github.com/omry/backlog-atlas
Project-URL: Documentation, https://github.com/omry/backlog-atlas/blob/main/USER-GUIDE.md
Project-URL: Source, https://github.com/omry/backlog-atlas
Project-URL: Issues, https://github.com/omry/backlog-atlas/issues
Project-URL: Changelog, https://github.com/omry/backlog-atlas/blob/main/CHANGELOG.md
Project-URL: Dashboard, https://omry.github.io/backlog-atlas/
Classifier: Development Status :: 3 - Alpha
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: omegaconf>=2.3
Provides-Extra: dev
Requires-Dist: black>=24; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: mypy>=1.8; extra == "dev"
Requires-Dist: pyflakes>=3; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Dynamic: license-file

# Backlog Atlas

[![PyPI](https://img.shields.io/pypi/v/backlog-atlas.svg)](https://pypi.org/project/backlog-atlas/)
[![Python versions](https://img.shields.io/pypi/pyversions/backlog-atlas.svg)](https://pypi.org/project/backlog-atlas/)
[![Publish to PyPI](https://github.com/omry/backlog-atlas/actions/workflows/publish.yml/badge.svg)](https://github.com/omry/backlog-atlas/actions/workflows/publish.yml)
[![License](https://img.shields.io/pypi/l/backlog-atlas.svg)](https://github.com/omry/backlog-atlas/blob/main/LICENSE)
[![Backlog Atlas dashboard](backlog_atlas/web/badge.svg)](https://omry.github.io/backlog-atlas/)

Backlog Atlas generates a self-hosted backlog snapshot and static dashboard for
GitHub repository maintainers.

It keeps GitHub Issues as the source of truth, derives backlog state from open
issues and linked pull requests, and publishes the result to a dedicated
`backlog-atlas` branch. The generated branch is machine-owned and can be served
directly with GitHub Pages.

![Backlog Atlas dashboard showing backlog summary tables, filters, issue rows, and recent activity.](https://raw.githubusercontent.com/omry/backlog-atlas/main/docs/assets/backlog-atlas-dashboard.png)

## Documentation

- [User Guide](https://github.com/omry/backlog-atlas/blob/main/USER-GUIDE.md)
  — install Backlog Atlas on a repository, enable the web UI, run updates, and
  uninstall.
- [Maintainer Guide](https://github.com/omry/backlog-atlas/blob/main/MAINTAINERS.md)
  — local development, testing, packaging, and release prep for this package.
- [Design Note](https://github.com/omry/backlog-atlas/blob/main/DESIGN.md)
  — how snapshots, diffs, and the update log fit
  together.
- [Changelog](https://github.com/omry/backlog-atlas/blob/main/CHANGELOG.md)
  — user-facing release notes.

## What It Produces

The `backlog-atlas` branch contains:

- `backlog.json` — structured backlog data plus the recent activity tail used by
  the web UI.
- `updates.jsonl` — append-only structured activity history.
- `last_snapshot.json` — internal diff state for the next run.
- `index.html` — the static dashboard.
- `favicon.svg` — the dashboard icon.
- `badge.svg` — a README badge image that can link to the hosted dashboard.

The dashboard can also load a generated `atlas.json` manifest next to
`index.html` and federate multiple public `backlog.json` files in the browser.
Author the multi-repo source as YAML, then compile it to the browser manifest.

The default branch only needs the installed workflow, manifest, and config:

- `.github/workflows/update-backlog-atlas.yml`
- `.github/backlog-atlas/manifest.json`
- `.github/backlog-atlas/config.yaml` — editable repository configuration

## Quick Start

```sh
pip install backlog-atlas
cd /path/to/target-repo
backlog-atlas install --dry-run
backlog-atlas install
```

The dry run previews the files and install source before anything is written.
Install is safe to rerun: it first removes old Backlog Atlas hooks/manifests and
preserves config and generated dashboard history. When the previous install
manifest lists bundled wheels, it writes a temporary cleanup workflow that
removes those old wheels only after the new install lands.
The manifest is the cleanup source of truth: it records installed files and
which ones are removed only by clean uninstall. Review and push the install
commit that Backlog Atlas creates, then enable GitHub Pages from the
`backlog-atlas` branch. See the
[User Guide](https://github.com/omry/backlog-atlas/blob/main/USER-GUIDE.md) for
the full local and remote install flows.

After the dashboard is hosted, add a Backlog Atlas badge to the repository
README by wrapping the generated badge image in a link to the dashboard.
Assuming the generated `badge.svg` is hosted alongside the dashboard, replace
`DASHBOARD_URL` with the dashboard URL:

```md
[![Backlog Atlas](DASHBOARD_URL/badge.svg)](DASHBOARD_URL)
```

For a conventional GitHub Pages dashboard, that is usually:

```md
[![Backlog Atlas](https://OWNER.github.io/REPO/badge.svg)](https://OWNER.github.io/REPO/)
```

## CLI

```sh
# install the workflow and manifest in a repository
backlog-atlas install [flags]

# remove installed hooks/manifests; --clean also removes config and branch
backlog-atlas uninstall [flags]

# write the static web UI files for preview or packaging
backlog-atlas dump-web --output PATH

# compile YAML multi-repo config into atlas.json for the browser UI
backlog-atlas dump-atlas --config atlas.yaml --output PATH

# manage repos tracked by .github/backlog-atlas/atlas.yaml
backlog-atlas atlas list
backlog-atlas atlas add owner/name [--backlog-url URL]
backlog-atlas atlas remove owner/name
backlog-atlas atlas install --delivery pr|push
backlog-atlas atlas install --local --checkout-root PATH

# refresh backlog data; normally run by the installed GitHub Action
backlog-atlas update [flags]

# explain how one issue is classified by the active config
backlog-atlas classify ISSUE_NUMBER [--repo URL]
```

## Development Checks

Maintainers can install local check tools with:

```sh
python -m pip install -e ".[dev]"
python -m black --check backlog_atlas tests tools
python -m pyflakes backlog_atlas tests tools
python -m mypy
python -m pytest
```

See the
[Maintainer Guide](https://github.com/omry/backlog-atlas/blob/main/MAINTAINERS.md)
for the full development workflow.

## License

MIT.
