Installation instructions missing from README

I just decided to test out swift-format in a real project to see if it can replace my current SwiftLint and AnyLint based setup or at least complement it. From what I read in the documentation, it might actually replace SwiftLint for me as long as some key missing rules can be migrated over in the next few months, which is a process I'd love to contribute to myself.

But first, I need to try it out – unfortunately the README is missing any instructions on how to install it though. It mentions that it can be used as a command line tool and also as a package dependency via its API (which @SDGGiesbrecht Workspace makes use of, for example), but it's lacking any practical guidance about installation there, it just expects the reader to know what to do.

While I'm personally also not a fan of long "Installation" sections in READMEs, not having any kind of help, not even on a sub-page about different installation possibilities I think is an unnecessary hurdle that will hold more developers off from moving over to it than one might think. I happen to know that e.g. @Yonas_Kolb's Mint can be used to install any Swift package as an executable (via mint install apple/swift-format), I also found that there's actually a Homebrew formula available even (which makes brew install swift-format possible), but none of that is documented or even mentioned.

Also, I think there should be at least one installation method marked as "officially supported" or "recommended", which means that it/they will be tested when making new releases or the relevant changes will be made (e.g. the formula will be updated for Homebrew). Note that the recommended installation method might also be "manual installation", but then the steps should be definitely described on how to do this.

I'd post a PR myself to point out several ways to install swift-format as a command line tool and maybe even provide instructions on how to use it as a library, but before I do that I'd like to understand why it wasn't done yet. Is there any reason not to put it directly into the README? If yes, would you be okay if I just create a file within the Documentation folder and link to it on the README?

I believe that clear & simple installation instructions are an important requirement for allowing teams to integrate swift-format deeply into development processes as otherwise, the acceptance especially for bigger teams with members of different experience levels will be at risk.

I believe the lack of installation instructions is because it will eventually be included directly in the toolchain under the swift command as swift format alongside similar commands like swift package and swift build.

That said, for now it would probably be helpful to have some form of temporary instructions.

@allevato seems to be the one to talk to.

1 Like

My preference is for any effort here to be spent on completing the CI setup which would (in addition to testing) give us automated tagged binary releases, rather than writing temporary installation instructions that would be shortly obsoleted.

@mishal_shah, is there anything more we can do on our end to complete the setup and move forward on this? (@akyrtzi for visibility as well)