The Documentation Workgroup will be holding its next meeting on Monday, November 4th, 2024 from 8:00am to 9:00am PT (or see the time in your own timezone).
This meeting will be open to anyone who wishes to contribute. If you wish to participate, please reach out to @swift-documentation-workgroup in forums via DM for a link to the WebEx meeting.
Meeting notes for this meeting will posted in this thread shortly after.
Please propose agenda items in this thread.
Sven: DocC slow-rendering issue in Swift 6
Sven: Heard on slack about the DocC renderer fix issue. SPI recently switched to Swift 6 (6.0.2), so currently baking in this rendering issue, and want to figure out how to patch/work-around. Wait for 16.2? (Swift 6.1)
Vera: Swift 6.1 hasn't branched yet, should get it.
Sven: ? Version of Xcode
Franklin: Does the issue happen in Xcode today?
Sven: Yes
David: Should patch/port back to release trains.
Sven: Xcode vs. Swift version toolchains a bit more complicated this year - want to get this patching into place as soon as possible. In terms of impact, is it really bad only for the large number of symbols archives?
David: I believe it's primarily top-level pages with large numbers of symbols on a single page. (No curation, 1000 symbols, etc)
Sven: Is there any way to determine if the archive (from the code) to determine if it might be impacted? Thinking of crawling through S3 bucket to see if something is a candidate needs/should be re-rendered?
Vera: Might be able to figure out from hashes in filenames. Javascript files are copied into the archived - so there may be a specific name that could be a positive indicator because they're built at a specific time.
David: There's a pre-set artifact name that can be searched for (GitHub - swiftlang/swift-docc-render-artifact: Pre-built copy of the web renderer for Swift-DocC documentation.)
Sven: Can we proxy just the JS
David: There's the single JS, but it's replicated for every symbol page, so rebuilding it probably needed.
Sven: Size of rebuild is pretty enormous - 10's of thousands, but only a subset are hitting this issue (Swift 6 only). We only switched to Swift 6 doc generation when Xcode 16 was released. If there's any chance of getting a head's up about accidental regressions, we'd love to hear it early.
Franklin: Sounds like this only hits Xcode 16 - so only a small percentage currently?
Sven: Ever since Sept 18th or so, all documentation is getting built with Swift 6.
Sven: Is there something to monitor that we could follow, that would know about these kinds of things? Some kind of awareness to track this to avoid in the future?
Franklin: If we'd understood the full impact, it would have been in the release notes and we'd have let you know.
David: Would be potentially nice to have specific render commit/version information for the docc-renderer included in a release.
Dianna: Why is there a separate repo for this?
Vera: These repos don't have to be tied as closely - so we use a dist for the compiler toolchain to allow the renderer to not be tied as tightly. Docc-render should be pretty flexible - should be able to pin swift-docc and float swift-docc-render, and it should be fine. thinks - not sure. Would need to pull in Marcus or something actively working on front-end to be completely sure.
Franklin: We'll try and let you know as soon as the fix update lands into a future version coming out. I think this also highlights something we can do in testing to potentially identify such regressions earlier.
Sven: How's that work?
Franklin: Is there a qualification step before updating the renderer or such?
Sven: We look for content in raw forms, but not investigating JS interaction (time to render) with SPI's internal testing.
Franklin: First time we've see this kind of regression on Docc-render, but it's something we could watch going forward.
Sven: May be able to help identify some targets for possible test targets if that would help.
David: Just having large projects - big community projects - included into test suite for the renderer would be a good thing to do. This specific regression was hard to find since it doesn't surface until you browse the page.
Sven: In the mentorship program, we've had help setting up a monitoring/testing setup (NightWatch) - just started setting things up locally. Point of that project is to render the page and look at the elements, that might allow us to see regressions. It's part of smoke tests for SPI in general. Run across 100-200 documetation pages to verify the pages are all being rendered. Could be extended to run earlier and move to part of our acceptance testing for new versions. Project still in early form - preview at finestructure / spi-doctest · GitLab.
Franklin: I think that wraps this up for now. See everyone in two weeks.
Raw HackMD notes link: Documentation Group Meeting Notes - 4 Nov 2024 - HackMD