hbase git commit: HBASE-12794 Guidelines for filing JIRA issues

[mi...@apache.org]

Repository: hbase
Updated Branches:
  refs/heads/master 2d781aa15 -> ed70f15b1


HBASE-12794 Guidelines for filing JIRA issues

Signed-off-by: Misty Stanley-Jones <mi...@apache.org>


Project: http://git-wip-us.apache.org/repos/asf/hbase/repo
Commit: http://git-wip-us.apache.org/repos/asf/hbase/commit/ed70f15b
Tree: http://git-wip-us.apache.org/repos/asf/hbase/tree/ed70f15b
Diff: http://git-wip-us.apache.org/repos/asf/hbase/diff/ed70f15b

Branch: refs/heads/master
Commit: ed70f15b1e869fb3f643feed04338491332058ba
Parents: 2d781aa
Author: Misty Stanley-Jones <mi...@apache.org>
Authored: Fri Jun 23 15:05:42 2017 -0700
Committer: Misty Stanley-Jones <mi...@apache.org>
Committed: Mon Jun 26 08:27:32 2017 -0700

----------------------------------------------------------------------
 src/main/asciidoc/_chapters/developer.adoc | 87 +++++++++++++++++++++++--
 1 file changed, 82 insertions(+), 5 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/hbase/blob/ed70f15b/src/main/asciidoc/_chapters/developer.adoc
----------------------------------------------------------------------
diff --git a/src/main/asciidoc/_chapters/developer.adoc b/src/main/asciidoc/_chapters/developer.adoc
index 50b9c74..46746a1 100644
--- a/src/main/asciidoc/_chapters/developer.adoc
+++ b/src/main/asciidoc/_chapters/developer.adoc
@@ -67,13 +67,90 @@ FreeNode offers a web-based client, but most people prefer a native client, and
 Check for existing issues in link:https://issues.apache.org/jira/browse/HBASE[Jira].
 If it's either a new feature request, enhancement, or a bug, file a ticket.
 
+We track multiple types of work in JIRA:
+
+- Bug: Something is broken in HBase itself.
+- Test: A test is needed, or a test is broken.
+- New feature: You have an idea for new functionality. It's often best to bring
+  these up on the mailing lists first, and then write up a design specification
+  that you add to the feature request JIRA.
+- Improvement: A feature exists, but could be tweaked or augmented. It's often
+  best to bring these up on the mailing lists first and have a discussion, then
+  summarize or link to the discussion if others seem interested in the
+  improvement.
+- Wish: This is like a new feature, but for something you may not have the
+  background to flesh out yourself.
+
+Bugs and tests have the highest priority and should be actionable.
+
+==== Guidelines for reporting effective issues
+
+- *Search for duplicates*: Your issue may have already been reported. Have a
+  look, realizing that someone else might have worded the summary differently.
++
+Also search the mailing lists, which may have information about your problem
+and how to work around it. Don't file an issue for something that has already
+been discussed and resolved on a mailing list, unless you strongly disagree
+with the resolution *and* are willing to help take the issue forward.
+
+* *Discuss in public*: Use the mailing lists to discuss what you've discovered
+  and see if there is something you've missed. Avoid using back channels, so
+  that you benefit from the experience and expertise of the project as a whole.
+
+* *Don't file on behalf of others*: You might not have all the context, and you
+  don't have as much motivation to see it through as the person who is actually
+  experiencing the bug. It's more helpful in the long term to encourage others
+  to file their own issues. Point them to this material and offer to help out
+  the first time or two.
+
+* *Write a good summary*: A good summary includes information about the problem,
+  the impact on the user or developer, and the area of the code.
+** Good: `Address new license dependencies from hadoop3-alpha4`
+** Room for improvement: `Canary is broken`
++
+If you write a bad title, someone else will rewrite it for you. This is time
+they could have spent working on the issue instead.
+
+* *Give context in the description*: It can be good to think of this in multiple
+  parts:
+** What happens or doesn't happen?
+** How does it impact you?
+** How can someone else reproduce it?
+** What would "fixed" look like?
++
+You don't need to know the answers for all of these, but give as much
+information as you can. If you can provide technical information, such as a
+Git commit SHA that you think might have caused the issue or a build failure
+on builds.apache.org where you think the issue first showed up, share that
+info.
+
+* *Fill in all relevant fields*: These fields help us filter, categorize, and
+  find things.
+
+* *One bug, one issue, one patch*: To help with back-porting, don't split issues
+  or fixes among multiple bugs.
+
+* *Add value if you can*: Filing issues is great, even if you don't know how to
+  fix them. But providing as much information as possible, being willing to
+  triage and answer questions, and being willing to test potential fixes is even
+  better! We want to fix your issue as quickly as you want it to be fixed.
+
+* *Don't be upset if we don't fix it*: Time and resources are finite. In some
+  cases, we may not be able to (or might choose not to) fix an issue, especially
+  if it is an edge case or there is a workaround. Even if it doesn't get fixed,
+  the JIRA is a public record of it, and will help others out if they run into
+  a similar issue in the future.
+
+==== Working on an issue
+
 To check for existing issues which you can tackle as a beginner, search for link:https://issues.apache.org/jira/issues/?jql=project%20%3D%20HBASE%20AND%20labels%20in%20(beginner)[issues in JIRA tagged with the label 'beginner'].
 
-* .JIRA PrioritiesBlocker: Should only be used if the issue WILL cause data loss or cluster instability reliably.
-* Critical: The issue described can cause data loss or cluster instability in some cases.
-* Major: Important but not tragic issues, like updates to the client API that will add a lot of much-needed functionality or significant bugs that need to be fixed but that don't cause data loss.
-* Minor: Useful enhancements and annoying but not damaging bugs.
-* Trivial: Useful enhancements but generally cosmetic.
+.JIRA Priorites
+* *Blocker*: Should only be used if the issue WILL cause data loss or cluster instability reliably.
+* *Critical*: The issue described can cause data loss or cluster instability in some cases.
+* *Major*: Important but not tragic issues, like updates to the client API that will add a lot of much-needed functionality or significant bugs that need to be fixed but that don't cause data loss.
+* *Minor*: Useful enhancements and annoying but not damaging bugs.
+* *Trivial*: Useful enhancements but generally cosmetic.
 
 .Code Blocks in Jira Comments
 ====