From c96fc1166c47991b5b297f0768aff3ba1917b7ed Mon Sep 17 00:00:00 2001 From: Parker Moore Date: Tue, 14 Jun 2016 10:25:50 -0700 Subject: [PATCH 01/12] Spike out some internal documentation for Jekyll processes. --- docs/avoiding-burnout.md | 3 ++ docs/becoming-a-maintainer.md | 3 ++ docs/merging-a-pull-request.md | 52 ++++++++++++++++++++++++++++++++ docs/readme.md | 12 ++++++++ docs/reviewing-a-pull-request.md | 4 +++ docs/triaging-an-issue.md | 9 ++++++ 6 files changed, 83 insertions(+) create mode 100644 docs/avoiding-burnout.md create mode 100644 docs/becoming-a-maintainer.md create mode 100644 docs/merging-a-pull-request.md create mode 100644 docs/readme.md create mode 100644 docs/reviewing-a-pull-request.md create mode 100644 docs/triaging-an-issue.md diff --git a/docs/avoiding-burnout.md b/docs/avoiding-burnout.md new file mode 100644 index 00000000000..488fbb013cc --- /dev/null +++ b/docs/avoiding-burnout.md @@ -0,0 +1,3 @@ +# Maintainers: Avoiding Burnout + +**This guide is for maintainers.** These special people have **write access** to one or more of Jekyll's repositories and help merge the contributions of others. You may find what is written here interesting, but it’s definitely not for everyone. diff --git a/docs/becoming-a-maintainer.md b/docs/becoming-a-maintainer.md new file mode 100644 index 00000000000..2926344c86c --- /dev/null +++ b/docs/becoming-a-maintainer.md @@ -0,0 +1,3 @@ +# Contributors: Becoming a Maintainer + +**This guide is for contributors.** These special people have contributed to one or more of Jekyll's repositories, but do not yet have write access to any. You may find what is written here interesting, but it’s definitely not for everyone. diff --git a/docs/merging-a-pull-request.md b/docs/merging-a-pull-request.md new file mode 100644 index 00000000000..ff1f102ed98 --- /dev/null +++ b/docs/merging-a-pull-request.md @@ -0,0 +1,52 @@ +# Maintainers: Merging a Pull Request + +**This guide is for maintainers.** These special people have **write access** to one or more of Jekyll's repositories and help merge the contributions of others. You may find what is written here interesting, but it’s definitely not for everyone. + +## Code Review + +All pull requests should be subject to code review. Code review is a [foundational value](https://blog.fullstory.com/what-we-learned-from-google-code-reviews-arent-just-for-catching-bugs-b125a13aa292) of good engineering teams. Besides providing validation of correctness, it promotes a sense of community and gives other maintainers understanding of all parts of the code base. In short, code review is crucial to a healthy open source project. + +Before merging a pull request **that changes code**, ensure that code is thoroughly reviewed and has received a thorough review from at least two maintainers. + +Before merging a pull request **that changes the documentation**, ensure there aren't any errors and that at least one other maintainer has agreed on the changes. + +## Merging + +We have [a helpful little bot](https://github.com/jekyllbot) which we use to merge pull requests. We don't use the GitHub.com interface for two reasons: + +1. You can't modify anything on mobile (e.g. titles, labels) +2. Provide a consistent paper trail in the `History.markdown` file for each release + +To merge a pull request, leave a comment thanking the contributor, then add the special merge request: + +```text +Thank you very much for your contribution. Folks like you make this project and community strong. :heart: + +@jekyllbot: merge +dev +``` + +The merge request is made up of three things: + +1. `@jekyllbot:` – this is the prefix our bot looks for when processing commands +2. `merge` – the command +3. `+dev` – the category to which the changes belong + +The categories match the H3's in the history/changelog file, and they are: + +1. Major Enhancements (`+major`) – major updates or breaking changes to the code which necessitate a major version bump (v3 ~> v4) +2. Minor Enhancements (`+minor`) – minor updates (feature, enhancement) which necessitate a minor version bump (v3.1 ~> v3.2) +3. Bug Fixes (`+bug`) – corrections to code which do not change or add functionality, which necessitate a patch version bump (v3.1.0 ~> v3.1.1) +4. Site Enhancements (`+site`) – changes to the source of https://jekyllrb.com, found in `site/` +5. Development Fixes (`+dev`) – changes which do not affect user-facing functionality or documentation, such as test fixes or bumping internal dependencies + +Once @jekyllbot has merged the pull request, you should see three things: + +1. A successful merge +2. Addition of labels for the necessary category if they aren't already applied +3. A commit to the `History.markdown` file which adds a note about the change + +If you forget the category, that's just fine. You can always go back and move the line to the proper category header later. The category is always necessary for `jekyll/jekyll`, but many plugins have too few changes to necessitate changelog categories. + +## Rejoice + +You did it! Thanks for being a maintainer for one of our official Jekyll projects. Your work means the world to our thousands of users who rely on Jekyll daily. :heart: diff --git a/docs/readme.md b/docs/readme.md new file mode 100644 index 00000000000..abf4290113a --- /dev/null +++ b/docs/readme.md @@ -0,0 +1,12 @@ +# Maintaining Jekyll + +Hello! This is where we document various processes for maintaining Jekyll. Being a maintainer for any Jekyll project is a big responsibility, so we put together some helpful documentation for various tasks you might do as a maintainer. + +1. [Triaging and issue](triaging-an-issue.md) +2. [Reviewing a pull request](reviewing-a-pull-request.md) +3. [Merging a pull request](merging-a-pull-request.md) +4. [Avoiding burnout](avoiding-burnout.md) + +Interested in becoming a maintainer? Here is some documentation for **contributors**: + +1. [Becoming a maintainer](becoming-a-maintainer.md) diff --git a/docs/reviewing-a-pull-request.md b/docs/reviewing-a-pull-request.md new file mode 100644 index 00000000000..35ac769e5e4 --- /dev/null +++ b/docs/reviewing-a-pull-request.md @@ -0,0 +1,4 @@ +# Maintainers: Reviewing a Pull Request + +**This guide is for maintainers.** These special people have **write access** to one or more of Jekyll's repositories and help merge the contributions of others. You may find what is written here interesting, but it’s definitely not for everyone. + diff --git a/docs/triaging-an-issue.md b/docs/triaging-an-issue.md new file mode 100644 index 00000000000..75dbe4d13af --- /dev/null +++ b/docs/triaging-an-issue.md @@ -0,0 +1,9 @@ +# Maintainers: Triaging an Issue + +**This guide is for maintainers.** These special people have **write access** to one or more of Jekyll's repositories and help merge the contributions of others. You may find what is written here interesting, but it’s definitely not for everyone. + +Here are some key things to remember when evaluating an issue. + +## Reproducible? + +If the bug has clear reproduction steps, take a minute to try them. From 0c6162fc0a9badd4df8df9c743fca9050b124e30 Mon Sep 17 00:00:00 2001 From: Parker Moore Date: Wed, 15 Jun 2016 13:11:16 -0700 Subject: [PATCH 02/12] Borrow 97% of Homebrew's excellent 'Avoiding Burnout' document. Many, many thanks to Mike McQuaid for writing it: https://github.com/Homebrew/brew/blob/master/share/doc/homebrew/Maintainers-Avoiding-Burnout.md#3-prioritise-maintainers-over-users --- docs/avoiding-burnout.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/docs/avoiding-burnout.md b/docs/avoiding-burnout.md index 488fbb013cc..4e8b2e0b116 100644 --- a/docs/avoiding-burnout.md +++ b/docs/avoiding-burnout.md @@ -1,3 +1,27 @@ # Maintainers: Avoiding Burnout **This guide is for maintainers.** These special people have **write access** to one or more of Jekyll's repositories and help merge the contributions of others. You may find what is written here interesting, but it’s definitely not for everyone. + +# 1. Use Homebrew + +Maintainers of Homebrew should be using it regularly. This is partly because you won't be a good maintainer unless you can put yourself in the shoes of our users but also because you may decide to stop using Jekyll and at that point you should also decide not to be a maintainer and find other things to work on. + +# 2. No Guilt About Leaving + +All maintainers can stop working on Jekyll at any time without any guilt or explanation (like a job). We may still ask for your help with questions after you leave but you are under no obligation to answer them. Like a job, if you create a big mess and then leave you still have no obligations but we may think less of you (or, realistically, probably just revert the problematic work). Like a job, you should probably take a break from Jekyll at least a few times a year. + +This also means contributors should be consumers. If a maintainer finds they are not using a project in the real-world, they should reconsider their involvement with the project. + +# 3. Prioritise Maintainers Over Users + +It's important to be user-focused but ultimately, as long as you follow #1 above, Jekyll's minimum number of users will be the number of maintainers. However, if Jekyll has no maintainers it will quickly become useless to all users and the project will die. As a result, no user complaint, behaviour or need takes priority over the burnout of maintainers. If users do not like the direction of the project, the easiest way to influence it is to make significant, high-quality code contributions and become a maintainer. + +# 4. Learn To Say No + +Jekyll gets a lot of feature requests, non-reproducible bug reports, usage questions and PRs we won't accept. These should be closed out as soon as we realise that they aren't going to be resolved or merged. This is kinder than deciding this after a long period of review. Our issue tracker should reflect work to be done. + +--- + +Thanks to https://gist.github.com/ryanflorence/124070e7c4b3839d4573 which influenced this document. + +Thanks to [Homebrew's "Avoiding Burnout" document](https://github.com/Homebrew/brew/blob/master/share/doc/homebrew/Maintainers-Avoiding-Burnout.md) for providing a perfect base for this document. From a71e67720733d207b7ab6b389578a69d424d8594 Mon Sep 17 00:00:00 2001 From: Parker Moore Date: Wed, 15 Jun 2016 16:32:28 -0700 Subject: [PATCH 03/12] Add 'Reviewing a Pull Request' documentation @mikemcquaid Would love your feedback on this one. Writing from scratch here and I have the tendency to sound pretty formal. Thoughts? --- docs/reviewing-a-pull-request.md | 34 ++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/docs/reviewing-a-pull-request.md b/docs/reviewing-a-pull-request.md index 35ac769e5e4..aeea06a5a1d 100644 --- a/docs/reviewing-a-pull-request.md +++ b/docs/reviewing-a-pull-request.md @@ -2,3 +2,37 @@ **This guide is for maintainers.** These special people have **write access** to one or more of Jekyll's repositories and help merge the contributions of others. You may find what is written here interesting, but it’s definitely not for everyone. +## Respond Kindly + +Above all else, please review a pull request kindly. Our community can only be strong if we make it a welcoming and inclusive environment. To further promote this, the Jekyll community is governed by a [Code of Conduct](../CONDUCT.markdown) by which all community members must abide. + +Use emoji liberally :heart: :tada: :sparkles: :confetti_ball: and feel free to be emotive!! Contributions keep this project moving forward and we're always happy to receive them, even if the pull request isn't ultimately merged. + +Mike McQuaid's post on the GitHub blog entitled ["Kindly Closing Pull Requests"](https://github.com/blog/2124-kindly-closing-pull-requests) is a great place to start. It describes various scenarios in which it would be acceptable to close a pull request for reasons other than lack of technical integrity or accuracy. Part of being kind is responding to and resolving pull requests quickly. + +## Respond Quickly + +We should be able to review all pull requests within one week. The only time initial review should take longer is if all the maintainers mysteriously took vacation during the same week. Promptness encourages frequent, high-quality contributions from community members and other maintainers. + +If your response requires a response on the part of the author, please add the `pending-feedback` tag. @jekyllbot will automatically remove the tag once the author of the pull request responds. + +## Resolve Quickly + +Similarly, we should aim to resolve pull requests quickly. If a pull request introduces a feature which does not fit into the core purpose or goal of the project, close it prompty with a kind explanation of why it is not acceptable. + +Leave detailed comments wherever possible. Provide the contributor with context around why the change you are requesting is necessary, or why the question you are asking is important to resolve. The more context we can clearly communicate to the contributor, the better able + +You may close a pull request if more than 30 days pass without a response from the author. + +## CI Must Pass + +It is fine to ask a contributor to investigate failures on Travis and patch them up before you begin your review. It is helpful to leave a message for the contributor indicating that the tests have failed and that no review will occur before the tests pass. If they ask for help, take a look and assist if you can. + +## Rule of Two + +A pull request may be merged once two maintainers have reviewed the pull request and indicated that it is acceptable to them. There is no need to wait for a third unless one of the two reviewers wishes for another set of eyes. + +## Think Security + +We owe it to our users to ensure that using a theme from the community or building someone else's site doesn't come with built-in security vulnerabilities. Things like where files may be read from and written to are important to keep secure. Jekyll is also the basis for hosted services such as [GitHub Pages](https://pages.github.com), which cannot upgrade when security issues are introduced. + From fa6934300bf1680f5c505c48415d818ecdd818a7 Mon Sep 17 00:00:00 2001 From: Parker Moore Date: Wed, 15 Jun 2016 17:19:47 -0700 Subject: [PATCH 04/12] Add 'Becoming a Maintainer' docs. --- docs/becoming-a-maintainer.md | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/docs/becoming-a-maintainer.md b/docs/becoming-a-maintainer.md index 2926344c86c..facc9965a59 100644 --- a/docs/becoming-a-maintainer.md +++ b/docs/becoming-a-maintainer.md @@ -1,3 +1,35 @@ # Contributors: Becoming a Maintainer **This guide is for contributors.** These special people have contributed to one or more of Jekyll's repositories, but do not yet have write access to any. You may find what is written here interesting, but it’s definitely not for everyone. + +So you want to become a maintainer of a Jekyll project? We'd love to have you! Here are some things we like to see from community members before we promote them to maintainers. + +## 1. Use Jekyll + +You want to maintain Jekyll? Use it often. Do weird things with it. Do normal things with it. Does it work? Does it have any weaknesses? Is there a gap in the product that you think should be filled? + +## 1. Help Triage Issues + +Watch the repository you're interested in. Join [an Affinity Team](https://teams.jekyllrb.com) and receive mentions regarding a particular interest area of the project. When you receive a notification for an issue that has not been triaged by a maintainer, dive in. Can you reproduce the issue? Can you determine the fix? [More tips on Triaging an Issue in our maintainer guide](triaging-an-issue.md). Every maintainer loves an issue that is resolved before they get to it. :smiley: + +## 2. Write Documentation + +Good documentation means less confusion for our users and fewer issues to triage. Documentation is always in need of fixes and updates as we change the code. Read through the documentation during your normal usage of the product and submit changes as you feel they are necessary. + +## 3. Write Code + +As a maintainer, you will be reviewing pull requests which update code. You should feel comfortable with the Jekyll codebase enough to confidently review a put forward. + +## 4. Review Pull Requests + +Start by reviewing one pull request a week. Leave detailed comments and [follow our guide for reviewing pull requests](reviewing-a-pull-request.md). + +## 5. Ask! + +Open an issue describing your contributions to the project and why you wish to be a maintainer. Issues are nice because you can easily reference where you have demonstrated that you help triage issues, write code & documentation, and review pull requests. You may also email any maintainer privately if you do not feel comfortable asking in the open. + +We would love to expand the team and look forward to many more community members becoming maintainers! + +# Helping Out Elsewhere + +In addition to maintainers of our core and plugin code, the Jekyll team is comprised of moderators for our forums. These helpful community members take a look at the topics posted to https://help.jekyllrb.com and ensure they are properly categorized and are acceptable under our Code of Conduct. If you would like to be a moderator, email one of the maintainers with links to where you have answered questions and a request to be added as a moderator. More help is always welcome. From 4afb407304c1ab11da2e380543eada522f4b5503 Mon Sep 17 00:00:00 2001 From: Parker Moore Date: Thu, 16 Jun 2016 15:14:42 -0700 Subject: [PATCH 05/12] Address comments from PR review. --- docs/avoiding-burnout.md | 2 +- docs/becoming-a-maintainer.md | 12 ++++++------ docs/merging-a-pull-request.md | 4 +--- docs/reviewing-a-pull-request.md | 4 ++++ docs/triaging-an-issue.md | 2 +- 5 files changed, 13 insertions(+), 11 deletions(-) diff --git a/docs/avoiding-burnout.md b/docs/avoiding-burnout.md index 4e8b2e0b116..8ca27bfe31b 100644 --- a/docs/avoiding-burnout.md +++ b/docs/avoiding-burnout.md @@ -2,7 +2,7 @@ **This guide is for maintainers.** These special people have **write access** to one or more of Jekyll's repositories and help merge the contributions of others. You may find what is written here interesting, but it’s definitely not for everyone. -# 1. Use Homebrew +# 1. Use Jekyll Maintainers of Homebrew should be using it regularly. This is partly because you won't be a good maintainer unless you can put yourself in the shoes of our users but also because you may decide to stop using Jekyll and at that point you should also decide not to be a maintainer and find other things to work on. diff --git a/docs/becoming-a-maintainer.md b/docs/becoming-a-maintainer.md index facc9965a59..28f1f70b5f8 100644 --- a/docs/becoming-a-maintainer.md +++ b/docs/becoming-a-maintainer.md @@ -8,23 +8,23 @@ So you want to become a maintainer of a Jekyll project? We'd love to have you! H You want to maintain Jekyll? Use it often. Do weird things with it. Do normal things with it. Does it work? Does it have any weaknesses? Is there a gap in the product that you think should be filled? -## 1. Help Triage Issues +## 2. Help Triage Issues Watch the repository you're interested in. Join [an Affinity Team](https://teams.jekyllrb.com) and receive mentions regarding a particular interest area of the project. When you receive a notification for an issue that has not been triaged by a maintainer, dive in. Can you reproduce the issue? Can you determine the fix? [More tips on Triaging an Issue in our maintainer guide](triaging-an-issue.md). Every maintainer loves an issue that is resolved before they get to it. :smiley: -## 2. Write Documentation +## 3. Write Documentation Good documentation means less confusion for our users and fewer issues to triage. Documentation is always in need of fixes and updates as we change the code. Read through the documentation during your normal usage of the product and submit changes as you feel they are necessary. -## 3. Write Code +## 4. Write Code -As a maintainer, you will be reviewing pull requests which update code. You should feel comfortable with the Jekyll codebase enough to confidently review a put forward. +As a maintainer, you will be reviewing pull requests which update code. You should feel comfortable with the Jekyll codebase enough to confidently review any pull request put forward. In order to become more comfortable, write some code of your own and send a pull request. A great place to start is with any issue labeled "bug" in the issue tracker. Write a test which replicates the problem and fails, then work on fixing the code such that the test passes. -## 4. Review Pull Requests +## 5. Review Pull Requests Start by reviewing one pull request a week. Leave detailed comments and [follow our guide for reviewing pull requests](reviewing-a-pull-request.md). -## 5. Ask! +## 6. Ask! Open an issue describing your contributions to the project and why you wish to be a maintainer. Issues are nice because you can easily reference where you have demonstrated that you help triage issues, write code & documentation, and review pull requests. You may also email any maintainer privately if you do not feel comfortable asking in the open. diff --git a/docs/merging-a-pull-request.md b/docs/merging-a-pull-request.md index ff1f102ed98..3d56b09660d 100644 --- a/docs/merging-a-pull-request.md +++ b/docs/merging-a-pull-request.md @@ -6,9 +6,7 @@ All pull requests should be subject to code review. Code review is a [foundational value](https://blog.fullstory.com/what-we-learned-from-google-code-reviews-arent-just-for-catching-bugs-b125a13aa292) of good engineering teams. Besides providing validation of correctness, it promotes a sense of community and gives other maintainers understanding of all parts of the code base. In short, code review is crucial to a healthy open source project. -Before merging a pull request **that changes code**, ensure that code is thoroughly reviewed and has received a thorough review from at least two maintainers. - -Before merging a pull request **that changes the documentation**, ensure there aren't any errors and that at least one other maintainer has agreed on the changes. +**Read our guide for [Reviewing a pull request](reviewing-a-pull-request.md) before merging.** Notably, the change must have tests if for code, and at least two maintainers must give it an OK. ## Merging diff --git a/docs/reviewing-a-pull-request.md b/docs/reviewing-a-pull-request.md index aeea06a5a1d..feea47ec522 100644 --- a/docs/reviewing-a-pull-request.md +++ b/docs/reviewing-a-pull-request.md @@ -24,6 +24,10 @@ Leave detailed comments wherever possible. Provide the contributor with context You may close a pull request if more than 30 days pass without a response from the author. +## Look for Tests + +If this is a code change, are there tests for the updated or added behaviour? Shipping a version with bugs is inevitable, but ensuring changes are tested helps keep bugs and regressions to a minimum. + ## CI Must Pass It is fine to ask a contributor to investigate failures on Travis and patch them up before you begin your review. It is helpful to leave a message for the contributor indicating that the tests have failed and that no review will occur before the tests pass. If they ask for help, take a look and assist if you can. diff --git a/docs/triaging-an-issue.md b/docs/triaging-an-issue.md index 75dbe4d13af..d69b64577f5 100644 --- a/docs/triaging-an-issue.md +++ b/docs/triaging-an-issue.md @@ -6,4 +6,4 @@ Here are some key things to remember when evaluating an issue. ## Reproducible? -If the bug has clear reproduction steps, take a minute to try them. +If the bug has clear reproduction steps, take a minute to try them. If it helps, write a test in our test suite for the scenario which replicates the problem. From 0c7693f7b918c6d603119281fec9165d61177122 Mon Sep 17 00:00:00 2001 From: Parker Moore Date: Thu, 16 Jun 2016 17:07:16 -0700 Subject: [PATCH 06/12] Updates to Reviewing a Pull Request --- docs/reviewing-a-pull-request.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/reviewing-a-pull-request.md b/docs/reviewing-a-pull-request.md index feea47ec522..b2c3e0def61 100644 --- a/docs/reviewing-a-pull-request.md +++ b/docs/reviewing-a-pull-request.md @@ -18,12 +18,14 @@ If your response requires a response on the part of the author, please add the ` ## Resolve Quickly -Similarly, we should aim to resolve pull requests quickly. If a pull request introduces a feature which does not fit into the core purpose or goal of the project, close it prompty with a kind explanation of why it is not acceptable. +Similarly, we should aim to resolve pull requests quickly. If a pull request introduces a feature which does not fit into the core purpose or goal of the project, close it promptly with a kind explanation of why it is not acceptable. -Leave detailed comments wherever possible. Provide the contributor with context around why the change you are requesting is necessary, or why the question you are asking is important to resolve. The more context we can clearly communicate to the contributor, the better able +Leave detailed comments wherever possible. Provide the contributor with context around why the change you are requesting is necessary, or why the question you are asking is important to resolve. The more context we can clearly communicate to the contributor, the better able the contributor is to provide high-quality patches. You may close a pull request if more than 30 days pass without a response from the author. +In some cases, review will involve many weeks of back-and-forth. As long as communication continues, this is fine. Ideally, any PR would be capable of resolution within 30 days of it being opened. + ## Look for Tests If this is a code change, are there tests for the updated or added behaviour? Shipping a version with bugs is inevitable, but ensuring changes are tested helps keep bugs and regressions to a minimum. From d220c7a9a922eb37f9e20098538bdceed7d8c751 Mon Sep 17 00:00:00 2001 From: Parker Moore Date: Thu, 16 Jun 2016 17:12:00 -0700 Subject: [PATCH 07/12] Try fleshing out Triaging an Issue more. --- docs/triaging-an-issue.md | 33 +++++++++++++++++++++++++++++++-- 1 file changed, 31 insertions(+), 2 deletions(-) diff --git a/docs/triaging-an-issue.md b/docs/triaging-an-issue.md index d69b64577f5..436a89d0ec6 100644 --- a/docs/triaging-an-issue.md +++ b/docs/triaging-an-issue.md @@ -4,6 +4,35 @@ Here are some key things to remember when evaluating an issue. -## Reproducible? +## Feature? -If the bug has clear reproduction steps, take a minute to try them. If it helps, write a test in our test suite for the scenario which replicates the problem. +If the issue describes a feature request, ask: + +1. Is this a setting? [Settings are a crutch](http://ben.balter.com/2016/03/08/optimizing-for-power-users-and-edge-cases/#settings-are-a-crutch) for doing "the right thing". Settings usually point to a bad default or an edge case that could be solved easily with a plugin. Keep the :christmas_tree: of settings as small as possible so as not to reduce the usability of the product. We like the philosophy "decisions not options." +2. Would at least 80% of users find it useful? If even a quarter of our users won't use it, it's very likely that the request doesn't fit our product's core goal. +3. Is there another way to accomplish the end goal of the request? Most feature requests are due to bad documentation for or understanding of a pre-existing feature. See if you can clarify the end goal of the request. What is the user trying to do? Could they accomplish that goal through another feature we already support? +4. Even if 80% of our users will use it, does it fit the core goal of our project? We are writing a tool for making static websites, not a swiss army knife for publishing more generally. + +Feel free to get others' opinions and ask questions of the issue author, but depending upon the answers to the questions above, it may be out of scope for our project. + +If the request is within scope, prioritize it on the product roadmap with the other maintainers. Apply the appropriate tags and ensure the right people have weighed in to define the feature's scope and implementation. If you want to be the _best ever_, submit a PR yourself which adds the feature. + +## Bug? + +### Reproducibility + +If the bug has clear reproduction steps, take a minute to try them. If it helps, write a test in our test suite for the scenario which replicates the problem. Can you reliably replicate the issue? + +If you can't replicate the issue, post your replication steps which didn't work and ask for clarification from the issue author. + +### Supported Platform + +Is the author using a supported platform? We support the latest versions of macOS, most common distributions of Linux. If the author is using Windows, you can use the `@jekyll/windows` team to help you investigate, but ultimately it is not a supported platform. + +If the user is experiencing issues with GitHub Pages or another hosted platform that we cannot reproduce, please direct them to the platform's support channel and close the issue. + +### What they wanted vs. what they got + +An issue without a clear explanation of what the user got and what they were expecting to get is not an issue we can accurately respond to. If the user doesn't provide this information, please ask for clarification. This information helps us build test cases such that we do not break the behaviour again in the future. + +Is what they wanted to get something we want to happen? Sometimes a bug report is actually masquerading as a feature request. See the guidance above for handling feature requests. From 8a71f0f48efb4e12de86e05a65e5b14707d841eb Mon Sep 17 00:00:00 2001 From: Parker Moore Date: Tue, 21 Jun 2016 14:21:15 -0700 Subject: [PATCH 08/12] Not homebrew, jekyll. --- docs/avoiding-burnout.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/avoiding-burnout.md b/docs/avoiding-burnout.md index 8ca27bfe31b..f5625e6891e 100644 --- a/docs/avoiding-burnout.md +++ b/docs/avoiding-burnout.md @@ -4,7 +4,7 @@ # 1. Use Jekyll -Maintainers of Homebrew should be using it regularly. This is partly because you won't be a good maintainer unless you can put yourself in the shoes of our users but also because you may decide to stop using Jekyll and at that point you should also decide not to be a maintainer and find other things to work on. +Maintainers of Jekyll should be using it regularly. This is partly because you won't be a good maintainer unless you can put yourself in the shoes of our users but also because you may decide to stop using Jekyll and at that point you should also decide not to be a maintainer and find other things to work on. # 2. No Guilt About Leaving From 13d60c21e16db57fe8de5a7f6581bf1f8123cf3e Mon Sep 17 00:00:00 2001 From: Parker Moore Date: Tue, 21 Jun 2016 14:42:47 -0700 Subject: [PATCH 09/12] Specify how the pending-feedback label works and flesh out Windows & automatic closure handling. --- docs/triaging-an-issue.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/docs/triaging-an-issue.md b/docs/triaging-an-issue.md index 436a89d0ec6..e7c5aef6f81 100644 --- a/docs/triaging-an-issue.md +++ b/docs/triaging-an-issue.md @@ -27,12 +27,18 @@ If you can't replicate the issue, post your replication steps which didn't work ### Supported Platform -Is the author using a supported platform? We support the latest versions of macOS, most common distributions of Linux. If the author is using Windows, you can use the `@jekyll/windows` team to help you investigate, but ultimately it is not a supported platform. +Is the author using a supported platform? We support the latest versions of macOS, and most common distributions of Linux. + +You may close the issue immediately if the author cannot reproduce the issue on a supported platform. For Windows-related problems, leave a comment letting the user know that Windows is not officially supported, but that they may absolutely continue using the issue to communicate with folks from `@jekyll/windows` to further investigate. Additionally, you can point them to Jekyll Talk (https://talk.jekyllrb.com) as a means of getting support from the community. If the user is experiencing issues with GitHub Pages or another hosted platform that we cannot reproduce, please direct them to the platform's support channel and close the issue. ### What they wanted vs. what they got -An issue without a clear explanation of what the user got and what they were expecting to get is not an issue we can accurately respond to. If the user doesn't provide this information, please ask for clarification. This information helps us build test cases such that we do not break the behaviour again in the future. +An issue without a clear explanation of what the user got and what they were expecting to get is not an issue we can accurately respond to. If the user doesn't provide this information, please ask for clarification and apply the `pending-feedback` label. This information helps us build test cases such that we do not break the behaviour again in the future. The `pending-feedback` label will be removed automatically once the issue author posts a reply. Is what they wanted to get something we want to happen? Sometimes a bug report is actually masquerading as a feature request. See the guidance above for handling feature requests. + +### Staleness and automatic closure + +@jekyllbot will automatically mark issues as `stale` if no activity occurs for at least one month. @jekyllbot leaves a comment asking for information about reproducibility in current versions. If no one responds after another month, the issue is automatically closed. From 77751cbf156487e303855f25d0cf04d307d4cfc4 Mon Sep 17 00:00:00 2001 From: Parker Moore Date: Wed, 22 Jun 2016 10:11:59 -0700 Subject: [PATCH 10/12] Add 'special labels' to internal docs. --- docs/readme.md | 1 + docs/special-labels.md | 17 +++++++++++++++++ 2 files changed, 18 insertions(+) create mode 100644 docs/special-labels.md diff --git a/docs/readme.md b/docs/readme.md index abf4290113a..f2cb1fed2b5 100644 --- a/docs/readme.md +++ b/docs/readme.md @@ -6,6 +6,7 @@ Hello! This is where we document various processes for maintaining Jekyll. Being 2. [Reviewing a pull request](reviewing-a-pull-request.md) 3. [Merging a pull request](merging-a-pull-request.md) 4. [Avoiding burnout](avoiding-burnout.md) +5. [Special Labels](special-labels.md) Interested in becoming a maintainer? Here is some documentation for **contributors**: diff --git a/docs/special-labels.md b/docs/special-labels.md new file mode 100644 index 00000000000..8ce525977e6 --- /dev/null +++ b/docs/special-labels.md @@ -0,0 +1,17 @@ +# Maintainers: Special Labels + +**This guide is for maintainers.** These special people have **write access** to one or more of Jekyll's repositories and help merge the contributions of others. You may find what is written here interesting, but it’s definitely not for everyone. + +We use a series of "special labels" on GitHub.com to automate handling of some parts of the pull request and issue process. @jekyllbot may automatically apply or remove certain labels based on actions taken by users or maintainers. Below are the labels and how they work: + +## `pending-feedback` + +This label is used to indicate that we need more information from the issue/PR author in order to continue. It may be that you need more info before you can properly triage a bug report, or that you have some unanswered questions about a PR that need to be resolved before moving forward. You can safely ignore any issue with this label, as it is waiting for feedback. + +## `needs-work` & `pending-rebase` + +These labels are used to indicate that the Git state of a pull request must change. Both are removed once a push is registered (a "synchronize" event for the pull request) and the pull request becomes mergable. Add `needs-work` to a PR if, after your review, it requires code changes. Add `pending-rebase` to a PR if the code is fine but the branch is not automatically mergable with the target branch (e.g. `master`). + +## `stale` + +This label is automatically added and removed by @jekyllbot based on activity on an issue or pull request. The rules for this label are laid out in [Triaging an Issue: Staleness and automatic closure](triaging-an-issue.md#staleness-and-automatic-closure). From 856dbcb2de317a0c463e6ea0381403e60befaae9 Mon Sep 17 00:00:00 2001 From: Parker Moore Date: Wed, 22 Jun 2016 10:18:51 -0700 Subject: [PATCH 11/12] Add list of supported platforms 4 real. --- docs/triaging-an-issue.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/triaging-an-issue.md b/docs/triaging-an-issue.md index e7c5aef6f81..a6f24447e73 100644 --- a/docs/triaging-an-issue.md +++ b/docs/triaging-an-issue.md @@ -27,7 +27,7 @@ If you can't replicate the issue, post your replication steps which didn't work ### Supported Platform -Is the author using a supported platform? We support the latest versions of macOS, and most common distributions of Linux. +Is the author using a supported platform? We support the latest versions of macOS, Ubuntu, Debian, CentOS, Fedora, and Arch Linux. You may close the issue immediately if the author cannot reproduce the issue on a supported platform. For Windows-related problems, leave a comment letting the user know that Windows is not officially supported, but that they may absolutely continue using the issue to communicate with folks from `@jekyll/windows` to further investigate. Additionally, you can point them to Jekyll Talk (https://talk.jekyllrb.com) as a means of getting support from the community. From 75989fdb3eb86d3dd03c3bccb4a2dbef3566e3b5 Mon Sep 17 00:00:00 2001 From: Parker Moore Date: Wed, 13 Jul 2016 14:51:12 -0700 Subject: [PATCH 12/12] Add definitions for feature & bug to maintainer docs. --- docs/triaging-an-issue.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/docs/triaging-an-issue.md b/docs/triaging-an-issue.md index a6f24447e73..10da324a3f4 100644 --- a/docs/triaging-an-issue.md +++ b/docs/triaging-an-issue.md @@ -2,7 +2,14 @@ **This guide is for maintainers.** These special people have **write access** to one or more of Jekyll's repositories and help merge the contributions of others. You may find what is written here interesting, but it’s definitely not for everyone. -Here are some key things to remember when evaluating an issue. +Before evaluating an issue, it is important to identify if it is a feature +request or a bug. For the Jekyll project the following definitions are used +to identify a feature or a bug: + +**Feature** - A feature is defined as a request that adds functionality to +Jekyll outside of its current capabilities. +**Bug** - A bug is defined as an issue that identifies an error that a user +(or users) encounter when using current Jekyll functionalities. ## Feature?