This is an automated email from the ASF dual-hosted git repository. zabetak pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/calcite.git
The following commit(s) were added to refs/heads/master by this push: new 6afa38b Site: Improve contribution guidelines for JIRA 6afa38b is described below commit 6afa38bae794462e6e250237a1b60cc4220b2885 Author: Stamatis Zampetakis <zabe...@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 | 42 +++++++++++++++++++++++++++++++++++++++++- 2 files changed, 69 insertions(+), 7 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 836c04b..de6ef62 100644 --- a/site/develop/index.md +++ b/site/develop/index.md @@ -70,6 +70,39 @@ 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. +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. In order to do that, send an email to the developers list @@ -85,7 +118,14 @@ 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 +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.