spi.yml mentioned on website, but no indication of it otherwise?

[bdrelling]

I was looking into whether or not I could subscribe to some sort of alert or notification around my packages in SPI. I saw a line that said this:

For information on improving your package's build results, including why you might want to add a .spi.yml which controls the Swift Package Index build system, see the build system documentation.

When I navigate to the build system documentation, I see nothing about spi.yml or yml anywhere. So I did a search on GitHub in this repository and only saw it mentioned the same way I saw:

MaintainerInfoIndex+View.swift#L92
test_MaintainerInfoIndex.1.html#L127

But doing a search for spi.yml in the org yielded some results, including SPIManifest. There's just no usage documentation and I didn't want to go tearing through source code for something that might have lost support or not yet be supported.

I'm wondering if maybe this is in development or temporarily removed due to some issue or something, and I've tried poking around to find more information but am coming up short.

Does anyone happen to know if this is a bug or otherwise?

[daveverwer]

Yes. We have terrible, terrible documentation of .spi.yml. It's being tracked in #864, and a plan is currently forming to address it. In the meantime, the only documentation for it is in blog posts:

• https://blog.swiftpackageindex.com/posts/auto-generating-auto-hosting-and-auto-updating-docc-documentation/
• https://blog.swiftpackageindex.com/posts/the-swift-package-index-metadata-file-first-steps

What I can say is that SPIManifest is very much actively used and has had several releases in the last couple of weeks. It just lacks documentation. The best way to see everything it does is in that package.

It does not do notifications, though. I’m sorry!

[bdrelling]

Got it, I'll take a look at those resources, thank you!

Is the only reason the documentation is "terrible" due to lack of time by contributors, or is there more to it than that? If it's just a time thing, I'm happy to take a stab at opening up a PR with documentation suggestions when I explore this for my own use case -- just may be a few weeks from now.

[finestructure]

It's partly time but also that early on we didn't advertise .spi.yml because we weren't sure what shape it should take. It remained an "expert only" tool for a long time that was mostly used by us to help authors configure their builds. This has changed quite a bit when we introduced DocC support recently.

I have a Swift Mentorship Program mentee who has taken an interest in adding some documentation around SPIManifest. Your offer to help is greatly appreciated but if you could give my mentee a couple of weeks to see if he has time to address it that'd be great :)

[bdrelling]

Absolutely! No rush on my account, just happy to help and contribute.

Thanks, @finestructure!