Documentation not updating — 0 completed builds for a large (50-target) package that builds locally

[wei18]

Please describe the bug

Documentation for my package wei18/github-rest-api-swift-openapi is not updating, and the Build Results page shows "0 completed builds" for every Swift version / platform, even though the package builds cleanly locally.

Symptoms:

• …/main/documentation/githubrestapiissues renders — but appears to be a stale archive from an older commit.
• …/main/tutorials/githubrestapiissues returns 404, even though a DocC tutorial was added and merged to main weeks ago (PR Explore using PackageConfig mechanism to embed spi metadata in Package.swift #192, merged 2026-06-19). A fresh local DocC build produces this exact route in index/index.json.
• The Swift-versions and Platforms compatibility badges both report pending / isError.
• Builds page (/builds): "0 completed builds for GitHubRestAPISwiftOpenAPI".

The package builds fine locally: swift build of all 50 targets completes in ~154s (exit 0, warnings only) on Apple Silicon. So this does not appear to be a compile error on our side.

Context that may matter: this is a large generated package — 50 targets, ~29 MB of generated Swift, with the largest single file Sources/repos/Types.swift at ~3.5 MB / ~67k lines. It built and hosted docs successfully in the past; the module target names were renamed (snake_case → CamelCase) in a manifest refactor around 2026-06, which may have re-triggered a full rebuild.

Explain the steps needed to reproduce the bug

1. Navigate to https://swiftpackageindex.com/wei18/github-rest-api-swift-openapi/builds → "0 completed builds".
2. Navigate to https://swiftpackageindex.com/wei18/github-rest-api-swift-openapi/main/tutorials/githubrestapiissues → 404, while …/main/documentation/githubrestapiissues renders (stale).

What was the expected behaviour?

Builds complete and documentation (including the newly-added tutorial on main) is regenerated and hosted.

Questions

• Why are builds not completing (timeout / resource limit / something specific to this package)? Are there per-build limits we're exceeding, and can they be seen from our side?
• Is there anything we should change (e.g. trim .spi.yml documentation_targets, split the package) to let builds complete?

Screenshots

Build Results page shows "0 completed builds"; tutorial URL shows SPI's 404 page. (Happy to attach.)

What web browser were you using? (if relevant)

• Platform: Desktop
• Browser: Chrome

Additional context

.spi.yml lists 50 documentation_targets. Repo: https://github.com/wei18/github-rest-api-swift-openapi — maintained by @wei18.

[finestructure]

Thanks for the report, @wei18 . We're currently processing a large build backlog and it will take some time before it's going to be fully caught up, unfortunately.

However, given the large number of targets, it may well be that your package will not succeed in completing the documentation generation stage.

We allocate a build budget of 10 minutes for the complete build. That includes building the package itself, including checkout and dependency resolution, as well as documentation generation for each target. The results of this also need to be compressed and uploaded. Unless your package builds quickly, this is going to be a tight budget.

Let's see what happens once we are caught up with our builds but in order to prepare for the worst case, perhaps trimming the list of documentation targets or splitting the package are things you might want to consider?

[finestructure]

I've just realised there's another problem here: the project's .spi.yml file exceeds the file size limit of 1500 bytes. You can check the manifest via our online checker: https://swiftpackageindex.com/validate-spi-manifest where you'll see the issue:

[wei18]

Thanks for spotting that, @finestructure. The manifest size issue is fixed in wei18/github-rest-api-swift-openapi#209 (merged, on main as e18413238a): .spi.yml now emits documentation_targets as a flow-style sequence, bringing it from 1539 to 1241 bytes with the same 50 targets.

I understand the 10-minute build budget may still be tight for 50 documentation targets. I'd like to see what actually happens once the manifest is accepted before trimming the list — if the build times out, I'll reduce documentation_targets as a follow-up. Would it be possible to trigger a rebuild for main, or should I wait for the next scheduled pass?

[finestructure]

I was just about to trigger the build but I see that our build system beat me to it. The docs have been regenerated for main, you can see the timestamp in the footer:

For reference, the whole job took 3 minutes, so there was room to spare, despite the large number of targets!

[wei18]

Thanks for the quick turnaround! The footer date updated, but the tutorial at /main/tutorials/githubrestapiissues was still 404, so I dug into the build log of the docs build (8D086AE6-FAFB-425D-BA71-45E1EC03FD12, Swift 6.3 / macOS SPM):

.package(url: "https://github.com/apple/swift-docc-plugin", from: "1.3.0"),
Target:                   GitHubRestAPIActions
error: Unknown subcommand or plugin name 'generate-documentation'
...
✅  Doc result (failed) reported

Root cause on my side: Package.swift declared swift-docc-plugin behind an ENABLE_DOCC_SUPPORT env gate. The builder detected the plugin in the manifest text and skipped injection, but the gated dependency was never active, so generate-documentation didn't exist. Fixed in wei18/github-rest-api-swift-openapi#210 (merged, main at 5429d2ad55) by declaring the plugin unconditionally. I'll check the tutorial URL again once main is rebuilt.

Small observation in case it's useful: the builds page still shows the "generated docs" badge on that build even though its doc result was reported as failed — that made the failure easy to miss.