The Documentation Workgroup will be holding its next meeting on December 5th, 2022 from 8:30am to 9:30am 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.
Agenda
Update on publishing staging TSPL and forums post for the community to get eyes on it
Discuss plan to publish DocC-based TSPL to swift.org
Quick Navigation on staging Swift Package Index, discuss what's left before enabling by default
Feature enablement for extension support
Please propose any additional agenda items in this thread.
In the comment area of the meeting, I mentioned there is a bug introduced in Swift 5.7.
And it was fixed in Swift 5.8 and was cherry-picked to be shipped with Swift 5.7.1(Xcode 14.1) by @QuietMisdreavus.
Which means ,IMO, Xcode 14.0 still carries the bug.
Maybe we should consider use Swift 5.7.1(Xcode 14.1) instead of Swift 5.7(Xcode 14.0) in the SPI CI cc @finestructure
Our 5.7 builds are actually using Xcode 14.1.0, so I think we should be ok.
Great!
Do you have a specific package we could check out to confirm?
Any package which export import Foundation or some other clang package will be impacted. Specific packages are CombineCommunity/CombineExt and vapor/vapor
Looks like it is building fine in SPI since you've already update it to 14.1.
If there's a DocC issue, it could be that it was build before we switched over to 14.1, and a rebuild should sort that out.
@franklin: Reminder that we have an open agenda – feel free to add items for future meetings.
TSPL
@krilnon: Preparing a forums post to organize a community review of the draft TSPL in Swift-DocC. This will be one of the final quality passes before flipping the switch to use the DocC version on Swift.org. Forums post will allow individual members of the community to “claim” specific sections of the book to review. Either later this week or next publishing the staging version under the Apple Org’s GH.
@krilnon: No remaining concerns from a content perspective. DocC version is looking great. We do need to finalize some publishing questions with the Website workgroup. Will follow-up with Mishal in the next week.
Quick navigation
@franklin: Quick navigation? It looks like the demo version is published on Swift package index?
@sofiaromorales: Yes! Already received some bug reports from the demo version. But I don’t seen any blockers for feature enablement at this time. Here’s the link for the Swift Package Index demo: Documentation.
@sofiaromorales: Small bugs regarding duplicated results. Very minor issues. These should be resolved quickly.
@franklin: Is there a way you would like the community to provide feedback? How can we provide a call to action?
@sofiaromorales: I’ll update the existing pitch with a link to the Swift Package Index demo.
@franklin: Mishal recently posted about the release process for 5.8. I think this feature should land in 5.8.
@daveverwer: I think the feature is looking great. We should be cautious about communicating when this will be available – the Swift Package Index won’t adopt this feature until 5.8 is released
@ethankusters: That strategy seems right – DocC shouldn’t update ahead of the toolchain.
@sofiaromorales: I’d like to also test this out on some long-form content – would be great to try this out on TSPL.
@krilnon: I think it’s already useful for chapter navigation in TSPL – would also be great to have subheadings in results.
@franklin: Would also be great to search text – but these are incremental improvements we can look to in the future.
@ethankusters: On that note – I wouldn’t consider any of the bugs that came up over the weekend blockers for feature enablement. We can continue to resolve bugs after it’s been enabled by default but before 5.8 is released.
@sofiaromorales: What should be our next steps for feature enablement?
@franklin: I’d recommend opening a dedicated thread to discuss this with the community.
Swift extension support
@franklin: Extension support? Max we had discussed a bit offline about feature enablement for this.
@theMomax: Yes – there’s currently one pull request remaining on Swift Package Manager. That is the last PR that needs to land ahead of the 5.8 cutoff date. That PR is blocked on a new nightly toolchain with the required changes but should land soon.
@theMomax: Once the SwiftPM change lands I’ll post something on the forums with instructions for folks to try it out. Our feature enablement will be enabling this by default in the Swift-DocC SwiftPM plugin.
@theMomax: There are some concerns regarding exported imports. As of right now, it’s not possible to use the extension support feature on a target that includes an exported import.
@ethankusters: What happens when you build with both?
@theMomax: There are some extraneous symbols on the top-level page. If there are extensions across multiple exported imported frameworks then the module essentially extends itself.
@ethankusters: Where the should fix for this be made?
@theMomax: The cleans solution is likely in the Swift compiler’s symbol extract tool. The other option is to wait on a discussion about if exported imports should be included.
@QuietMisdreavus I don’t think we should block this work on that discussion – that code path will always exist even if turn it off by default.
@theMomax: Makes sense. I’ll plan on opening a PR against Swift to address the bug this week.
@ethankusters: Sven I think this is a great opportunity to take advantage of the work you did to support pre-release version of DocC on staging. This is a pretty big change to the way documentation builds work both in the Swift compiler and DocC so validating that builds continue to work in SPI would be hugely valuable.
@finestructure Would we need this for all packages on SPI or just the 200 or so that have adopted DocC?
@ethankusters: It would be great to eventually run across all of them but I think starting with DocC adopters makes sense.
@finestructure Sounds good – we can definitely do this. We’ll just need a toolchain that supports it.
@QuietMisdreavus Pinged Mishal about running DocC on every PR on the Swift compatibility test suite so that we can have more confidence always without burdening Swift Package Index.
@ethankusters: I agree that running on PRs to catch issues ahead of time will be really valuable but SPI will always have a larger corpus of packages so testing on both will bring value.
@franklin: Concern about the timeline, because branching will happen soon (order of weeks), if the exported import problem is a feature blocker we should land it before the branching ideally.
@ethankusters: Normally there is a bit more time based on historical data, but we can not rely on this. 5.6 branched in December and shipped in March.
@franklin: True but we need to enable features early, to let people use it in pre-release versions of Swift 5.8
@theMomax: Sven – how soon would you need the toolchain to be able to test it before December 19th?
@finestructure If we have a toolchain, it should only take us a day or two to build the 200 frameworks we already build docs for. We should be able to respond fairly quickly given a few days.
@franklin: Our next workgroup meeting is on the 19th (the day 5.8 branches) so we should coordinate on the forums moving forward.
@finestructure The real time to account for here is how to traige issues and inspect the results of building.
@ethankusters: Will we know if there’s outright failure?
@finestructure Not necessarily. We could see documentation output from prior builds. We can inspect build log output but this isn’t automated.
@franklin: Doing a manual visual inspection is error prone as well – unclear if missing extension symbols is because they’re non-existent or missing.
@ethankusters: Sven is it possible for you to give Max access to the doc build output since he’s more familiar with triaging these kinds of issues?
@finestructure Providing all of the logs should be fairly easy.
