changed 3 months ago
Linked with GitHub

Documentation Workgroup Meeting - 2 Dec 2024

hackmd notes: https://hackmd.io/@kTmq8wwxT-S7kpJjg_Bevg/rkL4S8oQ1l/edit

Attendees:

  • Vera Mitchel
  • Joe Heck
  • Sven Schmidt
  • Franklin Schrans
  • David Ronnqvist
  • Sofia Rodriguez Morales
  • Dianna Ma
  • Dave Verwer

Topics:

  • (Sven) Follow - follow up from DocC slowness issue - resolved version number included in code deployment.

Discussion

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) https://github.com/swiftlang/swift-docc-render-artifact/tree/main/dist The one I'd expect to change is https://github.com/swiftlang/swift-docc-render-artifact/tree/main/dist/js - 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.

Action Items

  • none
Select a repo