The problem with open-source for most people isn’t writing code, but it’s all the other things.
How shall I push my changes? How do I handle git? What should I do?
I was the same and I actually dreaded my awesome summer job, just a little bit, because now I’m supposed to contribute and preferrably a non-trivial amount. Although I’ve been programming several years, I’ve never contributed a large open-source project. Or a small one for that matter.
I assume you’re going to contribute to rust, but the essence could be generalized for other projects as well.
For making the documentation:
make docs NO_REBUILD=1
And making other things:
make -j<num-cores> NO_REBUILD=1 NO_BENCH=1 CFG_DISABLE_VALGRIND=1
The process can be very slow though, especially if you do
make clean (try not to!).
Before we start hacking it’s good to have an idea of the git workflow we’re going to use.
email@example.com:rust-lang/rust.git and push that repo into your github account. I have that as my
origin. Then create an
git remote add upstream https://github.com/rust-lang/rust
For me it looks like this:
$ g remote -v origin firstname.lastname@example.org:treeman/rust.git (fetch) origin email@example.com:treeman/rust.git (push) upstream https://github.com/rust-lang/rust (fetch) upstream https://github.com/rust-lang/rust (push)
When we want to start working on something new, always create a new branch:
$ git checkout master -b mybranch
While we’re working we need to update from
upstream, to get new changes.
$ git checkout mybranch $ git fetch upstream $ git rebase upstream/master
When done, push locally to github:
$ git push origin mybranch
To file a pull request we can use github’s interface. Just be sure to target the
master integration branch.
If we want to make some changes to our pull request, simply make the changes in
mybranch and push towards your github profile.
If you have a lot of commits in your pull request, or if they aren’t very descriptive, you may be asked to squash your commits. Sounds scary, but it’s fairly straightforward:
git logand check how many commits you have (or check via github).
git rebase -i HEAD~2will rebase the 2 latest commits.
$ git push origin mybranch -f
And that’s it! Make sure to switch branch when you’re done. I accidentally pushed another commit on top of my already reviewed, and accepted, pull request. Quite embarrassing but I’ll live =)
With that taken care of, we can finally do some work. But what to do? Here are some tips:
Document the library.
At the time of my writing, the library lacks a lot of documentation, and that’s what I’m doing. And don’t be scared, it’s not as dry as it’s sounds. My contributions are basically just adding code examples.
Write unit tests.
Proofread the tutorial.
I did this, but the tutorial is currently getting a complete rewrite, so I’m not sure how useful that was.
Find and fix some bugs.
And you can always simply start hacking on something interesting. Or find and fix a bug yourself.