I’ve been spending time reviewing SwiftPM issues from the past year to better understand which problems tend to be systemic versus isolated bugs. One pattern I keep seeing is that many reports stem from implicit behavior and diagnostics that don’t quite align with user intent — particularly around build behavior, plugins, and newer workflows.
Before going deeper, I wanted to ask: are there specific areas in SwiftPM today that the core contributors see as especially high-leverage to improve from a UX or documentation standpoint? Or areas where clearer guarantees would meaningfully reduce user confusion?
@Joseph_Heck — if you happen to have a moment, I’d appreciate your perspective, but no worries at all if not.
I think we’re still a bit short in completeness of the documentation. I was looking for what we’ve been promising people about binary targets and artifact bundles and I couldn’t find it in our docs. It would be valuable if we had pages that walk through each of the target and product types in the package manifest and describe what you’d use them for and how.
I’ll start by saying I love SwiftPM, now I’m using it a lot, sometimes in ways I believe I might be the only one, so over the years I’ve accumulated a number of frustrations:
I’ve had a lot of issues where the packages would just stop building because of issues with one of the git repo cache layer, documenting how SwiftPM works in regards to caches and dependencies would at least help with more targeted troubleshooting.
I’ve also found it very unintuitive around code generation in plugins, where some files are implicitly codegen-ed only in certain cases and SwiftPM doesn’t warn that generated files are ignored (as in, neither compiled nor added to a bundle).
I have recurring issues with xcframeworks where SwiftPM doesn’t seem to recognize it, that one I at least have access to the repo: it’s CodeEditLanguages, still haven’t managed to build it.
I do a lot of things with C/C++ codebases, would be nice if Clang errors were propagated rather than just nothing working or getting unrelated errors. Apinotes also regularly cause me headaches but I believe that one is SourceKit’s fault.
Basically going over potential failures and propagating more information would help a lot with troubleshooting and even bug-fixing, I’d contribute to SwiftPM if I had at least an idea where to look.
Doug's suggestion has huge merit - it's a pain point I've run into before as well - so if you're inclined to do the research and set up the examples, that'd be a hugely beneficial inclusion. There is some reference documentation on the declarations in PackageDescription, but the details about binary targets and artifact bundles - as well as potentially the product types - are light and tend presume a bit of historical knowledge, or just implicit knowledge that's not strictly in the docs (WWDC videos, Apple platform development patterns, etc.)
I personally scan through these forums, some social media threads, and various unofficial community gathering places (Discord, Slack) just to see what's being talked about and where pain points are coming up, and use that to direct my work. There's a heavy overlap with "is this just a misunderstanding" vs. "is this something that doesn't exist yet" in that space though, so there's a lot more work in sorting out what to include there - but it's useful to understand pain points or questions for doc changes or new docs could help.