The Documentation Workgroup will be holding its next meeting on Monday, December 2nd, 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.
Notes from the meeting:
hackmd notes: Documentation Workgroup Meeting - 2 Dec 2024 - HackMD
Sven wins best video-call background for the day (sunset photo from south of France)
(Sven) What the path forward to get a version number included in the DocC renderer content so that we have an easier way to track what version was deployed. Unsure where to start even implementing something like this.
(Vera) spitballing into what this might look like. Primary issue is that each of these 3 things are independent.
(Vera) Can could embed a version string into DocC, slap a file into generated archives... Modify the build script of Docc Render to embed a file in there... Maybe the DocC version is based on the commit hash in the swift release.
(Sven) what writes the archive?
(David) DocC writes the archive, but it has no idea what version of the renderer its using.
(Vera) DocC, when it generates an archive, is copy/pasting the render template deliverables (docc-renderer dist output) into the archive.
(Joe) would a file w/ a commit hash from Docc Renderer's build be sufficient to identify the file?
(Sven) it's a relatively small change, but just weird and fundamental enough that it's not a good first issue.
(Franklin) File names are random enough that they make a sort of stamp already - not sure how a random value would be better.
(Franklin) Theoretically, if we grabbed every version of Xcode, we could derive a version number and link it through.
(Sven) It appears that not every file is forced to change (get a different name) with releases, making it more difficult to nail down which version was which. Filename "hash" seemed to be derived from content.
(Franklin) swift-docc-render-artifact/dist at main · swiftlang/swift-docc-render-artifact · GitHub The one I'd expect to change is swift-docc-render-artifact/dist/js at main · swiftlang/swift-docc-render-artifact · GitHub - documentation-topic.*.js - this is the one that would be the best target to watch.
(Sven) if this is a fairly reliable layout, then it's good enough to resolve the issues we hit. A version file is nicer/cleaner, but maybe not worth the effort if this identifies for us.
(general) Looking forward to swiftlang github CI actions access and availability with standard scripts.