Contributing Code

At Cappuccino we use github’s pull requests to integrate code from outside parties, so contributing code is fairly simple.

Create your own fork of the repository

1. You'll want to start by forking the main Cappuccino branch and creating your own copy. To do this, just click the "fork" button at our main page. You only need to do this once, and you can clone your forked repository to your local machine by doing the following:

   $ git clone git@github.com:yourusername/cappuccino.git

   Note that this URL is what is listed as "Your Clone URL" and not "Public Clone URL".

2. This will clone your fork to your local machine, not the Cappuccino master. To create a link to the Cappuccino master in your local repository, do the following:

   $ cd cappuccino
   $ git remote add upstream git://github.com/cappuccino/cappuccino.git
   $ git fetch upstream

Making changes

1. When making changes, you always want to base your changes on the latest Cappuccino master, to reduce the changes to a minimum. This is accomplished by making a "topic" branch from upstream/master:

   $ git fetch upstream
   $ git branch --track <topic> upstream/master
   $ git checkout <topic>

   <topic> is the name of the topic branch, and usually is named to reflect the change being made. For example, if you are fixing CPColor -colorWithHexString, you might name the branch "colorWithHexString-fix":

   $ git branch --track colorWithHexString-fix upstream/master
   $ git checkout colorWithHexString-fix

2. You can now proceed to make all the appropriate changes on your own git repository.

   IMPORTANT: You must follow the Cappuccino Coding Style Guidelines when submitting code for inclusion in Cappuccino. Please use the capp_lint tool (in cappuccino/Tools/capp_lint) to check your code, or if you are using Sublime Text 2 as your editor, you can use the SublimeLinter plugin, which has capp_lint built in. We're sorry, but we cannot accept code that does not conform to our coding guidelines.

3. If your code makes any functional changes to a Foundation class, please add a suitable test in cappuccino/Tests/Foundation. If your code makes any functional changes to an AppKit class, modify or add a suitable test in cappuccino/Tests/AppKit. If your change does not unit test well you can modify one of the manual tests in cappuccino/Tests/Manual or add a new test app if necessary.

4. After you have written and tested your code, commit your changes.

   IMPORTANT: You must follow the commit message guidelines when writing commit messages for inclusion in the Cappuccino repository. This is critical, it helps us enormously.

Creating a pull request

1. Before pushing your topic branch to your github fork, first you have to make sure you won’t conflict with the latest Cappuccino master:

   $ git pull

   If you get merge conflicts when pulling, you will have to resolve them manually and then commit your changes.

2. Now you can push your topic branch to your github fork:

   $ git push origin <topic>

3. Finally, you need to turn your topic branch into a pull request. Open your browser and go to https://github.com/<username>/cappuccino/pull/new/<topic>, where <username> is your github username and <topic> is the name of the topic branch you just pushed.

4. If necessary, modify the pull request title and comments to be as descriptive as possible.

5. Click on the "Files Changed" tab and review the changes to make sure only the changes you intended to part of the pull request are included.

6. When you are sure everything looks good, click "Send pull request". We will review it as soon as we have time and make comments or ask questions via the pull request’s page on github.