2018-08-02 | 882 words | How to start contributing to Rakudo Perl 6 compiler
So, you want to contribute to an awesome open source project like the Rakudo Perl 6 compiler, but didn't know where to start? Good news! This guide is for you.
Finding What to Fix
The Issues in the repository have
labels on them. Newcomers should look for Issues labeled with
good first issue
easy to resolve Issues.
The two labels are largely synonyms, though slightly harder than trivial Issues
might be marked with
easy to resolve label only.
Once you have a few bug corpses behind you, you may wish to give
medium difficulty Issues a go.
Some of these labels are assigned based only on a guess about what the problem is, so keep in mind a labelled Issue might turn out to be harder than it first looked like.
If you found the easy Issues too hard, you may have some luck writing tests
for already-fixed bugs instead. Such Issues are marked with
testneeded labels instead
The main point of these labeled Issues isn't that any passer-by should be able to fix them, but that any passer-by can asks questions about fixing those issues and a core dev will be willing to walk you through fixing them, so that you can learn about fixing bugs in core.
So, be sure you ask questions if you're stuck with some Issue. You can ask by commenting directly on the Issue or join our dev chat room (but keep in mind that due to timezones, at times you may find no one around. Just ask your question and eventually someone will turn up and answer it).
There are many ways to set all these repos up, but I'll tell you just the one way that I use: Z-Script. It's a helper script that simplifies a lot of the building instructions to a single command. The rest of the guide will assume you're using Z-Script.
For initial setup, follow Z-Script's installation instructions. Once installed, you can run
z --help for a list
of supported commands (the list in README is outdated). It will check out
the 3 code repos inside your setup directory and the roast will be checked
You need to build different stuff, depending on what repos you modified:
- If you made changes in MoarVM, run
z mto rebuild MoarVM
- If you made changes in NQP, run
z nto rebuild NQP and Rakudo on top of it
- If you made changes in Rakudo, run
zto rebuild Rakudo
In some cases, such as when modifying
Makefile-related stuff or list of
build files, you'll need to go through the full build cycle for a particular
repo. In those cases, run
z build moar,
z build nqp,
z build rakudo
to from-scratch rebuild MoarVM, NQP, and Rakudo respectively.
Any change you wish to contribute must pass the "spectest". Simply run
z s to run the test. On a typical computer, it'll take about 5-10 minutes to
run. If you have a lot of CPU cores, you may choose to run "stresstest" instead, by running
z ss, which takes about 160 seconds on a 24-core box.
Note that a couple of test files are known to fail (to "flop") on occasion.
You can re-run a particular test file by running
z t t/spec/The/Test-file.t.
This command is also handy when you're adding new tests to roast and wish
to check they run OK.
To find a place where to put your new test, a rule of thumb is to
tree -f | grep -i ThingYou'reTesting the roast files to find any files for
the feature you're testing. If that finds nothing,
grep -FIRn ThingYou'reTesting can sometimes be helpful. If that fails too, you can either ask the core devs for a good place or just find some file.
Keep in mind, roast is the language specification that applies to all
compilers, not just Rakudo. If you have a very specific test (like text content of error messages), it may be best to place that test into Rakudo's
test suite, into
Don't over-agonize about the location of the test. The spec gets reviewed before language release, so even if you place the test into the wrong place, it'll likely be relocated later.
Simply submit your work as a Pull Request on GitHub. If you already have a commit bit to a particular repository, feel free to commit directly if you're confident in your work and it isn't something controvercial. Otherwise, still submit a Pull Request.
Tips and Stuff
Some tips for excellent bug fixing: write tests to cover the bug firsts. They should all fail and when they all pass you know you fixed the bug. And even if you fail to fix the bug, the tests can still be submitted to roast.
Think about the code you're fixing. Do similar routines have similar bug? Is the bug present with other types of input? Often what's reported in the bug report covers just a part of the problem.
And again, if you need help, just ask us.