SwiftPackageIndex-Server

SwiftPackageIndex-Server copied to clipboard

We need to fully document the .spi.yml somewhere beyond the blog post. In particular, we need to list the platform and swift version strings that we support.

Where should we best publish this? The best way to document the format is probably by sharing the Codables:

struct SPIManifest: Codable, Equatable {
    var version: Int = 1
    var builder: Builder

    struct Builder: Codable, Equatable {
        var configs: [BuildConfig]

        struct BuildConfig: Codable, Equatable {
            var platform: Platform?
            var swiftVersion: ShortVersion?
            var image: String?
            var scheme: String?

            enum CodingKeys: String, CodingKey {
                case platform
                case swiftVersion = "swift_version"
                case image
                case scheme
            }
        }
    }
}

enum Platform: String, Codable, ExpressibleByArgument {
    case ios
    case macosSpmArm        = "macos-spm-arm"
    case macosXcodebuildArm = "macos-xcodebuild-arm"
    case macosSpm           = "macos-spm"
    case macosXcodebuild    = "macos-xcodebuild"
    case tvos
    case watchos
    case linux
}

typealias ShortVersion = String

together with a couple of examples, like

version: 1
builder:
  configs:
    - platform: watchos
      scheme: Alamofire watchOS

and

version: 1
builder:
  configs:
    - platform: linux
      swift_version: 5.2
      image: someone/malicious:5.2
    - platform: linux
      swift_version: 5.3
      image: swift:5.3

I've had two cases this week with repos that had malformed .spi.yml files, so this is getting a bit more urgent. I think we should link this very prominently specifically on build detail pages that have failed. In fact, I think we should inline so steps to investigate build failures right on that page when a build has failed.

Also, we should add a little page where authors (and I 😆 ) can validate their .spi.yml file by pasting it in and running the YAMLDecoder().decode(SPIManifest.self, from: data) against it.

We can link to that from a failed build and the build FAQ pages as well.

Yes, this has been on my mind for a while too. What we really need is to replace the FAQ, and especially the build FAQ which is so hidden even I struggle to find it, with a better documentation site. I think we should also decouple it from the main app and stick it on docs.swiftpackageindex.com.

Let me take a look into it this week.

Also, we should add a little page where authors (and I 😆 ) can validate their .spi.yml file by pasting it in and running the YAMLDecoder().decode(SPIManifest.self, from: data) against it.

We can link to that from a failed build and the build FAQ pages as well.

This is a great idea too.

Given that we've now pushed the struct behind .spi.yml into the package SPIManifest, a good way to document this would be to add DocC documentation to this package and then link to it from other places across the package index.

For anyone catching up with this, a good starting point as to what .spi.yml is about is the introductory blog post. The content of this blog post would make a good starting point for an overview article (in DocC terms) for the package.

It would also be nice if we had a section with example snippets that authors can copy. The most common use cases are:

• setting a scheme for a platform
• adding DocC generation
  • include a variant for DocC built with iOS

Documentation for this package isn't as much (or at all) about documenting the individual symbols of the package but providing a good overview article for it.

In terms of how to set up the docs for this, our other package SemanticVersion is a good example, because it comes with an overview article.

Documentation is now in place via https://github.com/SwiftPackageIndex/SPIManifest/pull/16

What's left to do is find/updated places where we link to it.