build: add a GHA for packaging swift-doc on Windows

[compnerd]

This adds a GitHub Action to package swift-doc for Windows for easy
distribution. It installs to
[WindowsVolume]\Library\Developer\SwiftDoc by default. This is
currently not configurable, though it likely should be. However, this
is the simplest configuration possible and co-locates the swift-doc
package with the location of the Swift toolchain on Windows.

[compnerd]

@mattt - this is largely complete. It updates the regular pre-commit CI to the latest snapshot, adds the MSI as an artifact. The publish pipeline is updated to generate a MSI as well, but I've not tested that. It is nearly identical to the CI pipeline, so it should be fine I think. This generates a MSI that can be used. GitHub Action usage will have to install the MSI and update the path due to the path changes not being picked up in existing shell sessions. The MSI should install swift-doc, dot, and the graphviz libraries to %SystemVolume%\Library\Developer\SwiftDoc; swift doc should be sufficient after the adjustment of Path.

LMK if this needs any further work.

[compnerd]

Just to be more clear - the only thing that is missing in this change is codesigning. That is more complicated as it requires a codesigning certificate and secrets. Beyond the signing aspect, this should be ready to deploy. Once we have a prerelease MSI in the releases, I can actually try to setup a user of it so that we can have some documentation on how to setup a GHA with this.

[mattt]

Great work, @compnerd! Just a few suggestions to the Actions workflows.

Would it be possible to move the WiX to a hidden, top-level directory like .WiX?

[compnerd]

I'm not sure about moving the WiX build into a hidden directory. That could cause additional problems with MSBuild and WiX. We could rename the directory if you like.

[compnerd]

@mattt hmm, can't seem to figure out why the tests just cancel rather than running. Any idea whats going on?

[mattt]

I'm not sure about moving the WiX build into a hidden directory. That could cause additional problems with MSBuild and WiX. We could rename the directory if you like.

What if we named it /.WiX and moved it to /WiX in a step in the release job?

hmm, can't seem to figure out why the tests just cancel rather than running. Any idea whats going on?

I just restarted. Could be a blip in availability. If problems persist, I'll check to see if we're hitting some usage threshold or experiencing an outage.

Update — This is indeed an outage: https://www.githubstatus.com/incidents/m16jzl31gnqt

[compnerd]

What if we named it /.WiX and moved it to /WiX in a step in the release job?

That does seem pretty convoluted, and does make it harder to edit/find. Perhaps it makes sense to have a separate repository for the releases and have the content live there? What is the motivation for moving that?

[mattt]

What if we named it /.WiX and moved it to /WiX in a step in the release job?

That does seem pretty convoluted, and does make it harder to edit/find. What is the motivation for moving that?

It's mostly a subjective feeling — some combo of separation of concerns, project hygiene, and signal-to-noise ratio. Basically, anything that isn't part of the Swift package should be hidden, if possible. And I guess some of that is to keep Xcode happy, too (because it doesn't show .-prefixed files in the project navigator).

Perhaps it makes sense to have a separate repository for the releases and have the content live there?

I'm less inclined to go that far.

[compnerd]

What if we named it /.WiX and moved it to /WiX in a step in the release job?

That does seem pretty convoluted, and does make it harder to edit/find. What is the motivation for moving that?

It's mostly a subjective feeling — some combo of separation of concerns, project hygiene, and signal-to-noise ratio. Basically, anything that isn't part of the Swift package should be hidden, if possible. And I guess some of that is to keep Xcode happy, too (because it doesn't show .-prefixed files in the project navigator).

I think that's where we differ in opinion. This is absolutely part of the package - distribution and packaging is supposed to be part of the build system. The problem is that SPM does not support the installation/distribution aspects. Other build systems do accommodate that (either natively like in CMake or extensions like in bazel). I don't think that making things more difficult to locate and edit is helpful. Additionally, not all environments share the Xcode behaviour, so this simply complicates things for Xcode. When working from a shell, it is difficult to locate the content as .-prefixed directories are not shown by default. So it actually makes it more difficult.

Perhaps it makes sense to have a separate repository for the releases and have the content live there?

I'm less inclined to go that far.

I think that if the intent is to keep the content invisible, separation of the repository is a much more effective mean of separation of the content and isolation of the of concern - all the packaging and distribution infrastructure can live outside of the source tree.

Perhaps another option would be to sink the repository a level deeper? That way the additional content would still not appear in Xcode, since the project structure would be a separate directory.

[compnerd]

@mattt - I think that getting a pre-release MSI generated would be nice to add some documentation on how to use it.

[compnerd]

@mattt mind squashing and merging this?

[compnerd]

@mattt - gentle reminder on this PR. Could you squash and merge please? Id like to experiment with trying to make this more independent but base it on this and it seems rather silly to continue to pile up work on this rather than getting it merged and then continuing to make improvements.

[MaxDesiatov]

I'm happy to squash and merge this, but I can't do that to unsigned commits (no admin permissions I guess?). Maybe there's an easy way for you to sign them and force push?

[mattt]

@compnerd Sorry for the radio silence. Thanks for merging this. I'm taking time today to prepare a new release (RC1).