From ab539622ddd737a29d038ebe926444aa4f29c248 Mon Sep 17 00:00:00 2001 From: Tom Preston-Werner Date: Thu, 17 Jan 2013 12:38:27 -0800 Subject: [PATCH] Refine CONTRIBUTE with more detail and better formatting. --- CONTRIBUTING.md | 53 ++++++++++++++++++++++++++++++++++--------------- 1 file changed, 37 insertions(+), 16 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fa6fb807..3135baf4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,20 +1,34 @@ Contribute ========== -So you've got an awesome idea to throw into Jekyll. Great! Please keep the following in mind: +So you've got an awesome idea to throw into Jekyll. Great! Please keep the +following in mind: * **Contributions will not be accepted without tests.** -* If you're creating a small fix or patch to an existing feature, just a simple test will do. Please stay in the confines of the current test suite and use [Shoulda](http://github.com/thoughtbot/shoulda/tree/master) and [RR](http://github.com/btakita/rr/tree/master). -* If it's a brand new feature, make sure to create a new [Cucumber](https://github.com/cucumber/cucumber/) feature and reuse steps where appropriate. Also, whipping up some documentation in your fork's wiki would be appreciated, and once merged it will be transferred over to the main wiki. +* If you're creating a small fix or patch to an existing feature, just a simple + test will do. Please stay in the confines of the current test suite and use + [Shoulda](http://github.com/thoughtbot/shoulda/tree/master) and + [RR](http://github.com/btakita/rr/tree/master). +* If it's a brand new feature, make sure to create a new + [Cucumber](https://github.com/cucumber/cucumber/) feature and reuse steps + where appropriate. Also, whipping up some documentation in your fork's wiki + would be appreciated, and once merged it will be transferred over to the main + wiki. +* If your contribution changes any Jekyll behavior, make sure to update the + documentation. It lives in site/_posts. If the docs are missing information, + please feel free to add it in. Great docs make a great project! Test Dependencies ----------------- -To run the test suite and build the gem you'll need to install Jekyll's dependencies. Jekyll uses Bundler, so a quick run of the bundle command and you're all set! +To run the test suite and build the gem you'll need to install Jekyll's +dependencies. Jekyll uses Bundler, so a quick run of the bundle command and +you're all set! $ bundle -Before you start, run the tests and make sure that they pass (to confirm your environment is configured properly): +Before you start, run the tests and make sure that they pass (to confirm your +environment is configured properly): $ rake test $ rake features @@ -23,23 +37,30 @@ Workflow -------- Here's the most direct way to get your work merged into the project: -* Fork the project -* Clone down your fork ( `git clone git://github.com//jekyll.git` ) -* Create a topic branch to contain your change ( `git checkout -b my_awesome_feature` ) + +* Fork the project. +* Clone down your fork ( `git clone git://github.com//jekyll.git` ). +* Create a topic branch to contain your change ( `git checkout -b my_awesome_feature` ). * Hack away, add tests. Not necessarily in that order. -* Make sure everything still passes by running `rake` -* If necessary, rebase your commits into logical chunks, without errors -* Push the branch up ( `git push origin my_awesome_feature` ) -* Create an issue with a description and link to your branch +* Make sure everything still passes by running `rake`. +* If necessary, rebase your commits into logical chunks, without errors. +* Push the branch up ( `git push origin my_awesome_feature` ). +* Create a pull request against mojombo/jekyll and describe what your change + does and the why you think it should be merged. Gotchas ------- -* If you want to bump the gem version, please put that in a separate commit. This way, the maintainers can control when the gem gets released. -* Try to keep your patch(es) based from the latest commit on mojombo/jekyll. The easier it is to apply your work, the less work the maintainers have to do, which is always a good thing. -* Please don't tag your GitHub issue with [fix], [feature], etc. The maintainers actively read the issues and will label it once they come across it. +* If you want to bump the gem version, please put that in a separate commit. + This way, the maintainers can control when the gem gets released. +* Try to keep your patch(es) based from the latest commit on mojombo/jekyll. + The easier it is to apply your work, the less work the maintainers have to do, + which is always a good thing. +* Please don't tag your GitHub issue with [fix], [feature], etc. The maintainers + actively read the issues and will label it once they come across it. Finally... ---------- -Thanks! Hacking on Jekyll should be fun, and if for some reason it's a pain to do let us know so we can fix it. +Thanks! Hacking on Jekyll should be fun. If you find any of this hard to figure +out, let us know so we can improve our process or documentation!