I would like to start a discussion about getting started with the
Swift Compiler. The end goal is to see if there are ways we can help
newcomers to the compiler get started and more quickly grow into a
more effective contributor. The motivation is that I've had a
surprising amount of trouble with my starter bug. Swift is amazing and
I would love to contribute more regularly, but I also don't want to
burden the core team.
I know that documentation on a huge project like this is a
non-starter, but I wonder if we could have better information on the
contribution process, which likely wouldn't change frequently. For
example, I learned through a conference talk that Swift uses LLVM's
lit testing. I couldn't find that in any of Swift's documentation. The
docs explain how to run tests, but not how to write them. I would be
happy to help out with documentation if we can decide on changes that
would be useful.
Also, after I'm able to get my starter bug merged, I have no idea
where to go from there. I don't want to take another starter bug and
deprive someone else of the opportunity to contribute (although maybe
that's an unnecessary restriction I'm placing on myself), but I'm also
not in a place where I could take on something much larger.
The learning curve for a compiler is always going to be high, but does
anyone have ideas on how we could assist newcomers with their first
starter bug and then transitioning into something larger?
I would like to start a discussion about getting started with the
Swift Compiler. The end goal is to see if there are ways we can help
newcomers to the compiler get started and more quickly grow into a
more effective contributor. The motivation is that I've had a
surprising amount of trouble with my starter bug. Swift is amazing and
I would love to contribute more regularly, but I also don't want to
burden the core team.
I know that documentation on a huge project like this is a
non-starter, but I wonder if we could have better information on the
contribution process, which likely wouldn't change frequently. For
example, I learned through a conference talk that Swift uses LLVM's
lit testing. I couldn't find that in any of Swift's documentation. The
docs explain how to run tests, but not how to write them. I would be
happy to help out with documentation if we can decide on changes that
would be useful.
All the infrastructure documentation on llvm.org is also valid for Swift.
Also, after I'm able to get my starter bug merged, I have no idea
where to go from there. I don't want to take another starter bug and
deprive someone else of the opportunity to contribute (although maybe
that's an unnecessary restriction I'm placing on myself), but I'm also
not in a place where I could take on something much larger.
I don't think you should need to worry that any software project will ever run out of bugs :-)
But if you want to explore a particular area in more depth I would recommend searching bugs.swift.com for bug reports in the area that you are now familiar with after working through your starter bug.
-- adrian
···
On Jun 20, 2017, at 12:37 PM, Halen Wooten via swift-dev <swift-dev@swift.org> wrote:
The learning curve for a compiler is always going to be high, but does
anyone have ideas on how we could assist newcomers with their first
starter bug and then transitioning into something larger?
Of course I find the doc that mentions lit testing as soon as I send
this. The other questions (and my offer to assist with documentation)
still remain.
Halen
···
On Tue, Jun 20, 2017 at 3:37 PM, Halen Wooten <swift@hpwooten.com> wrote:
Hi,
I would like to start a discussion about getting started with the
Swift Compiler. The end goal is to see if there are ways we can help
newcomers to the compiler get started and more quickly grow into a
more effective contributor. The motivation is that I've had a
surprising amount of trouble with my starter bug. Swift is amazing and
I would love to contribute more regularly, but I also don't want to
burden the core team.
I know that documentation on a huge project like this is a
non-starter, but I wonder if we could have better information on the
contribution process, which likely wouldn't change frequently. For
example, I learned through a conference talk that Swift uses LLVM's
lit testing. I couldn't find that in any of Swift's documentation. The
docs explain how to run tests, but not how to write them. I would be
happy to help out with documentation if we can decide on changes that
would be useful.
Also, after I'm able to get my starter bug merged, I have no idea
where to go from there. I don't want to take another starter bug and
deprive someone else of the opportunity to contribute (although maybe
that's an unnecessary restriction I'm placing on myself), but I'm also
not in a place where I could take on something much larger.
The learning curve for a compiler is always going to be high, but does
anyone have ideas on how we could assist newcomers with their first
starter bug and then transitioning into something larger?
I would like to start a discussion about getting started with the
Swift Compiler. The end goal is to see if there are ways we can help
newcomers to the compiler get started and more quickly grow into a
more effective contributor. The motivation is that I've had a
surprising amount of trouble with my starter bug. Swift is amazing and
I would love to contribute more regularly, but I also don't want to
burden the core team.
I know that documentation on a huge project like this is a
non-starter, but I wonder if we could have better information on the
contribution process, which likely wouldn't change frequently. For
example, I learned through a conference talk that Swift uses LLVM's
lit testing. I couldn't find that in any of Swift's documentation. The
docs explain how to run tests, but not how to write them. I would be
happy to help out with documentation if we can decide on changes that
would be useful.
The learning curve for a compiler is always going to be high, but does
anyone have ideas on how we could assist newcomers with their first
starter bug and then transitioning into something larger?
Improving documentation for new developers is a great project. We have some information at swift.org/contributing <http://swift.org/contributing>, but it is unbalanced. (For example it has detailed specifications about the format of commit messages, but next to nothing about writing and running tests.)
You might start by writing down the various topics that you yourself wished had been gathered in one place. As a recent new contributor you will have the best insight into what is currently lacking from that perspective. For example, we do have test documentation (as you found later), but your experience shows that the documentation is not sufficiently discoverable.
Also, after I'm able to get my starter bug merged, I have no idea
where to go from there. I don't want to take another starter bug and
deprive someone else of the opportunity to contribute (although maybe
that's an unnecessary restriction I'm placing on myself), but I'm also
not in a place where I could take on something much larger.
Don't worry about that. Starter bugs are unlikely to be a scarce resource. If too many starter bugs get fixed then we will (1) celebrate, and then (2) find some more bugs that are good starter candidates.
···
On Jun 20, 2017, at 12:37 PM, Halen Wooten via swift-dev <swift-dev@swift.org> wrote:
Hi,
I’ve thought about this issue in the past too, and would be happy to help
write some content or at least proofread / contribute tidbits to a guide
for new developers.
As pointed out in this thread, a lot of Swift infrastructure and paradigms
comes from the LLVM community, but spelling that out in a “Getting Started”
guide would be nice. It’d also be worth gathering some tips & tricks for
developing & debugging issues, using Xcode or otherwise.
Would a Markdown document in the apple/swift repo be the best place for
such a thing?
···
On Tue, Jun 20, 2017 at 12:37 PM Halen Wooten via swift-dev < swift-dev@swift.org> wrote:
Hi,
I would like to start a discussion about getting started with the
Swift Compiler. The end goal is to see if there are ways we can help
newcomers to the compiler get started and more quickly grow into a
more effective contributor. The motivation is that I've had a
surprising amount of trouble with my starter bug. Swift is amazing and
I would love to contribute more regularly, but I also don't want to
burden the core team.
I know that documentation on a huge project like this is a
non-starter, but I wonder if we could have better information on the
contribution process, which likely wouldn't change frequently. For
example, I learned through a conference talk that Swift uses LLVM's
lit testing. I couldn't find that in any of Swift's documentation. The
docs explain how to run tests, but not how to write them. I would be
happy to help out with documentation if we can decide on changes that
would be useful.
Also, after I'm able to get my starter bug merged, I have no idea
where to go from there. I don't want to take another starter bug and
deprive someone else of the opportunity to contribute (although maybe
that's an unnecessary restriction I'm placing on myself), but I'm also
not in a place where I could take on something much larger.
The learning curve for a compiler is always going to be high, but does
anyone have ideas on how we could assist newcomers with their first
starter bug and then transitioning into something larger?
I would like to start a discussion about getting started with the
Swift Compiler. The end goal is to see if there are ways we can help
newcomers to the compiler get started and more quickly grow into a
more effective contributor. The motivation is that I've had a
surprising amount of trouble with my starter bug. Swift is amazing and
I would love to contribute more regularly, but I also don't want to
burden the core team.
I know that documentation on a huge project like this is a
non-starter, but I wonder if we could have better information on the
contribution process, which likely wouldn't change frequently. For
example, I learned through a conference talk that Swift uses LLVM's
lit testing. I couldn't find that in any of Swift's documentation. The
docs explain how to run tests, but not how to write them. I would be
happy to help out with documentation if we can decide on changes that
would be useful.
Also, after I'm able to get my starter bug merged, I have no idea
where to go from there. I don't want to take another starter bug and
deprive someone else of the opportunity to contribute (although maybe
that's an unnecessary restriction I'm placing on myself), but I'm also
not in a place where I could take on something much larger.
I would like to echo what Adrian/Greg have said. There is always more work to be done, so I wouldn't worry about this. But I just wanted to add, if there is an area of the compiler that interests you and there are not open starter bugs in that area, it may just be because no one has taken the time to file one. In such a case, I would just send an email to this list and ask what other things need to be fixed in this area of the compiler. We will be more than happy to guide you [that is how open source /should/ work, after all = )].
Michael
···
On Jun 20, 2017, at 12:37 PM, Halen Wooten via swift-dev <swift-dev@swift.org> wrote:
The learning curve for a compiler is always going to be high, but does
anyone have ideas on how we could assist newcomers with their first
starter bug and then transitioning into something larger?
Hi,
I’ve thought about this issue in the past too, and would be happy to help write some content or at least proofread / contribute tidbits to a guide for new developers.
As pointed out in this thread, a lot of Swift infrastructure and paradigms comes from the LLVM community, but spelling that out in a “Getting Started” guide would be nice.
Patch?
It’d also be worth gathering some tips & tricks for developing & debugging issues, using Xcode or otherwise.
There is already a file like this if you want to extend it. It is ./docs/DebuggingTheCompiler.rst.
Would a Markdown document in the apple/swift repo be the best place for such a thing?
See above ; ).
I imagine if you wanted to convert it to markdown, I don't think anyone would object. But I could be wrong.
···
On Jun 22, 2017, at 12:32 AM, Jacob Bandes-Storch via swift-dev <swift-dev@swift.org> wrote:
On Tue, Jun 20, 2017 at 12:37 PM Halen Wooten via swift-dev <swift-dev@swift.org <mailto:swift-dev@swift.org>> wrote:
Hi,
I would like to start a discussion about getting started with the
Swift Compiler. The end goal is to see if there are ways we can help
newcomers to the compiler get started and more quickly grow into a
more effective contributor. The motivation is that I've had a
surprising amount of trouble with my starter bug. Swift is amazing and
I would love to contribute more regularly, but I also don't want to
burden the core team.
I know that documentation on a huge project like this is a
non-starter, but I wonder if we could have better information on the
contribution process, which likely wouldn't change frequently. For
example, I learned through a conference talk that Swift uses LLVM's
lit testing. I couldn't find that in any of Swift's documentation. The
docs explain how to run tests, but not how to write them. I would be
happy to help out with documentation if we can decide on changes that
would be useful.
Also, after I'm able to get my starter bug merged, I have no idea
where to go from there. I don't want to take another starter bug and
deprive someone else of the opportunity to contribute (although maybe
that's an unnecessary restriction I'm placing on myself), but I'm also
not in a place where I could take on something much larger.
The learning curve for a compiler is always going to be high, but does
anyone have ideas on how we could assist newcomers with their first
starter bug and then transitioning into something larger?
This thread is a wonderful collection of information. I'm going to be
away from my computer for a few days, but I'm going to review all of
this and make a list of next action steps that we can take.
Thanks for all the insight!
···
On Thu, Jun 22, 2017 at 12:57 PM, Michael Gottesman <mgottesman@apple.com> wrote:
On Jun 20, 2017, at 12:37 PM, Halen Wooten via swift-dev <swift-dev@swift.org> wrote:
Hi,
I would like to start a discussion about getting started with the
Swift Compiler. The end goal is to see if there are ways we can help
newcomers to the compiler get started and more quickly grow into a
more effective contributor. The motivation is that I've had a
surprising amount of trouble with my starter bug. Swift is amazing and
I would love to contribute more regularly, but I also don't want to
burden the core team.
I know that documentation on a huge project like this is a
non-starter, but I wonder if we could have better information on the
contribution process, which likely wouldn't change frequently. For
example, I learned through a conference talk that Swift uses LLVM's
lit testing. I couldn't find that in any of Swift's documentation. The
docs explain how to run tests, but not how to write them. I would be
happy to help out with documentation if we can decide on changes that
would be useful.
Also, after I'm able to get my starter bug merged, I have no idea
where to go from there. I don't want to take another starter bug and
deprive someone else of the opportunity to contribute (although maybe
that's an unnecessary restriction I'm placing on myself), but I'm also
not in a place where I could take on something much larger.
I would like to echo what Adrian/Greg have said. There is always more work to be done, so I wouldn't worry about this. But I just wanted to add, if there is an area of the compiler that interests you and there are not open starter bugs in that area, it may just be because no one has taken the time to file one. In such a case, I would just send an email to this list and ask what other things need to be fixed in this area of the compiler. We will be more than happy to guide you [that is how open source /should/ work, after all = )].
Michael
The learning curve for a compiler is always going to be high, but does
anyone have ideas on how we could assist newcomers with their first
starter bug and then transitioning into something larger?
Here are a summary of what we've discussed and my proposal for a next step:
## Compiler tips
- The LLVM infrastructure docs are valid for Swift as well, and this
includes LIT testing. Reading over those will help with understanding
the Swift codebase.
- You can invoke lit directly for rapid testing during development.
- If you don't see a starter bug in an area of the compiler that
interests you, email this mailing list to ask if there are any unfiled
bugs available.
- ./docs/DebuggingTheCompiler.rst contains debugging information
- Release builds of the compiler will build the standard library more
quickly, which can help reduce development time.
## Proposal
### Motivation
Right now, there are at least three places that have information about
contributing to Swift. The largest of these is Swift.org - Contributing , which discusses contributions to the
project overall, and not compiler specifics (which is probably the
right call). We also have the near-empty CONTRIBUTING.md and a small
section at the end of the readme.
### Action Item
I propose that we consolidate the above tips and links for swift
compiler resources (like the previously mentioned testing guide) into
CONTRIBUTING.md and link to that from the README. This will serve as
the definitive guide for new contributors to get up to speed. Does
that sound reasonable? (And if so, should this be a jira ticket?)
Thanks,
Halen
···
On Thu, Jun 22, 2017 at 8:45 PM, Halen Wooten <swift@hpwooten.com> wrote:
This thread is a wonderful collection of information. I'm going to be
away from my computer for a few days, but I'm going to review all of
this and make a list of next action steps that we can take.
Thanks for all the insight!
On Thu, Jun 22, 2017 at 12:57 PM, Michael Gottesman > <mgottesman@apple.com> wrote:
On Jun 20, 2017, at 12:37 PM, Halen Wooten via swift-dev <swift-dev@swift.org> wrote:
Hi,
I would like to start a discussion about getting started with the
Swift Compiler. The end goal is to see if there are ways we can help
newcomers to the compiler get started and more quickly grow into a
more effective contributor. The motivation is that I've had a
surprising amount of trouble with my starter bug. Swift is amazing and
I would love to contribute more regularly, but I also don't want to
burden the core team.
I know that documentation on a huge project like this is a
non-starter, but I wonder if we could have better information on the
contribution process, which likely wouldn't change frequently. For
example, I learned through a conference talk that Swift uses LLVM's
lit testing. I couldn't find that in any of Swift's documentation. The
docs explain how to run tests, but not how to write them. I would be
happy to help out with documentation if we can decide on changes that
would be useful.
Also, after I'm able to get my starter bug merged, I have no idea
where to go from there. I don't want to take another starter bug and
deprive someone else of the opportunity to contribute (although maybe
that's an unnecessary restriction I'm placing on myself), but I'm also
not in a place where I could take on something much larger.
I would like to echo what Adrian/Greg have said. There is always more work to be done, so I wouldn't worry about this. But I just wanted to add, if there is an area of the compiler that interests you and there are not open starter bugs in that area, it may just be because no one has taken the time to file one. In such a case, I would just send an email to this list and ask what other things need to be fixed in this area of the compiler. We will be more than happy to guide you [that is how open source /should/ work, after all = )].
Michael
The learning curve for a compiler is always going to be high, but does
anyone have ideas on how we could assist newcomers with their first
starter bug and then transitioning into something larger?