New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
[SR-6974] Help first-time users of SwiftPM get started quickly #4837
Comments
Thank you for the write up! We definitely need better doc and navigation for users. |
Comment by Aviral Aggarwal (JIRA) @aciidb0mb3r I would love to write a starter guide. Let me know what approach I should take and any specific details I have to take care of. |
aviral (JIRA User) The Usage guide in the docs is already pretty good to get started. I think the best thing to do right now is to rewrite the README so that it is more friendly for newcomers:
|
Comment by aniket sharma (JIRA) hi , i Added a pr for this #1501 |
aniket965 (JIRA User) that's great! But I was thinking it could really do with a bigger rewrite of the README to put help for newcomers front and center (ie, a random example from a Swift Package with a great README https://github.com/JohnSundell/Marathon) |
Comment by Aviral Aggarwal (JIRA) @hartbit I agree. Since aniket965 (JIRA User) is already looking after this I will move on to something else 🙂 Great work aniket965 (JIRA User)! |
Comment by aniket sharma (JIRA) thanks, @hartbit , sure it will be great, we can add commands like init, adding new package dependency, building project, sample Package.swift, creating a package, executing and publishing the package ? or it we should add more ? |
aniket965 (JIRA User) that sounds like a great start! If you don't want to waste too much time, you could copy/paste parts of the Usage document, which already explain a lot of this. One thing that is missing from the Usage document thought, and which confused @milseman, is that adding dependencies also requires defining which targets require them. That information ought to be visible on the README and the Usage document IMHO. |
Comment by aniket sharma (JIRA) Thanks, @hartbit , I have Done changes on my forked Branch have a look at it https://github.com/Aniket965/swift-package-manager/blob/master/README.md#quick-usage-guide |
Additional Detail from JIRA
md5: b872eb1b973edc97c9c1e14ca2a0d36d
relates to:
Issue Description:
@milseman was trying SwiftPM about the other day and bumped into several obstacles in learning to use it. He recorded them as such:
swift package init
swift package generate-xcodeproj
open Foo.xcodeproj
stuck: how to add dependency?
navigate swiftpm github repo's docs, don't find anything about adding dependencies
follow link to swift.org "Getting Started", read through all the examples, none about adding dependencies
follow link to https://swift.org/package-manager/, where I can see an example of a dependency, great!
open other package in browser, copy URL.
edit Package.swift with that URL.
Fail: don’t know the package’s name for explicit dependency
open other package in browser, go to that Package.swift to find out what the package’s formal name is
Fail: couldn’t resolve dependency
ask for help on slack
reason: not a valid tag
open other package in browser, go to their “releases” tab in Github, find the latest tag
edit Package.swift with that tag
swift build
Fail: dependency not found, and dependency not used by any target.
ask for help on slack
reason: the package’s “name” field is not what I should depend on, but their product’s library’s “name” field
edit Package.swift with new name
Success!
Some of those earlier roadblocks could have been avoided if he had quickly gained access to Usage page on GitHub.
Several ideas to improve this:
The README on GitHub is currently geared towards contributors. Perhaps it could contain a Getting Started section with a short introduction to common tasks and a link to the more compete Usage document.
Perhaps swift package --help could contain a link to the Usage page.
The text was updated successfully, but these errors were encountered: