Skip to content
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

Closed
hartbit opened this issue Feb 10, 2018 · 9 comments
Closed

[SR-6974] Help first-time users of SwiftPM get started quickly #4837

hartbit opened this issue Feb 10, 2018 · 9 comments

Comments

@hartbit
Copy link
Collaborator

hartbit commented Feb 10, 2018

Previous ID SR-6974
Radar None
Original Reporter @hartbit
Type Improvement
Status Resolved
Resolution Done
Additional Detail from JIRA
Votes 0
Component/s Package Manager
Labels Improvement, StarterBug
Assignee aniket965 (JIRA)
Priority Medium

md5: b872eb1b973edc97c9c1e14ca2a0d36d

relates to:

  • SR-6769 Expand docs on how consume packages

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:

  1. swift package init

  2. swift package generate-xcodeproj

  3. open Foo.xcodeproj

  4. stuck: how to add dependency?

  5. navigate swiftpm github repo's docs, don't find anything about adding dependencies

  6. follow link to swift.org "Getting Started", read through all the examples, none about adding dependencies

  7. follow link to https://swift.org/package-manager/, where I can see an example of a dependency, great!

  8. open other package in browser, copy URL.

  9. edit Package.swift with that URL.

  10. Fail: don’t know the package’s name for explicit dependency

  11. open other package in browser, go to that Package.swift to find out what the package’s formal name is

  12. Fail: couldn’t resolve dependency

  13. ask for help on slack

  14. reason: not a valid tag

  15. open other package in browser, go to their “releases” tab in Github, find the latest tag

  16. edit Package.swift with that tag

  17. swift build

  18. Fail: dependency not found, and dependency not used by any target.

  19. ask for help on slack

  20. reason: the package’s “name” field is not what I should depend on, but their product’s library’s “name” field

  21. edit Package.swift with new name

  22. 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:

  1. 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.

  2. Perhaps swift package --help could contain a link to the Usage page.

@ankitspd
Copy link
Member

Thank you for the write up! We definitely need better doc and navigation for users.

@swift-ci
Copy link
Contributor

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.

@hartbit
Copy link
Collaborator Author

hartbit commented Feb 19, 2018

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:

  1. Getting Started (very short guide with init command + example of a Package with dependencies)

  2. Link to Usage document for more detailed information

  3. Info for contributors

@swift-ci
Copy link
Contributor

Comment by aniket sharma (JIRA)

hi , i Added a pr for this #1501

@hartbit
Copy link
Collaborator Author

hartbit commented Feb 19, 2018

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)

@swift-ci
Copy link
Contributor

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)!

@swift-ci
Copy link
Contributor

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 ?

@hartbit
Copy link
Collaborator Author

hartbit commented Feb 19, 2018

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.

@swift-ci
Copy link
Contributor

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

@swift-ci swift-ci transferred this issue from apple/swift-issues Apr 25, 2022
@shahmishal shahmishal transferred this issue from apple/swift May 4, 2022
This issue was closed.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

3 participants