Debbugs::Status(3pm)

✨ NAME ✨

Debbugs::Status — routines for dealing with summary and status files 🎀

Ok so this is the Debbugs::Status(3pm) page, from the User Contributed Perl Documentation section, and bestie, it's literally the module that reads and writes your bug status files. Let's get into it 💅

---

🌸 SYNOPSIS 🌸

use Debbugs::Status;

That's it. That's the whole vibe. Load it and go 🦋

---

🧚 DESCRIPTION 🧚

So this module is a glow-up replacement for the parts of errorlib.pl which write and read status and summary files. Not me erasing legacy code and serving something better 😭✨

It also contains generic routines for returning information about the status of a particular bug. Very much giving "I do it all" energy 👑

---

💖 FUNCTIONS 💖

🌟 readbug

readbug($bug_num,$location)
readbug($bug_num)

Reads a summary file from the archive, given a bug number and a bug location. Valid locations are those understood by getbugcomponent — don't try to freestyle new ones, it won't eat 💀

🌟 read_bug

read_bug(bug => $bug_num,
         location => 'archive',
        );
read_bug(summary => 'path/to/bugnum.summary');
read_bug($bug_num);

A more complete function than readbug, highkey. It lets you pass a full path to the summary file instead of the bug number and/or location, which is such a slay for flexibility 🫶

Options

• bug — the bug number
• location — optional location which is passed to getbugcomponent
• summary — complete path to the .summary file which will be read
• lock — whether to obtain a lock for the bug to prevent something modifying it while the bug has been read. You must call unfilelock(); if something not undef is returned from read_bug.
• locks — hashref of already obtained locks; incremented as new locks are needed, and decremented as locks are released on particular files.

One of bug or summary must be passed. This function will return undef on failure, and will die if improper arguments are passed. Like, it's not playing games, periodt 🔥

🌟 split_status_fields

my @data = split_status_fields(@data);

Splits splittable status fields (like package, tags, blocks, blockedby, etc.) into arrayrefs (use make_list on these). Keeps the passed @data intact using dclone. Respectful king behavior, not touching your original data 💜

In scalar context, returns only the first element of @data. iykyk.

🌟 join_status_fields

my @data = join_status_fields(@data);

Handles joining the splitable status fields. (Basically, the inverse of split_status_fields. 🌈

Primarily called from makestatus, but may be useful for other functions after calling split_status_fields (or for legacy functions if we transition to split fields by default). Lowkey a multitasker 💅

🌟 lockreadbug

lockreadbug($bug_num,$location)

Performs a filelock, then reads the bug; the bug is unlocked if the return is undefined, otherwise, you need to call unfilelock or unlockwritebug. So like, if it comes back with something real, the lock is still yours to deal with — don't just walk away 🙈

See readbug above for information on what this returns.

🌟 lockreadbugmerge

my ($locks, $data) = lockreadbugmerge($bug_num,$location);

Performs a filelock, then reads the bug. If the bug is merged, locks the merge lock. Returns a list of the number of locks and the bug data. Merged bugs stay together, no cap 🧚

🌟 lock_read_all_merged_bugs

my ($locks,@bug_data) = lock_read_all_merged_bugs($bug_num,$location);

Performs a filelock, then reads the bug passed. If the bug is merged, locks the merge lock, then reads and locks all of the other merged bugs. Returns a list of the number of locks and the bug data for all of the merged bugs.

Will also return undef if any of the merged bugs failed to be read, even if all of the others were read properly. It's giving all-or-nothing, and honestly? Valid 😤

🌟 new_bug

my $new_bug_num = new_bug(copy => $data->{bug_num});

Creates a new bug and returns the new bug number upon success. Baby bug, welcome to the world 🎀

Dies upon failures. Dramatic but fair 💀

🌟 makestatus

my $content = makestatus($status,$version)
my $content = makestatus($status);

Creates the content for a status file based on the $status hashref passed.

Really only useful for writebug — like, that's its whole purpose bestie, stay in your lane 💅

Currently defaults to version 2 (non-encoded rfc1522 names) but will eventually default to version 3. If you care, you should specify a version. Future-you will thank present-you ✨

🌟 writebug

writebug($bug_num,$status,$location,$minversion,$disablebughook)

Writes the bug status and summary files out.

Skips writing out a status file if minversion is 2.

Does not call bughook if disablebughook is true. Simple as that 🌸

🌟 unlockwritebug

unlockwritebug($bug_num,$status,$location,$minversion,$disablebughook);

Writes a bug, then calls unfilelock; see writebug for what these options mean. Write it, then let it go — release that lock, queen 🕊️

---

🔥 VERSIONS 🔥

The following functions are exported with the :versions tag 🏷️✨

💫 addfoundversions

addfoundversions($status,$package,$version,$isbinary);

All use of this should be phased out in favor of Debbugs::Control::fixed/found. It's giving deprecated, bestie — the new thing ate 😌

💫 removefoundversions

removefoundversions($data,$package,$versiontoremove)

Removes found versions from $data.

If a version is fully qualified (contains /) only versions matching exactly are removed. Otherwise, all versions matching the version number are removed. Careful with that one, it's not subtle 💀

Currently $package and $isbinary are entirely ignored, but accepted for backwards compatibility. They're just there for the vibes at this point 🙈

💫 splitpackages

splitpackages($pkgs)

Split a package string from the status file into a list of package names. One string in, many names out 🌈

💫 bug_archiveable

bug_archiveable(bug => $bug_num);

Options

• bug — bug number (required)
• status — Status hashref returned by read_bug or get_bug_status (optional)
• version — Debbugs::Version information (optional)
• days_until — return days until the bug can be archived

Returns 1 if the bug can be archived. Returns 0 if the bug cannot be archived.

If days_until is true, returns the number of days until the bug can be archived, -1 if it cannot be archived. 0 means that the bug can be archived the next time the archiver runs.

Returns undef on failure. The math is mathing 📊

💫 get_bug_status

my $status = get_bug_status(bug => $nnn);

my $status = get_bug_status($bug_num)

Options

• bug — scalar bug number
• status — optional hashref of bug status as returned by readbug (can be passed to avoid rereading the bug information)
• bug_index — optional tied index of bug status infomration; currently not correctly implemented.
• version — optional version(s) to check package status at
• dist — optional distribution(s) to check package status at
• arch — optional architecture(s) to check package status at
• bugusertags — optional hashref of bugusertags
• sourceversion — optional arrayref of source/version; overrides dist, arch, and version. [The entries in this array must be in the source/version format.] Eventually this can be used to for caching.
• indicatesource — if true, indicate which source packages this bug could belong to (or does belong to in the case of bugs assigned to a source package). Defaults to true.

Note: Currently the version information is cached; this needs to be changed before using this function in long lived programs. Long-lived processes, consider yourselves warned bestie ⚠️

Returns

Currently returns a hashref of status with the following keys.

• id — bug number
• bug_num — duplicate of id
• keywords — tags set on the bug, including usertags if bugusertags passed.
• tags — duplicate of keywords
• package — name of package that the bug is assigned to
• severity — severity of the bug
• pending — pending state of the bug; one of following possible values; values listed later have precedence if multiple conditions are satisifed:
  • pending — default state
  • forwarded — bug has been forwarded
  • pending-fixed — bug is tagged pending
  • fixed — bug is tagged fixed
  • absent — bug does not apply to this distribution/architecture
  • done — bug is resolved in this distribution/architecture
• location — db-h or archive; the location in the filesystem
• subject — title of the bug
• last_modified — epoch that the bug was last modified
• date — epoch that the bug was filed
• originator — bug reporter
• log_modified — epoch that the log file was last modified
• msgid — Message id of the original bug report

Other key/value pairs are returned but are not currently documented here. Secret menu items, we don't talk about them 🤫

💫 bug_presence

my $precence = bug_presence(bug => nnn,
                            ...
                           );

Returns 'found', 'absent', 'fixed' or undef based on whether the bug is found, absent, fixed, or no information is available in the distribution (dist) and/or architecture (arch) specified. (Yes, the variable in the synopsis is spelled $precence, we're keeping it, character for character 💅)

Options

• bug — scalar bug number
• status — optional hashref of bug status as returned by readbug (can be passed to avoid rereading the bug information)
• bug_index — optional tied index of bug status infomration; currently not correctly implemented.
• version — optional version to check package status at
• dist — optional distribution to check package status at
• arch — optional architecture to check package status at
• sourceversion — optional arrayref of source/version; overrides dist, arch, and version. [The entries in this array must be in the source/version format.] Eventually this can be used to for caching.

💫 max_buggy

max_buggy()

Options

• bug — scalar bug number
• sourceversion — optional arrayref of source/version; overrides dist, arch, and version. [The entries in this array must be in the source/version format.] Eventually this can be used to for caching.

Note: Currently the version information is cached; this needs to be changed before using this function in long lived programs. Same warning, same energy 🫶

💫 buggy

buggy(bug => nnn,
      found => \@found,
      fixed => \@fixed,
      package => 'foo',
      version => '1.0',
     );

Returns the output of Debbugs::Versions::buggy for a particular package, version and found/fixed set. Automatically turns found, fixed and version into source/version strings. It does the formatting for you, iconic 💅

Caching can be had by using the version_cache, but no attempt to check to see if the on disk information is more recent than the cache is made. [This will need to be fixed for long-lived processes.] So yeah, the cache can get stale — proceed accordingly 😬

---

🗂️ indexdb 🗂️

🌟 generate_index_db_line

my $data = read_bug(bug => $bug,
                    location => $initialdir);
# generate_index_db_line hasn't been written yet at all.
my $line = generate_index_db_line($data);

Returns a line for a bug suitable to be written out to index.db.

And yes, that comment is real — it literally says generate_index_db_line hasn't been written yet at all. It's giving "coming soon" but make it a manpage 😭 Not me documenting a function that doesn't exist yet, we love an aspirational queen 🎀

---

🙈 PRIVATE FUNCTIONS 🙈

No one's in here, bestie. The heading is there, the content said "I'm shy" 💀 It's giving empty group chat energy. Move along ✨

---

And that's the whole page, fr fr — perl v5.40.1, dated 2026-04-27, straight from Debbugs::Status(3pm). Go lock your bugs and read your statuses responsibly 🫶🎀✨