|
| 1 | +Contribute |
| 2 | +========== |
| 3 | + |
| 4 | +So you've got an awesome idea to throw into Jekyll. Great! Please keep the |
| 5 | +following in mind: |
| 6 | + |
| 7 | +* **Contributions will not be accepted without tests or necessary documentation updates.** |
| 8 | +* If you're creating a small fix or patch to an existing feature, just a simple |
| 9 | + test will do. Please stay in the confines of the current test suite and use |
| 10 | + [Shoulda](https://github.com/thoughtbot/shoulda/tree/master) and |
| 11 | + [RR](https://github.com/rr/rr). |
| 12 | +* If it's a brand new feature, make sure to create a new |
| 13 | + [Cucumber](https://github.com/cucumber/cucumber/) feature and reuse steps |
| 14 | + where appropriate. Also, whipping up some documentation in your fork's `site` |
| 15 | + would be appreciated, and once merged it will be transferred over to the main |
| 16 | + `site`, jekyllrb.com. |
| 17 | +* If your contribution changes any Jekyll behavior, make sure to update the |
| 18 | + documentation. It lives in `site/docs`. If the docs are missing information, |
| 19 | + please feel free to add it in. Great docs make a great project! |
| 20 | +* Please follow the [GitHub Ruby Styleguide](https://github.com/styleguide/ruby) |
| 21 | + when modifying Ruby code. |
| 22 | +* Please do your best to submit **small pull requests**. The easier the proposed |
| 23 | + change is to review, the more likely it will be merged. |
| 24 | +* When submitting a pull request, please make judicious use of the pull request |
| 25 | + body. A description of what changes were made, the motivations behind the |
| 26 | + changes and [any tasks completed or left to complete](http://git.io/gfm-tasks) |
| 27 | + will also speed up review time. |
| 28 | + |
| 29 | +Test Dependencies |
| 30 | +----------------- |
| 31 | + |
| 32 | +To run the test suite and build the gem you'll need to install Jekyll's |
| 33 | +dependencies. Jekyll uses Bundler, so a quick run of the bundle command and |
| 34 | +you're all set! |
| 35 | + |
| 36 | + $ bundle |
| 37 | + |
| 38 | +Before you start, run the tests and make sure that they pass (to confirm your |
| 39 | +environment is configured properly): |
| 40 | + |
| 41 | + $ bundle exec rake test |
| 42 | + $ bundle exec rake features |
| 43 | + |
| 44 | +Workflow |
| 45 | +-------- |
| 46 | + |
| 47 | +Here's the most direct way to get your work merged into the project: |
| 48 | + |
| 49 | +* Fork the project. |
| 50 | +* Clone down your fork ( `git clone git@github.com:<username>/jekyll.git` ). |
| 51 | +* Create a topic branch to contain your change ( `git checkout -b my_awesome_feature` ). |
| 52 | +* Hack away, add tests. Not necessarily in that order. |
| 53 | +* Make sure everything still passes by running `rake`. |
| 54 | +* If necessary, rebase your commits into logical chunks, without errors. |
| 55 | +* Push the branch up ( `git push origin my_awesome_feature` ). |
| 56 | +* Create a pull request against jekyll/jekyll and describe what your change |
| 57 | + does and the why you think it should be merged. |
| 58 | + |
| 59 | +Updating Documentation |
| 60 | +---------------------- |
| 61 | + |
| 62 | +We want the Jekyll documentation to be the best it can be. We've |
| 63 | +open-sourced our docs and we welcome any pull requests if you find it |
| 64 | +lacking. |
| 65 | + |
| 66 | +You can find the documentation for jekyllrb.com in the |
| 67 | +[site](https://github.com/jekyll/jekyll/tree/master/site) directory of |
| 68 | +Jekyll's repo on GitHub.com. |
| 69 | + |
| 70 | +All documentation pull requests should be directed at `master`. Pull |
| 71 | +requests directed at another branch will not be accepted. |
| 72 | + |
| 73 | +The [Jekyll wiki](https://github.com/jekyll/jekyll/wiki) on GitHub |
| 74 | +can be freely updated without a pull request as all GitHub users have access. |
| 75 | + |
| 76 | +Gotchas |
| 77 | +------- |
| 78 | + |
| 79 | +* If you want to bump the gem version, please put that in a separate commit. |
| 80 | + This way, the maintainers can control when the gem gets released. |
| 81 | +* Try to keep your patch(es) based from the latest commit on jekyll/jekyll. |
| 82 | + The easier it is to apply your work, the less work the maintainers have to do, |
| 83 | + which is always a good thing. |
| 84 | +* Please don't tag your GitHub issue with [fix], [feature], etc. The maintainers |
| 85 | + actively read the issues and will label it once they come across it. |
| 86 | + |
| 87 | +Finally... |
| 88 | +---------- |
| 89 | + |
| 90 | +Thanks! Hacking on Jekyll should be fun. If you find any of this hard to figure |
| 91 | +out, let us know so we can improve our process or documentation! |
0 commit comments