# debian/watch -- uscan control file (format VERSION 5)
#
# STATUS: upstream rockdodger is currently NOT trackable by uscan.
#
# WHY (verified 2026-06):
#   * Upstream publishes releases only as tarballs uploaded to the Bitbucket
#     "Downloads" area of bitbucket.org/rpkrawczyk/rockdodger.
#   * That area no longer offers a machine-readable listing to anonymous
#     HTTP clients:
#       - the Downloads web page is a JavaScript application and contains
#         no static <a href> links to the tarballs, so uscan (plain HTTP,
#         no JS) finds nothing to match;
#       - the REST listing endpoint
#         https://api.bitbucket.org/2.0/repositories/rpkrawczyk/rockdodger/downloads
#         returns HTTP 402 ("A workspace on a Free plan does not support
#         uploading or downloading files").
#   * The git repository carries no release tags (refs/tags is empty; only
#     the "master" branch exists), so git-tag mode has nothing to match.
#   Note: an individual tarball IS still fetchable by its exact URL
#   (.../downloads/rockdodger-1.1.4.tar.gz -> 302 -> signed S3 URL), but
#   uscan cannot DISCOVER the version because no listing is exposed.
#
# CONSEQUENCE:
#   No HTTP-scrape watch rule can work here, regardless of the regex. We
#   therefore declare the source Untrackable and document the situation,
#   which keeps this a valid version-5 file and stops uscan/QA from emitting
#   spurious "no matching files" / "obsolete watch file" warnings.
#
# HOW TO RE-ENABLE TRACKING (preferred long-term fix):
#   Ask upstream to tag releases in git (e.g. a "1.1.4" or "v1.1.4" tag).
#   Once tags exist, delete this file's body and use the git-tag stanza that
#   is provided (commented out) at the bottom -- uscan will then read tags
#   via "git ls-remote" and need no web listing at all.
#
# RFC822/deb822 SYNTAX REMINDER (this bit us before):
#   A version-5 watch file is paragraph-based. A blank line ENDS a paragraph.
#   All fields that belong together (Source, Matching-Pattern, ...) must be
#   in the SAME paragraph, i.e. with no blank line between them. We use "#"
#   comment lines (never truly empty lines) for spacing so the single
#   paragraph below stays intact.
#
# TEST:  uscan --no-download --verbose
#
# ---------------------------------------------------------------------------
# Required first (and here only) line of the paragraph.
Version: 5
# Untrackable: <free-text reason>. Its mere presence tells uscan not to treat
# the inability to find a match as an error. Source/Matching-Pattern are kept
# for documentation and so the file is ready to work the moment a real listing
# becomes available again.
Untrackable: Bitbucket Downloads not listable for anonymous HTTP (Free-plan API returns 402, web page is JS-only) and the git repo has no release tags
# Source: the page uscan would scan for download hyperlinks.
Source: https://bitbucket.org/rpkrawczyk/rockdodger/downloads
# Matching-Pattern: regex matched against hrefs; first capture = version.
#   .*?/          non-greedy href path prefix (e.g. ".../downloads/")
#   rockdodger    literal tarball basename
#   @ANY_VERSION@ -> [-_]?[Vv]?(\d[\-+\.:\~\da-zA-Z]*)  (captures the version)
#   (?:\.pkg)?    optional ".pkg" infix kept from the legacy v3 file
#   @ARCHIVE_EXT@ -> (?i)(?:\.(?:tar\.xz|tar\.bz2|tar\.gz|tar\.zstd?|zip|tgz|tbz|txz))
Matching-Pattern: .*?/rockdodger@ANY_VERSION@(?:\.pkg)?@ARCHIVE_EXT@
#
# ---------------------------------------------------------------------------
# FUTURE: once upstream tags releases in git, replace everything above with
# the stanza below (remove the leading "# " from each line). It needs no web
# listing -- uscan reads tags directly via "git ls-remote".
#
# Version: 5
# Source: https://bitbucket.org/rpkrawczyk/rockdodger.git
# Matching-Pattern: refs/tags/@ANY_VERSION@
# Mode: git
# Git-Mode: full
