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
Installation.md 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.