[calcite] branch site updated: Site: Improve contribution guidelines for JIRA

[za...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

zabetak pushed a commit to branch site
in repository https://gitbox.apache.org/repos/asf/calcite.git


The following commit(s) were added to refs/heads/site by this push:
     new 2126ee2  Site: Improve contribution guidelines for JIRA
2126ee2 is described below

commit 2126ee2c39544af3a5ddccf87f31ba224243f1a6
Author: Stamatis Zampetakis <za...@gmail.com>
AuthorDate: Sat May 4 18:14:16 2019 +0200

    Site: Improve contribution guidelines for JIRA
    
    Summarize the respective discussion in the dev list(
    https://lists.apache.org/thread.html/59d028ec300884e432f9be1abe894d076e94b9f1ac9427cb22fa745d@%3Cdev.calcite.apache.org%3E) and include the suggestions from all participants.
---
 site/_docs/howto.md   | 34 +++++++++++++++++++++++++------
 site/develop/index.md | 56 +++++++++++++++++++++++++++++++++++++++++++--------
 2 files changed, 76 insertions(+), 14 deletions(-)

diff --git a/site/_docs/howto.md b/site/_docs/howto.md
index 408fa78..d012a23 100644
--- a/site/_docs/howto.md
+++ b/site/_docs/howto.md
@@ -457,12 +457,34 @@ particular release managers.
 
 ## Merging pull requests (for Calcite committers)
 
-Ask the contributor to squash the PR into a single commit with a message starting with [CALCITE-XXX] where XXX is the associated JIRA issue number.
-You can take this step yourself if needed.
-The contributor's name should also be added in parentheses at the end of the first line of the commit message.
-Finally, after a couple new lines make sure the message contains "Close apache/calcite#YYY" where YYY is the GitHub issue number.
-This is important as it is the only way we have to close issues on GitHub without asking the originator to do so manually.
-When the PR has been merged and pushed, be sure to mark the JIRA issue as resolved (do not use closed as that is reserved for release time).
+These are instructions for a Calcite committer who has reviewed a pull request
+from a contributor, found it satisfactory, and is about to merge it to master.
+Usually the contributor is not a committer (otherwise they would be committing
+it themselves, after you gave approval in a review).
+
+If the PR has multiple commits, squash them into a single commit. The
+commit message should follow the conventions outined in
+[contribution guidelines]({{ site.baseurl }}/develop/#contributing).
+If there are conflicts it is better to ask the contributor to take this step,
+otherwise it is preferred to do this manually since it saves time and also
+avoids unnecessary notification messages to many people on GitHub.
+
+If the contributor is not a committer, add their name in parentheses at the end
+of the first line of the commit message.
+
+If the merge is performed via command line (not through the GitHub web
+interface), make sure the message contains a line "Close apache/calcite#YYY",
+where YYY is the GitHub pull request identifier.
+
+When the PR has been merged and pushed, be sure to update the JIRA case. You
+must:
+ * resolve the issue (do not close it as this will be done by the release
+manager);
+ * select "Fixed" as resolution cause;
+ * mark the appropriate version (e.g., 1.20.0) in the "Fix version" field;
+ * add a comment (e.g., "Fixed in ...") with a hyperlink pointing to the commit
+which resolves the issue (in GitHub or GitBox), and also thank the contributor
+for their contribution.
 
 ## Set up PGP signing keys (for Calcite committers)
 
diff --git a/site/develop/index.md b/site/develop/index.md
index f754df9..de6ef62 100644
--- a/site/develop/index.md
+++ b/site/develop/index.md
@@ -68,24 +68,64 @@ helps to agree on the general approach. Log a
 proposed feature or start a discussion on the dev list.
 
 Before opening up a new JIRA case, have a look in the existing issues.
-The feature or bug that you plan to work on may already be there.  
+The feature or bug that you plan to work on may already be there.
+
+If a new issue needs to be created, it is important to provide a
+concise and meaningful summary line. It should imply what the end user
+was trying to do, in which component, and what symptoms were seen.
+If it's not clear what the desired behavior is, rephrase: e.g.,
+"Validator closes model file" to "Validator should not close model file".
+
+Contributors to the case should feel free to rephrase and clarify the
+summary line. If you remove information while clarifying, put it in
+the description of the case.
+
+Design discussions may happen in various places (email threads,
+github reviews) but the JIRA case is the canonical place for those
+discussions. Link to them or summarize them in the case.
+
+When implementing a case, especially a new feature, make sure
+the case includes a functional specification of the change. For instance,
+"Add a IF NOT EXISTS clause to the CREATE TABLE command; the command is
+a no-op if the table already exists." Update the description if
+the specification changes during design discussions or implementation.
+
+When implementing a feature or fixing a bug, endeavor to create
+the jira case before you start work on the code. This gives others
+the opportunity to shape the feature before you have gone too far down
+(what the reviewer considers to be) the wrong path.
+
+The best place to ask for feedback related to an issue is the developers list.
+Please avoid tagging specific people in the JIRA case asking for feedback.
+This discourages other contributors to participate in the discussion and
+provide valuable feedback.
+
+If there is a regression that seems to be related with a particular commit,
+feel free to tag the respective contributor(s) in the discussion.
 
 If you are going to take on the issue right away assign it to yourself.
-To assign issues to yourself you have to be registered in JIRA as a contributor. 
+To assign issues to yourself you have to be registered in JIRA as a contributor.
 In order to do that, send an email to the developers list
-and provide your JIRA username.   
+and provide your JIRA username.
 
-If you are committed to fixing the issue before the upcoming release set 
+If you are committed to fixing the issue before the upcoming release set
 the fix version accordingly (e.g., 1.20.0), otherwise leave it as blank.
 
-If you pick up an existing issue, mark it 'in progress', and when it's 
-finished flag it with 'pull-request-available'. 
+If you pick up an existing issue, mark it 'in progress', and when it's
+finished flag it with 'pull-request-available'.
 
 If for any reason you decide that an issue cannot go into the ongoing
 release, reset the fix version to blank.
 
-During a release, the release manager will update the issues that were 
-not completed for the current release to the next release
+During a release, the release manager will update the issues that were
+not completed for the current release to the next release.
+
+There are cases where the JIRA issue may be solved in the discussion
+(or some other reason) without necessitating a change. In such cases,
+the contributor(s) involved in the discussion should:
+ * resolve the issue (do not close it);
+ * select the appropriate resolution cause ("Duplicate", "Invalid", "Won't fix", etc.);
+ * add a comment with the reasoning if that's not obvious.
 
 Fork the GitHub repository, and create a branch for your feature.