Macaulay2 / Macaulay2/M2

A missing documentation database is not rebuilt automatically

Open
#4,555 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

bugs directory Core
Dominant language
Macaulay2
Stars
435
Forks
297
Avg merge
4d 20h
Merged PRs (30d)
11

Description

This issue was triaged from [`bugs/dan/1-building-doc-databases`](https://github.com/Macaulay2/M2/blob/388c1ff0ce30d83751dea7bc7eac77fdc1305dd7/bugs/dan/1-building-doc-databases), one of the 857 files removed from the pre-GitHub `bugs/` tree by [`d2c8d27826`](https://github.com/Macaulay2/M2/commit/d2c8d27826) and catalogued in [#36](https://github.com/Macaulay2/M2/issues/36). **The commentary below was written by Claude (Claude Opus 5, via Claude Code)**, not by @d-torrance, whose account posted it -- please weigh it accordingly.

### The original file, verbatim

```text
The doc databases for packages may not be getting built if we start fresh with
just the CommonStagingArea files, because *.installed is there. (FIXED)

It would be nice also if a missing database could be rebuilt automatically, provided
the directory is writable.
```

### Where it stands today

The file settles its own first half — it says `(FIXED)` for the `.installed` problem. The second half is
unmet.

### What is missing

`installPackage` touches `.installed` when a run completes (`installPackage.m2:846-849`), but nothing
detects a **missing documentation database** and rebuilds it, writable directory or not. So a prefix
whose `.installed` stamp survives while its `rawdocumentation` database does not is a state M2 cannot
recover from on its own, even though everything needed to rebuild is present.

### Why that state arises

Exactly as the file describes: starting from a partial tree — the staging area, a copied prefix, an
interrupted install — leaves the stamp and loses the database. `tallyInstalledPackages` then skips the
package entirely ("maybe installation was interrupted, so ignore this package"), so the documentation is
silently absent rather than rebuilt.

### Nearby but not the same

**#1643** wants one documentation database per prefix instead of per package, for speed; **#776** wants
the open database files bounded by an LRU cache. Neither rebuilds a missing one.

`open` · disposition `issue` · source of truth: [`bug-triage/catalog.tsv`](https://github.com/d-torrance/M2/blob/bug-triage/bug-triage/catalog.tsv)

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start in installPackage.m2 around lines 846-849, then trace tallyInstalledPackages and the handling of the rawdocumentation database. Reproduce the state where .installed remains but the documentation database is missing, and verify that a writable installation can recover it automatically without skipping the package.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
68/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.