Contributing Patches

josevalim edited this page Sep 13, 2010 · 15 revisions

Home | Contributing Patches

Want to be heard?

Please check our bug tracking system and/or Remarkable Google group

Interested in contributing a patch to Remarkable or the Remarkable-tmbundle? Here’s what you need to know.

Getting started – cloning the repositories

git clone git://  
cd remarkable

Once you’ve cloned the repo, you need to install some dependencies:

sudo gem install rspec rspec-rails
sudo gem install rails -v=2.1.2 --no-ri --no-doc
sudo gem install rails -v=2.2.2 --no-ri --no-doc
sudo gem install rails -v=2.3.2 --no-ri --no-doc

Tests are crucial

Be sure to create tests for the new feature or to simulate the bug you’re fixing.

Before sending your ticket, run the following on remarkable root. It will run specs for all gems in Rails 2.1.2, 2.2.2 and 2.3.2.

rake pre_commit

You should see two tests pending in the first batch. All others tests should be successful.

Clean histories when sharing changes

Also see Topic Branches

Please keep commit histories as clean as possible. This makes it easier for us to merge your changes into the official Remarkable repo. If your commit histories contain junk, we’ll politely ask you to give us a cleaner history.

The easiest way to create a clean history is to make a new branch that tracks Remarkable’s master branch, and then cherry-pick your own commits to it. For example, say you had a commit whose sha is abc123 that you’d like to contribute to Remarkable. However you made a previous commit to your repo that would be irrelevant, but that would get pulled in when we pull from your repo.

Here’s how you would do it. This assumes that you have a remote reference named ‘remarkable’, and a publically-available repository named ’origin

git checkout -b myfix remarkable/master
git cherry-pick abc123
git push origin myfix

This creates a branch named ‘myfix’ on your public repo. Now you can tell us to pull from that branch of your repository. Then once we’ve incorporated the change you’re free to delete the branch.

You don’t need to create a different branch for each fix. This would only apply if you’ve got commits in your repo that would be irrelevant for the fix you want to share.

More steps coming soon …

Lastly, either enter a ticket or modify and existing ticket at with one of two things:

  • A link to the relevant commit(s) in your own fork of any of the remarkable repositories. These can be at github or any other public-facing git host.
  • A git-formatted patch (created using git-format-patch). This can be uploaded as an attachment, or just pasted into the ticket. See, as an example, how to create a patch for Rails.