Getting started with contributing to Processing.js or Popcorn.js
So, the first two open source projects I was involved in have a fairly similar work flow, and I decided to write down the steps to get started in these projects.
Both Processing and Popcorn have fairly good intro sites, and I would start there. Popcorn also have secondary site that is useful. Also might want to check out the original Processing. Those sites provide a general introduction on the projects, and not something I will be covering here.
Both projects have four primary things, an issue tracker, a source repository, revision control, and a developer community.
An issue tracker is where bugs and new features get tracked, assigned, and reviewed. Both projects use something called lighthouse as their issue tracker. These can be found here for popcorn and here for processing. Issues can be anything from whitespace fixes, to documentation changes to complete rewrites. The pages I liked are the recent activity pages. You may want to look under milestones to get a list of potential tickets.
A source repository is a place where the code is stored and updated. Both projects use github as their source repository. These can be found here for popcorn and here for processing. Those are our release repos, in that they only get updated once for each release. If you want the unreleased code, you have to get that from a separate repo. These can be found here for popcorn and here for processing. We call these development branches.
Both projects use git for revision control. It goes hand in hand with github, but I do feel like it is a different thing. Source repository is where the code is kept, and revision control are the tools that interact with it. This is how I like to think of it, as it helps me understand it the way I need to work with it. I might not be technically correct with the definitions, though. Kinda like how the alphabet is not actually a song, but a song helps to understand it.
Both projects use irc for their developer community. This is the place you can go to get real time help from the people that have the answers. Popcorn uses the channel #popcorn and processing #processing.js. These can be found on the server irc.mozilla.org. More information about connecting to irc can be found here or here.
Now that that is out of the way, you will want to create a github account if you don’t already have one, then fork one of the projects from their github page. You will probably want to fork one of the development repos.
From there, you will need to get that github repo onto your local machine. I used this post when I started this, and I recommend it to others.
Next step is to find a bug on one of the lighthouse pages. Maybe comment in the bug that you are interested in working on it, so others know not to work on it as well.
You will want to create a branch on your local git repo named after your bug number. So, if my bug is popcorn bug #927 I will want to create a branch called t927. We add the t because code commits can be shorthanded to numbers, and there may be collisions in branch names and commits. Always good practice to but a letter in it. You can do this by running this command:
git branch t927 develop
git checkout t927
What this does is created a branch named t927 that is based off the branch develop. Then, moves you over to that branch.
Next you can go about changing the code in your local git repo. Once done, you will want to run some git commands.
1. git status: this shows the files that have changed, that you may need to commit.
2. git add: this adds those files. If you notice running git status after a git add, things will of changed.
3. git commit: this commits those added files. Again, running git status after this, you should see even more changes. I like to run this command like this:
git commit -m “[#927] usefull message about what I did”
This will add a message to the commit, so future developers can see why certain lines were changed, and even track it back to the original lighthouse ticket.
4. git push: this pushes the changes into your forked github repo. An example of this command for when I do it is:
git push firstname.lastname@example.org:ScottDowne/popcorn-js.git t927
This command takes the ssh url of my repo, and a name to name for the branch. After doing this, I could find my branch here: https://github.com/ScottDowne/popcorn-js/tree/t927 and my changes here: https://github.com/ScottDowne/popcorn-js/commits/t927
From here you will want to take one of those two urls and drop it back intp the lighthouse ticket, as a comment, and change the status to peer-review-requested. Both projects have a two step review process. Peer-review and super-review. Once both reviews passed, the repo manager will pull your changes into develop, and then on release day, everything including your changes will be pulled into master.