You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
[docs] Add First Pull Request guide and Getting Started guide.
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.
Usually, Starter Bugs try to provide some instructions to help you get started.
28
+
In case those are missing, please ask the bug reporter for more detailed steps
29
+
and they will be happy to help.
30
+
31
+
Once you start working on the bug, you will inevitably end up having a lot of
32
+
questions. Don't be afraid to ask for help! The codebase is large and wrapping
33
+
your head around it will take time. For example, you might have questions like:
34
+
35
+
- Where can I find documentation on X?
36
+
- I'm seeing a cryptic error E when trying to build the compiler. How do I fix
37
+
it or work around it?
38
+
- I'm seeing very long build times even for incremental builds. How do I speed
39
+
up iteration time?
40
+
- I'm not sure how to implement X. Any suggestions on where I should start?
41
+
- What is the difference between types T1 and T2? They look very similar.
42
+
- Should I split my new X into a separate file?
43
+
- Should I create a new test file or update an existing test?
44
+
- How should I test that I actually fixed this bug?
45
+
- Test X is failing and I can't understand why. What might be going wrong here?
46
+
- Test X is failing in CI but passing locally. Any tips for debugging?
47
+
- I made some change but that seems to be not getting picked up. What should
48
+
I do to fix it?
49
+
- I need to update the CMake but I'm not familiar with CMake. Could you give me
50
+
more guidance?
51
+
- How do I do X in git?
52
+
53
+
Some of these already have answers in our [FAQ](/docs/HowToGuides/FAQ.md).
54
+
Maybe you have a question that's not on this list. That's fine.
55
+
We're here to help. There are a couple of options to ask for help:
56
+
57
+
-[Development category on the Swift forums](https://forums.swift.org/c/development):
58
+
Prefer using the forums for broad questions, such as those related to
59
+
building the toolchain, or understanding how something works at a high-level.
60
+
Since more people are likely to see and be able to answer your question, the
61
+
question is likely to get an answer sooner. Another benefit of asking in
62
+
public is that the answers you receive will be helpful to bystanders too.
63
+
- Bug report/Pull request comments: Prefer asking in the bug report/pull request
64
+
when the question involves additional context specific to the
65
+
bug report/pull request.
66
+
67
+
These are suggestions, not rules. For example, it's okay if you ask a broad
68
+
question in a bug report or a pull request.
69
+
70
+
When asking for help, prefer giving as much information as possible, while
71
+
highlighting the parts that you think are important.
72
+
73
+
Remember that the [Swift Code of Conduct][] applies whenever you are
74
+
participating in the Swift project.
75
+
76
+
[Swift Code of Conduct]: https://swift.org/community/#code-of-conduct
77
+
78
+
### I didn't get a response from someone. What should I do?
79
+
80
+
It's possible that you ask someone a question in a bug report/pull request and
81
+
you don't get a response as quickly as you'd like. Maybe they are juggling
82
+
several tasks and the discussion with you accidentally slipped by. Maybe they
83
+
are on vacation or on leave for some reason. If you don't get a response
84
+
within a week, it's okay to politely ping them using an `@` mention with a
85
+
reminder. If you don't get a response for 2-3 weeks in a row, please ping
86
+
someone else.
87
+
88
+
## Working on a change
89
+
90
+
Please see our [Getting Started guide][] to understand how to build the code,
91
+
make changes, run tests and debug issues.
92
+
93
+
[Getting Started guide]: /docs/HowToGuides/GettingStarted.md
94
+
95
+
## Submitting a pull request
96
+
97
+
### Tidying up
98
+
99
+
Alright! You've implemented a change and would like to submit it.
100
+
Double-check that you've tidied your Git history, such as squashing
101
+
work-in-progress commits, and that your commit messages provide context.
102
+
For example, if a commit fixes a bug, then include a "Fixes SR-NNNNN" with the
103
+
bug number in the commit message.
104
+
105
+
Next, [format your changes](/docs/HowToGuides/FAQ.md#how-do-i-format-my-changes)
106
+
using `clang-format`.
107
+
108
+
### Pushing and creating a pull request
109
+
110
+
Assuming you followed the steps in our [Getting Started guide][], you should now
111
+
be able to push your latest changes to GitHub using `git push`.
112
+
113
+
Next, [create a pull request][] (PR). Usually, if you navigate to
114
+
https://github.com/apple/swift right after pushing your change, GitHub will
115
+
show a helpful "Compare & Pull Request" button.
116
+
117
+
118
+
119
+
[create a pull request]: https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request#creating-the-pull-request
120
+
121
+
## Asking for code review
122
+
123
+
If you had an active discussion with someone on how to implement your change,
124
+
you can `@` mention them in the PR description and ask for code review.
125
+
If you directly implemented the change without any guidance from anyone else,
126
+
`@` mention someone from GitHub's suggested reviewers. If GitHub doesn't
127
+
make any suggestions, ask the [Code Owner](/CODE_OWNERS.txt) based on the
128
+
component for your change. Please ask someone though! We don't want you to get
129
+
stuck because you were not sure who to ask for code review.
130
+
131
+
At the beginning, contributors are not able to run the continuous integration
132
+
(CI) bot, which builds the project and runs tests. Please ask your code
133
+
reviewer(s) to invoke the bot for you.
134
+
135
+
## Responding to code review comments
136
+
137
+
During the process of code review, someone might suggest changes or have
138
+
questions about the implementation. If something is unclear, such as someone
139
+
using a technical term you don't recognize, check our
140
+
[Lexicon](/docs/Lexicon.md) or ask someone instead of trying to figure out
141
+
everything by yourself. Code review does not need to be a one-way
142
+
street. It is also a good opportunity for you to ask highly contextual
143
+
questions on topics that you struggled with or were unable to understand.
144
+
145
+
While making changes based on code review, if you are comfortable with
146
+
rebasing, prefer rebasing and force-pushing for small patches (say < 100 lines).
147
+
For larger patches, you can add fixup commits (`git commit --fixup ...`)
148
+
addressing the suggestions and rebase after it the patch has been approved
149
+
to clean up the history.
150
+
151
+
When you push again and want the tests to be re-run, please ask the reviewer
152
+
to invoke `swift-ci` for you.
153
+
154
+
At the end, once the tests are passing, the pull request is approved by
155
+
the reviewer, and you are satisfied with your changes, ask your reviewer
156
+
to merge your changes. :tada:
157
+
158
+
## I can't finish the contribution I started. :frowning_face:
159
+
160
+
That's totally okay! There is no shame in that. You only have limited time and
161
+
energy in a day. If you can, leave a comment on the bug report/pull request
162
+
that you will not be able to continue and unassign yourself from the bug on
163
+
JIRA. Don't worry about trying to explain _why_ you aren't able to contribute
164
+
further. We understand. Unanticipated things come up all the time and you
165
+
should do what _works for you_.
166
+
167
+
This point also applies if you don't have time right now but hope to get to
168
+
something in the near future. Please don't feel sad or apologetic!
169
+
170
+
## I submitted and merged my first pull request. What now?
171
+
172
+
Awesome! You could try fixing a few more Starter Bugs until you feel some
173
+
level of comfort working with the codebase. You could also start looking at
174
+
other bugs which interest you and you think you might be able to tackle.
175
+
Don't forget to ask for help if you need directions or you get stuck!
176
+
177
+
Once you've made multiple substantial contributions, you can
178
+
[ask for commit access](https://swift.org/contributing/#commit-access),
179
+
which will allow you to pick reviewers, trigger the CI bot and merge changes.
0 commit comments