From a3577d953dbf2a1d8ab2c4b62d9c1527704255b9 Mon Sep 17 00:00:00 2001 From: Ben Balter Date: Fri, 26 Feb 2016 15:29:43 -0500 Subject: [PATCH] refresh contributing doc --- .github/CONTRIBUTING.markdown | 182 +++++++++++++++++--------------- History.markdown | 2 + site/_docs/contributing.md | 189 +++++++++++++++++++--------------- site/_docs/history.md | 4 +- 4 files changed, 209 insertions(+), 168 deletions(-) diff --git a/.github/CONTRIBUTING.markdown b/.github/CONTRIBUTING.markdown index c563e2d6..9ac5a8e2 100644 --- a/.github/CONTRIBUTING.markdown +++ b/.github/CONTRIBUTING.markdown @@ -1,41 +1,107 @@ -# Contributing +# Contributing to Jekyll -So you've got an awesome idea to throw into Jekyll. Great! Please keep the -following in mind: +Hi there! Interested in contributing to Jekyll? We'd love your help. Jekyll is an open source project, built one contribution at a time by users like you. -* **Use https://talk.jekyllrb.com for non-technical or indirect Jekyll questions that are not bugs.** -* **Contributions will not be accepted without tests or necessary documentation updates.** -* 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](https://github.com/thoughtbot/shoulda/tree/master) and - [RSpec-Mocks](https://github.com/rspec/rspec-mocks). -* 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 `site` - would be appreciated, and once merged it will be transferred over to the main - `site`, jekyllrb.com. -* If your contribution changes any Jekyll behavior, make sure to update the - documentation. It lives in `site/_docs`. If the docs are missing information, - please feel free to add it in. Great docs make a great project! -* Please follow the [GitHub Ruby Styleguide](https://github.com/styleguide/ruby) - when modifying Ruby code. -* Please do your best to submit **small pull requests**. The easier the proposed - change is to review, the more likely it will be merged. -* When submitting a pull request, please make judicious use of the pull request - body. A description of what changes were made, the motivations behind the - changes and [any tasks completed or left to complete](http://git.io/gfm-tasks) - will also speed up review time. +## Where to get help or report a problem -Test Dependencies ------------------ +* If you have a question about using Jekyll, start a discussion on https://talk.jekyllrb.com. +* If you think you've found a bug within a Jekyll plugin, open an issue in that plugin's repository. +* If you think you've found a bug within Jekyll itself, [open an issue](https://github.com/jekyll/jekyll/issues/new) -To run the test suite and build the gem you'll need to install Jekyll's -dependencies. Simply run this command to get all setup: +## Ways to contribute + +Whether you're a developer, a designer, or just a Jekyll devotee, there are lots of ways to contribute. Here's a few ideas: + +* [Install Jekyll on your computer](https://jekyllrb.com/docs/installation/) and kick the tires. Does it work? Does it do what you'd expect? If not, [open an issue](https://github.com/jekyll/jekyll/issues/new) and let us know. +* Comment on some of the project's [open issues](https://github.com/jekyll/jekyll/issues). Have you experienced the same problem? Know a work around? Do you have a suggestion for how the feature could be better? +* Read through [the documentation](http://jekyllrb.com/docs/home/), and click the "improve this page" button, any time you see something confusing, or have a suggestion for something that could be improved. +* Browse through [the Jekyll discussion forum](https://talk.jekyllrb.com/), and lend a hand answering questions. There's a good chance you've already experienced what another user is experiencing. +* Find [an open issue](https://github.com/jekyll/jekyll/issues) (especially [those labeled `help-wanted`](https://github.com/jekyll/jekyll/issues?q=is%3Aopen+is%3Aissue+label%3Ahelp-wanted)), and submit a proposed fix. If it's your first pull request, we promise we won't bite, and are glad to answer any questions. +* Help evaluate [open pull requests](https://github.com/jekyll/jekyll/pulls), by testing the changes locally and reviewing what's proposed. + +## Submitting a pull request + +### Pull requests generally + +* The smaller the proposed change, the better. If you'd like to propose two unrelated changes, submit two pull requests. + +* The more information, the better. Make judicious use of the pull request body. Describe what changes were made, why you made them, and what impact they will have for users. + +* Pull request are easy and fun. If this is your first pull request, it may help to [understand GitHub Flow](https://guides.github.com/introduction/flow/) + +* If you're submitting a code contribution, be sure to read the [code contributions](#code-contributions) section below. + +### Submitting a pull request via github.com + +Many small changes can be made entirely through the github.com web interface. + +1. Navigate to the file within [`jekyll/jekyll`](https://github.com/jekyll/jekyll) that you'd like to edit +2. Click the pencil icon in the top right corner to edit the file +3. Make your proposed changes +4. Click "Propose file change" +5. Click "Create pull request" +6. Add a descriptive title and detailed description for your proposed change. The more information the better. +7. Click "Create pull request" + +That's it! You'll be automatically subscribed to receive updates as others review your proposed change and provide feedback. + +### Submitting a pull request via Git command line + +1. Fork the project by clicking "Fork" in the top right corner of [`jekyll/jekyll`](https://github.com/jekyll/jekyll) +2. Clone the repository lcoally `git clone https://github.com//jekyll` +3. Create a new, descriptively named branch to contain your change ( `git checkout -b my-awesome-feature` ). +4. Hack away, add tests. Not necessarily in that order. +5. Make sure everything still passes by running `script/cibuild` (see [the tests section](#running-tests-locally) below) +6. Push the branch up ( `git push origin my-awesome-feature` ). +7. Create a pull request by visiting https://github.com//jekyll/ and following the instructions at the top of the screen. + +## Proposing updates to the documentation + +We want the Jekyll documentation to be the best it can be. We've open-sourced our docs and we welcome any pull requests if you find it lacking. + +### How to submit changes + +You can find the documentation for jekyllrb.com in the [site](https://github.com/jekyll/jekyll/tree/master/site) directory. See the section above, [submitting a pull request](#submitting-a-pull-request) for information on how to propose a change. + +One gotcha, all pull requests should be directed at the `master` branch (the default branch). + +### Adding plugins + +If you want to add your plugin to the [list of plugins](http://jekyllrb.com/docs/plugins/#available-plugins), please submit a pull request modifying the [plugins page source file](site/_docs/plugins.md) by adding a link to your plugin under the proper subheading depending upon its type. + +## Code Contributions + +Interesting in submitting a pull request? Awesome. Read on. There's a few common gotchas that we'd love to help you avoid. + +### Tests and documentation + +Any time you propose a code change, you should also include updates to the documentation and tests within the same pull request. + +#### Documentation + +If your contribution changes any Jekyll behavior, make sure to update the documentation. Documentation lives in the `site/_docs` folder (spoiler alert: it's a Jekyll site!). If the docs are missing information, please feel free to add it in. Great docs make a great project. Include changes to the documentation within your pull request, and once merged, `jekyllrb.com` will be updated. + +#### Tests + +* If you're creating a small fix or patch to an existing feature, a simple test if more than enough. You can usually copy/paste from an existing example in the `tests` folder, but if you need to can find out about our tests suites [Shoulda](https://github.com/thoughtbot/shoulda/tree/master) and [RSpec-Mocks](https://github.com/rspec/rspec-mocks). + +* If it's a brand new feature, create a new [Cucumber](https://github.com/cucumber/cucumber/) feature, reusing existing steps where appropriate. + +### Code contributions generally + +* Jekyll follows the [GitHub Ruby Styleguide](https://github.com/styleguide/ruby). + +* Don't bump the Gem version in your pull request (if you don't know what that means, you probably didn't). + +## Running tests locally + +### Test Dependencies + +To run the test suite and build the gem you'll need to install Jekyll's dependencies by running the following command: $ script/bootstrap -Before you start, run the tests and make sure that they pass (to confirm your -environment is configured properly): +Before you make any changes, run the tests and make sure that they pass (to confirm your environment is configured properly): $ script/cibuild @@ -50,56 +116,6 @@ If you are only updating a `.feature` file, you can use the command: Both `script/test` and `script/cucumber` can be run without arguments to run its entire respective suite. -Workflow --------- +## A thank you -Here's the most direct way to get your work merged into the project: - -* [Fork](https://github.com/jekyll/jekyll/fork) the project. -* Clone down your fork ( `git clone git@github.com:[username]/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 `script/cibuild`. -* 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 jekyll/jekyll and describe what your change - does and the why you think it should be merged. - -Updating Documentation ----------------------- - -We want the Jekyll documentation to be the best it can be. We've -open-sourced our docs and we welcome any pull requests if you find it -lacking. - -You can find the documentation for jekyllrb.com in the -[site](https://github.com/jekyll/jekyll/tree/master/site) directory of -Jekyll's repo on GitHub.com. - -All documentation pull requests should be directed at `master`. Pull -requests directed at another branch will not be accepted. - -The [Jekyll wiki](https://github.com/jekyll/jekyll/wiki) on GitHub -can be freely updated without a pull request as all GitHub users have access. - -If you want to add your plugin to the -[list of plugins](http://jekyllrb.com/docs/plugins/#available-plugins), -please submit a pull request modifying the -[plugins page source file](site/_docs/plugins.md) by adding a -link to your plugin under the proper subheading depending upon its type. - -Gotchas -------- - -* Please do not bump the gem version in your pull requests. -* Try to keep your patch(es) based from the latest commit on jekyll/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. If you find any of this hard to figure -out, let us know so we can improve our process or documentation! +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! diff --git a/History.markdown b/History.markdown index e00cc6fd..bbc79733 100644 --- a/History.markdown +++ b/History.markdown @@ -1,3 +1,5 @@ +# History + ## HEAD ### Minor Enhancements diff --git a/site/_docs/contributing.md b/site/_docs/contributing.md index 51942fab..9f45f6f3 100644 --- a/site/_docs/contributing.md +++ b/site/_docs/contributing.md @@ -1,46 +1,119 @@ --- -title: Contributing +title: CONTRIBUTING layout: docs permalink: "/docs/contributing/" note: This file is autogenerated. Edit /.github/CONTRIBUTING.markdown instead. --- -So you've got an awesome idea to throw into Jekyll. Great! Please keep the -following in mind: +--- +layout: docs +title: Contributing +permalink: /docs/contributing/ +--- -* **Use https://talk.jekyllrb.com for non-technical or indirect Jekyll questions that are not bugs.** -* **Contributions will not be accepted without tests or necessary documentation updates.** -* 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](https://github.com/thoughtbot/shoulda/tree/master) and - [RSpec-Mocks](https://github.com/rspec/rspec-mocks). -* 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 `site` - would be appreciated, and once merged it will be transferred over to the main - `site`, jekyllrb.com. -* If your contribution changes any Jekyll behavior, make sure to update the - documentation. It lives in `site/_docs`. If the docs are missing information, - please feel free to add it in. Great docs make a great project! -* Please follow the [GitHub Ruby Styleguide](https://github.com/styleguide/ruby) - when modifying Ruby code. -* Please do your best to submit **small pull requests**. The easier the proposed - change is to review, the more likely it will be merged. -* When submitting a pull request, please make judicious use of the pull request - body. A description of what changes were made, the motivations behind the - changes and [any tasks completed or left to complete](http://git.io/gfm-tasks) - will also speed up review time. +# Contribute to Jekyll -Test Dependencies ------------------ +Hi there! Interested in contributing to Jekyll? We'd love your help. Jekyll is an open source project, built one contribution at a time by users like you. -To run the test suite and build the gem you'll need to install Jekyll's -dependencies. Simply run this command to get all setup: +## Where to get help or report a problem + +* If you have a question about using Jekyll, start a discussion on https://talk.jekyllrb.com. +* If you think you've found a bug within Jekyll itself, [open an issue](https://github.com/jekyll/jekyll/issues/new) + +## Ways to contribute + +Whether you're a developer, a designer, or just a Jekyll devotee, there are lots of ways to contribute. Here's a few ideas: + +* [Install Jekyll on your computer](https://jekyllrb.com/docs/installation/) and kick the tires. Does it work? Does it do what you'd expect? If not, [open an issue](https://github.com/jekyll/jekyll/issues/new) and let us know. +* Comment on some of the project's [open issue](https://github.com/jekyll/jekyll/issues). Have you experienced the same problem? Know a work around? Do you have a suggestion for how the feature could be better? +* Read through [the documentation](http://jekyllrb.com/docs/home/), and click the "improve this page" button, any time you see something confusing, or have a suggestion for something that could be improved. +* Browse through [the Jekyll discussion forum](https://talk.jekyllrb.com/), and lend a hand answering questions. There's a good chance you've already experienced what another user is experiencing. +* Find [an open issue](https://github.com/jekyll/jekyll/issues) (especially [those labeled `help-wanted`](https://github.com/jekyll/jekyll/issues?q=is%3Aopen+is%3Aissue+label%3Ahelp-wanted)), and submit a proposed fix. If it's your first pull request, we promise we won't bite, and are glad to answer any questions. +* Help evaluate [open pull requests](https://github.com/jekyll/jekyll/pulls), by testing the changes locally and reviewing what's proposed. + +## Submitting a pull request + +### Pull requests generally + +* The smaller the proposed change, the better. If you'd like to propose two unrelated changes, submit two pull requests. + +* The more information, the better. Make judicious use of the pull request body. Describe what changes were made, why you made them, and what impact they will have for users. + +* Pull request are easy and fun. If this is your first pull request, it may help to [understand GitHub Flow](https://guides.github.com/introduction/flow/) + +* If you're submitting a code contribution, be sure to read the [code contributions](#code-contributions) section below. + +### Submitting a pull request via github.com + +Many small changes can be made entirely through the github.com web interface. + +1. Navigate to the file within [`jekyll/jekyll`](https://github.com/jekyll/jekyll) that you'd like to edit +2. Click the pencil icon in the top right corner to edit the file +3. Make your proposed changes +4. Click "Propose file change" +5. Click "Create pull request" +6. Add a descriptive title and detailed description for your proposed change. The more information the better. +7. Click "Create pull request" + +That's it! You'll be automatically subscribed to receive updates as others review your proposed change and provide feedback. + +### Submitting a pull request via Git command line + +1. Fork the project by clicking "Fork" in the top right corner of [`jekyll/jekyll`](https://github.com/jekyll/jekyll) +2. Clone the repository lcoally `git clone https://github.com//jekyll` +3. Create a new, descriptively named branch to contain your change ( `git checkout -b my-awesome-feature` ). +4. Hack away, add tests. Not necessarily in that order. +5. Make sure everything still passes by running `script/cibuild` (see [the tests section](#running-tests-locally) below) +6. Push the branch up ( `git push origin my-awesome-feature` ). +7. Create a pull request by visiting https://github.com//jekyll/ and following the instructions at the top of the screen. + +## Proposing updates to the documentation + +We want the Jekyll documentation to be the best it can be. We've open-sourced our docs and we welcome any pull requests if you find it lacking. + +### How to submit changes + +You can find the documentation for jekyllrb.com in the [site](https://github.com/jekyll/jekyll/tree/master/site) directory. See the section above, [submitting a pull request](#submitting-a-pull-request) for information on how to propose a change. + +One gotcha, all pull requests should be directed at the `master` branch (the default branch). + +### Adding plugins + +If you want to add your plugin to the [list of plugins](http://jekyllrb.com/docs/plugins/#available-plugins), please submit a pull request modifying the [plugins page source file](site/_docs/plugins.md) by adding a link to your plugin under the proper subheading depending upon its type. + +## Code Contributions + +Interesting in submitting a pull request? Awesome. Read on. There's a few common gotchas, we'd love to help you avoid. + +### Tests and documentation + +Any time you propose a code change, you should also include updates to the documentation and tests within the same pull request. + +#### Documentation + +If your contribution changes any Jekyll behavior, make sure to update the documentation. Documentation lives in the `site/_docs` folder (spoiler alert: it's a Jekyll site!). If the docs are missing information, please feel free to add it in. Great docs make a great project. Include changes to the documentation within your pull request, and once merged, `jekyllrb.com` will be updated. + +#### Tests + +* If you're creating a small fix or patch to an existing feature, a simple test if more than enough. You can usually copy/paste from an existing example in the `tests` folder, but if you need to can find out about our tests suites [Shoulda](https://github.com/thoughtbot/shoulda/tree/master) and [RSpec-Mocks](https://github.com/rspec/rspec-mocks). + +* If it's a brand new feature, create a new [Cucumber](https://github.com/cucumber/cucumber/) feature, reusing existing steps where appropriate. + +### Code contributions generally + +* Jekyll follows the [GitHub Ruby Styleguide](https://github.com/styleguide/ruby). + +* Don't bump the Gem version in your pull request (if you don't know what that means, you probably didn't). + +## Running tests locally + +### Test Dependencies + +To run the test suite and build the gem you'll need to install Jekyll's dependencies by running the following command: $ script/bootstrap -Before you start, run the tests and make sure that they pass (to confirm your -environment is configured properly): +Before you make any changes, run the tests and make sure that they pass (to confirm your environment is configured properly): $ script/cibuild @@ -55,56 +128,6 @@ If you are only updating a `.feature` file, you can use the command: Both `script/test` and `script/cucumber` can be run without arguments to run its entire respective suite. -Workflow --------- +## A thank you -Here's the most direct way to get your work merged into the project: - -* [Fork](https://github.com/jekyll/jekyll/fork) the project. -* Clone down your fork ( `git clone git@github.com:[username]/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 `script/cibuild`. -* 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 jekyll/jekyll and describe what your change - does and the why you think it should be merged. - -Updating Documentation ----------------------- - -We want the Jekyll documentation to be the best it can be. We've -open-sourced our docs and we welcome any pull requests if you find it -lacking. - -You can find the documentation for jekyllrb.com in the -[site](https://github.com/jekyll/jekyll/tree/master/site) directory of -Jekyll's repo on GitHub.com. - -All documentation pull requests should be directed at `master`. Pull -requests directed at another branch will not be accepted. - -The [Jekyll wiki](https://github.com/jekyll/jekyll/wiki) on GitHub -can be freely updated without a pull request as all GitHub users have access. - -If you want to add your plugin to the -[list of plugins](http://jekyllrb.com/docs/plugins/#available-plugins), -please submit a pull request modifying the -[plugins page source file](site/_docs/plugins.md) by adding a -link to your plugin under the proper subheading depending upon its type. - -Gotchas -------- - -* Please do not bump the gem version in your pull requests. -* Try to keep your patch(es) based from the latest commit on jekyll/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. If you find any of this hard to figure -out, let us know so we can improve our process or documentation! +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! diff --git a/site/_docs/history.md b/site/_docs/history.md index 12da9d24..175a3b1a 100644 --- a/site/_docs/history.md +++ b/site/_docs/history.md @@ -1063,7 +1063,7 @@ note: This file is autogenerated. Edit /History.markdown instead. - Patch a couple show-stopping security vulnerabilities ([#1946]({{ site.repository }}/issues/1946)) - Sanitize paths uniformly, in a Windows-friendly way ([#2065]({{ site.repository }}/issues/2065), [#2109]({{ site.repository }}/issues/2109)) - Update gem build steps to work correctly on Windows ([#2118]({{ site.repository }}/issues/2118)) -- Remove obsolete `normalize_options` method call from `bin/jekyll` ([#2121]({{ site.repository }}/issues/2121)). +- Remove obsolete `normalize_options` method call from `bin/jekyll` ([#2121]({{ site.repository }}/issues/2121)) - Remove `+` characters from Pygments lexer names when adding as a CSS class ([#994]({{ site.repository }}/issues/994)) - Remove some code that caused Ruby interpreter warnings ([#2178]({{ site.repository }}/issues/2178)) - Only strip the drive name if it begins the string ([#2175]({{ site.repository }}/issues/2175)) @@ -2061,7 +2061,7 @@ note: This file is autogenerated. Edit /History.markdown instead. - Bug Fixes - Fix pagination % 0 bug ([#78]({{ site.repository }}/issues/78)) -- Ensure all posts are processed first ([#71]({{ site.repository }}/issues/71)) ## NOTE +- Ensure all posts are processed first ([#71]({{ site.repository }}/issues/71)) - After this point I will no longer be giving credit in the history; that is what the commit log is for.