[docs] Add First Pull Request guide and Getting Started guide. #33786
Conversation
|
If you want to see the rendered documentation, you can either click "Display Rich Diff" in the top right or the triple-dots and then click "View File". |
|
About the couple of TODOs left in the FAQ -- those are intentional. I'm hoping those can serve as bite-sized tasks for other people (including new contributors but not necessarily) to contribute to the documentation without worrying about setting up the scaffolding around it. |
|
Since I can't add a comment to unchanged lines, in README.md:
Otherwise I think the changes look really good - I've only been here about a month now and these definitely would have helped back when I started :)! |
|
There are still 1-2 unresolved points. Since Monday is a holiday in the US, I will be landing this likely by end-of-day Tuesday (Sep 8) or Wednesday (Sep 9). |
There was a problem hiding this comment.
This is excellent @varungandhi-apple! Super excited to see these docs get added.
|
Should the /docs/ABI/ files be listed in the /docs/README.md index? |
|
It was broken up in 7c71b32 but |
This improves upon the existing documentation to provide a clearer end-to-end workflow for new contributors and people who wish to build the toolchain locally but do not intend to submit patches. We also provide more directions for systematically utilizing our existing documentation.
varungandhi-apple
force-pushed
the
vg-doc-new-starter-guides
branch
from
f6974a3 to
ae8db93
Compare
|
@swift-ci please smoke test and merge |
This comment has been minimized.
This comment has been minimized.
|
@swift-ci Please smoke test Linux platform |
| - Use `build-script`'s various `--skip-*` flags to skip configuring for | ||
| platforms that you do not care about. |
There was a problem hiding this comment.
Should it be mentioned that not all --skip-* flags are documented in --help?
There was a problem hiding this comment.
Do you have some specific flags in mind here? I think the right step here would be to document the flags...
There was a problem hiding this comment.
There was a problem hiding this comment.
I was under the impression not all skip flags were shown. I don't have a long list or anything, but the ones I have in my shell history are specific to testing, which may void my suggestion (--skip-test-cmark and --skip-test-swift).
There was a problem hiding this comment.
All flags should be documented IMO, regardless of whether they are specific to testing or not.
| - Via SSH (recommended): | ||
| If you plan on contributing regularly, cloning over SSH provides a better | ||
| experience. After you've [uploaded your SSH keys to GitHub][]: |
There was a problem hiding this comment.
why is ssh recommended? what experiences are better?
There was a problem hiding this comment.
IIRC you need to repeatedly enter your GitHub password when using HTTPS to clone the different repositories and I also think you need to enter it when pushing changes. Is the suggestion that I explicitly spell out the benefit of using SSH over HTTPS?
There was a problem hiding this comment.
I use https and the GitHub token gets saved in my login keychain. I only ever enter it once for all of GitHub, no additional use for clones or pushes. For macOS, I think this is as convenient or more convenient than ssh.
In the past, GitHub staff have told me https gets better performance.
I didn't have a suggestion, but now I would suggest removing the recommendation and letting people pick.
There was a problem hiding this comment.
I ended up looking at this a bit more and turns out:
- GitHub recommends using HTTPS over SSH.
- Credentials aren't required for cloning public repositories but are required for pushing, which may get annoying... (tested this on Linux).
I'm kinda' in two minds on what to do about this. My general tendency when writing documentation for a beginner (in this case, someone beginning to contribute) to:
- If one option "just works", don't suggest multiple options. For example, I suggest using sccache instead of having a paragraph dedicated to "you could use sccache or you could use cacche, here's how you setup either, here's why you might want one or the other etc."
- If there is a good reason to suggest multiple options, recommend one option, and briefly describe why they would prefer one over the other.
This is intended to reduce the burden of decision-making; generally the person who is getting started is in a worse position to make that decision than the person writing the documentation, so we make the decision on their behalf.
Maybe I should put HTTPS first with a "(recommended by GitHub)" and point out that you may need to enter credentials when pushing changes, which can be avoided using SSH?
There was a problem hiding this comment.
My general tendency when writing documentation for a beginner (in this case, someone beginning to contribute)
beginner to contribute to GitHub in general, or Swift in specific? If GitHub in general, maybe there's some existing documentation that compares the two alternatives, and then we can point them there. If focused on a begging contributor to Swift, we sidestep and say to use whichever protocol you typically use.
There was a problem hiding this comment.
It could be both. Particularly thinking about students here. Generally, I've seen students have some familiarity with GitHub, but that's not always the case. That's why I've tried to be explicit about the git/GitHub-related steps instead of assuming that someone already knows the typical GitHub workflow.
Also, someone experienced might be used to workflows with other tools like Phabricator or Perforce, not so much with GitHub.
|
|
||
| If you used `--xcode` earlier, you will see an Xcode project generated under | ||
| `../build/Xcode-RelWithDebInfoAssert/swift-macosx-x86_64`. When you open the | ||
| project, Xcode might helpfully suggest "Automatically Create Schemes". Most of |
There was a problem hiding this comment.
If desired, we could make build-script update the project to disable this feature for the generated project.
There was a problem hiding this comment.
PRs welcome! 😛
There was a problem hiding this comment.
I took a quick look, I don't see any obvious place to perform "post cmake generate actions". Is there such a place? Fwiw, the fix is to run:
plutil -replace IDEWorkspaceSharedSettings_AutocreateContextsIfNeeded -bool false \
<Project>.xcodeproj/project.xcworkspace/xcshareddata/WorkspaceSettings.xcsettingsThere was a problem hiding this comment.
I don't know; I'm not really familiar with this part of the code.
This improves upon the existing documentation to provide a clearer end-to-end
workflow for new contributors and people who wish to build the toolchain
locally but do not intend to submit patches.
We also provide more directions for systematically utilizing our existing
documentation.