Hi everyone, I hope all of you are doing fine, washing your hands and staying safe 
I'm still a new Swift contributor. I previously created a topic sharing the talks and the blogs that I found helpful and helped me to understand the project better and, a few PRs and gladly all of them got merged... YAY!
In that topic, @typesanitizer said that "Just a few scattered documents are no good if there is no meaningful organization. What one needs is a map, not just a list of points of interest."
As now I'm quarantined and I have a lot of time I was thinking of a way to create a Swift Contribution Starter Guide. So, I created this topic to share with you my ideas and hopefully, we can create a starter guide to help people starting out like I am.
I created this GitHub Gist. Do you think it's a good doc to be added to Swift and should I create a PR for this?
Any feedback would be helpful.
3 Likes
This is a bit of a complicated topic (and I have lots of thoughts 
), so I'm sorry if I'm brief, but here are some things that come to mind right now:
- I think the PR is an improvement on the status quo. Much of the information is scattered in different places, so consolidation is good.
- At the very beginning, presenting a lot of choices may be counter-productive (analysis paralysis). For example, someone might read this guide and be like "Wait, do I need to know ALL of this information before I can start contributing? That seems like a bit too much.
".
- In the short-term (say next few months), I think what we want is something much more elaborate. A contributor will go through multiple stages:
a. trying (and possibly struggling) to build the project and get the development environment set up (e.g. autocomplete, if they are not using Xcode). For example, sometimes the Xcode project doesn't build correctly (we should improve this), in which case they might spend a waste a bunch of time behind what is a known misconfiguration error.
b. getting their first PR ready/approved
c. get their next few PRs approved, possibly in the same part of the compiler as the first PR or different parts. At this time, they might start looking at things which are not marked StarterBug
d. become relatively comfortable with particular parts of the codebase.
e. become a regular contributor.
At all these stages, people need different kinds of support (they will have different kinds of questions!) and different levels of support (immediate code-related details vs broad ideas). I feel like the starter guide (in its current form) mixes some things which are not immediately required. For example, if your first PR is going to be documentation related or in Sema, you don't really immediately need to know much about LLVM except that it is a library that we are using and it provides a bunch of data structures and algorithms that are used in the compiler. That's something you can pick up as you go.
I guess, to summarize, my point of view is that while this document might potentially be useful in the immediate short-term, it has its risks in terms of information overload/analysis paralysis, and it is not sufficient for the short-term/medium-term -- we will need a lot more work (and by implication, a broader discussion amongst compiler developers before we start making large changes).
3 Likes
@typesanitizer I understand your thoughts now.
I would love if you can reach out to me when you start implementing this Contribution Starter Guide in the way you discussed above because I'd love to help in such project.
1 Like