Hackathons‎ > ‎

How To Contribute Code: a 10-Step Code Lab

Before coming to a Hackathon to write code, follow this 10-step Code Lab to set up your laptop.

It will get you going in making open-source contributions on Pencil Code from the ground up:

  1. Get an account on github, and take a look around the Pencil Code repositories.  There are two main repositories: pencilcode-site is the main code for the IDE, and jquery-turtle is the jquery plugin that provides the turtle library.  In addition, there are repositories for private forks of major open source libraries including CoffeeScript and the ACE editor.
  2. Do a code review (in github that is "reviewing a pull request") or open an issue (i.e., file a bug).  Skim through recent issues, pushes, and pull requests on https://github.com/organizations/PencilCode/. When opening a bug, be sure to include details on exactly how to reproduce the bug and what fixed behavior you would expect to see.  To review code, pick a pull request and read the diffs, make some comments, and say "looks good to me" if it looks good.
  3. Set up git on your machine.  If you are new to git, the following is the best book that I have found: http://documentup.com/skwp/git-workflows-book - don't read the whole thing yet, but skip to his .gitconfig and .bashrc suggestions, and do them first. In particular, take a minute to get the __git_ps1 trick working at your bash prompt, so you can always see which git branch you are looking at.
  4. Set up node, npm, and grunt.   The executable "node" is a language interpreter for javascript (it packages v8 with a standard library and execution environment for running javascript files as shell scripts, like perl or python).  The "npm" program is a package manager that we will use to get dependencies without checking them into the repository.  And "grunt" is a javascript-based build system (akin to make or ant).  The "prerequisites" section of this doc has a script you can cut-and-paste to install all three: https://github.com/PencilCode/pencilcode-site/blob/master/README.md
  5. Clone pencilcode-site and jquery-turtle, and get a running build for each project.  The steps are described in the README above.  You should get to the point where you can say "grunt" and all the steps of the default build and test pass.  (Once in a while, a test will fail just because it is flaky - just repeat the test.)
  6. Make a local change and see it on your local server.  In the above README, it describes how.  On pencilcode-site, run "grunt devserver"; and then browse the devserver by launching chrome with the appropriate proxy.pac command-line switch (also described in the README).  Verify that you are actually browsing your local copy by making a trivial change in the pencilcode-site/src directory (e.g., change some text) and refresh the site to see the update.
  7. Make your own fork of pencilcode-site or jquery-turtle.  Press the "Fork" button on the PencilCode repo on which you would like to test a change, and repeat step 5 to make a local clone of your own copy of the repository instead of the master copy.  For more details on what it means to fork a repro, read the github instructions here.
  8. Make and commit a change locally.  Try fixing a trivial piece of UI, or just fix the README.md.  For example, add tooltip suggestions to some buttons (as requested in https://github.com/PencilCode/jquery-turtle/issues/15 ).  Or add tips in the README.md to make it easier for the next person who is setting up a dev environoment.  Then be sure to git commit -a -m "Fixed something confusing in the readme." to create a commit in your local repository.
  9. Push your local repo to github, and create a pull request. (git push)  Anybody can now see your changes on github, at https://github.com/YourAccount/pencilcode-site.  Once it is on github, there will be a big green button to "Create a Pull Request" on your forked repository.  Making a pull request is like opening an issue: start a thread describing what's changes you made, and optionally assign it to somebody on the team to review.
  10. Now go bug somebody (David) to review your code and merge it into master.  If there are changes to make due to comments in the code review process, just keep committing and pushing improvements to your forked repo until it's ready to merge.  That's it!  If you have direct access to the PencilCode repos, you can do steps #7-#9 using branches within the main repository instead of in a forked repository - it's the same process.