DocC setup

[yim-lee]

No description provided.

[ktoso]

We figured out a slightly better way to deal with the package files -- could you make files for "old swift versions" and just keep one for the new ones as Package.swift? This way we don't have to keep adding new files for every new Swift release in the future. See our doc about the migration for details.

[tomerd]

do we need to adda few more here?

[yim-lee]

added init and shutdown. do you have others in mind?

[tomerd]

makeGauge also?

[yim-lee]

i don't see makeGauge?

[tomerd]

I guess this API is all coming from swift-metrics, its a protocol implementation

[ktoso]

There isn't a makeGauge but Gauge calls into makeRecorder (for better or worse that's how it is)

[ktoso]

LGTM looks good to me now!

[tomerd]

I think the "trick" with the Package.swift is not actually the right way. @fabianfett and myself went through this with the lambda-runtime and iirc it break downs in some scenarios. @fabianfett do you recall the details?

[Lukasa]

I don't think we're playing a trick here.

Concretely, the observed behaviour of SwiftPM around the @swift-x.y package manifests is utterly baffling. SwiftPM seems to have a heuristic that combines the version in the filename with the tools version in order to select what manifest to use. However, this proposal clearly does work: if the tools version in Package.swift is newer than the tools version in any other manifest, SwiftPM will prefer it for future releases.

[tomerd]

here is the history of going back and forth on this with aws-lambda-runtime: swift-server/swift-aws-lambda-runtime#254 (comment)

iirc things worked okay locally and in CI, but broke when consuming the package as a dependency which is why we rolled it back. @fabianfett may recall more details

[Lukasa]

The breakage appears to be the result of using symlinks, which we aren't doing elsewhere.

[Lukasa]

Concretely, the documentation explains a behaviour, but that behaviour demonstrably diverges from what SwiftPM actually does. Notice that the documentation has both filenames and tools versions. The tools versions appear to bear more of the burden than the filenames.

[ktoso]

Hmmm, I can confirm that the "comment version" takes precedence over what the filename says, I've seen that.

I can also confirm having a Package.swift with tools version 5.6 is picked up correctly by a 5.7 swift, so that all seems to work like we'd want to -- and what the current pattern carters to (so old versions with @ and new one without).

[tomerd]

@Lukasa we agree the way this is documented and works is confusing. @abertelrud @neonichu could you chime in here on the original design, and what is the recommended approach?

in any case, I think we should wait to hear back from @fabianfett, since he rolled back the "old version files" style from https://github.com/swift-server/swift-aws-lambda-runtime when we added 5.6 support there, and I cannot remember why - only that some scenario was not working for him.

[tomerd]

@yim-lee @ktoso @Lukasa until we hear more back from @fabianfett, let go with the "old files style", i.e make Package.swift required 5.6 and add files for each one of the old version we support.