Getting started with a project
Getting set up
The primary way in which we collaborate on coding projects is via git and GitLab. If you haven’t done so already, create an account on our GitLab server.
You should also set up git on your machine; you don’t need to know all the ins and outs (but feel free to if you want to)! I’d recommend checking out our getting started with git guide. Once you’ve done this, you should be able to check out and working on your code.
Common Tools
There are some reasonably common build systems that our projects use:
- Mason + Ninja (C and C++)
- Maven (Java)
- pip + setup.py (Python)
Getting the project working
Have a look at the project’s readme on GitLab. This should tell you how to get the project running on your machine. If it doesn’t or the instructions don’t work you’ve found a bug! Report it so that the maintainers can fix it.
Finding something to work on
Now you’ve got the project setup, let’s find something to work on. There are a couple of ways to go about this, but it’s best to start on something small and then work up to bigger tasks. An excellent first step is to have a go at fixing some of the ‘low hanging fruit’ bug reports. These are reports that should be relatively easy to fix.
Working on bugs is a good way to get familiar with a project, as you’ll end up looking at lots of different areas of the code. It’s also handy for both the maintainers and the end-users of the software.
Bug Hunting
Lots of the projects should have a “good first issue” tag. This lets you find problems that are well suited to new contributors. Look on the GitLab issues page and filter by issues that are tagged as good first issues. Once you’ve found an issue that you’d like to work on, comment on the issue and assign it to yourself. This prevents duplication of effort so that two people don’t end up working on the same problem.
Fixing the bug
The first step in fixing the bug should be to create a new branch. This keeps your code off the main branch until it’s ready. If you’re not sure how to create a branch, check out our ‘git branching guide’.
Finding it
The next step is to see if you can reproduce the bug. The issue should detail what went wrong. This is one of the reasons writing useful bug reports is so important. If you can’t see the problem happen, how will you know if you’ve fixed it? Depending on the project, a unit test showing the bug might be a good addition as well (so people know if it comes back in the future), although most of the time this is a ‘nice to have’ rather than a requirement.
Fixing it
Now we know what the bug is, let’s have a go at fixing it. Write code that fixes the bug; the issue might have some pointers on the steps required to do this. If you need help, you can contact someone involved in the project or write a comment in the bug report. Asking questions via the issue system has the advantage that other people might be able to find the answer in the future if they have the same problem.
Once you’ve fixed the problem, re-test it using the steps you performed before if the problem is gone, great! Time to move on to the next step! If not, it’s back to the bug hunting. This find-fix-test-repeat approach is relatively common in software development.
Getting your work merged
Now you’ve fixed the bug; it’s time to get it added in to the project’s main copy. The way you do this is via a ‘pull request’. This lets the maintainer know that you’re ready to have someone check the code. Depending on your level of access, you might be able to push directly to the main repository, or you might need to clone it.
Once you’ve written your merge request, one of the maintainers should perform a code review. This is to help spot any potential problems with your submitted code. It’s usual for a pull request to go back and forth between the developer and the maintainer a few times before it’s accepted. Most of our projects also have a helpful automated process that will perform checks as well.
Once your changes have been approved, they will be merged, and the pull request will be closed. Well done, you’ve fixed an issue a user was having making their day a little brighter and making the project better in the process.
Finding bigger fish
Congratulations, you’ve gotten your first pull request accepted. Why not have a look at some of the other issues in the project? Maybe choose something a little bigger, or choose a new ‘good first issue’.
about 900 Words.