You are viewing a plain text version of this content. The canonical link for it is here.

Posted to github@arrow.apache.org by GitBox <gi...@apache.org> on 2020/06/22 22:13:29 UTC

[GitHub] [arrow] nealrichardson opened a new pull request #7520: ARROW-9189: [Website] Improve contributor guide

nealrichardson opened a new pull request #7520:
URL: https://github.com/apache/arrow/pull/7520


   


----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [arrow] nealrichardson commented on a change in pull request #7520: ARROW-9189: [Website] Improve contributor guide

Posted by GitBox <gi...@apache.org>.

nealrichardson commented on a change in pull request #7520:
URL: https://github.com/apache/arrow/pull/7520#discussion_r444320449



##########
File path: docs/source/developers/contributing.rst
##########
@@ -168,11 +274,15 @@ remote repo still holds the old history, you would need to do a force push. ::
 look at your updates, please ensure you comment on the PR on GitHub as simply force
 pushing does not trigger a notification in the GitHub user interface.
 
-Simplifying ``rebase``
-++++++++++++++++++++++
+Also, once you have a pull request up, be sure you pull from ``origin``
+before rebasing and force-pushing. Arrow maintainers can push commits directly
+to your branch, which they sometimes do to help move a pull request along.
+In addition, the GitHub PR "suggestion" feature can also add commits to
+your branch, so it is possible that your local copy of your branch is missing
+some additions.

Review comment:
       FWIW I too like the suggestion feature: I find it makes for a better being-reviewed experience because trivial or pedantic suggestions can just be accepted. In any case, I agree with Joris that I don't read this paragraph as an endorsement, just an acknowledgement of a way that `origin` may have commits that you don't have locally, even though it is "your" branch.




----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [arrow] jorisvandenbossche commented on a change in pull request #7520: ARROW-9189: [Website] Improve contributor guide

Posted by GitBox <gi...@apache.org>.

jorisvandenbossche commented on a change in pull request #7520:
URL: https://github.com/apache/arrow/pull/7520#discussion_r444293158



##########
File path: docs/source/developers/contributing.rst
##########
@@ -124,29 +181,72 @@ To contribute a patch:
   `ARROW-767: [C++] Filesystem abstraction <https://github.com/apache/arrow/pull/4225>`_).
 * Make sure that your code passes the unit tests. You can find instructions how
   to run the unit tests for each Arrow component in its respective README file.
+
+Core developers and others with a stake in the part of the project your change
+affects will review, request changes, and hopefully indicate their approval
+in the end. To make the review process smooth for everyone, try to
+
+* Break your work into small, single-purpose patches if possible. It’s much
+  harder to merge in a large change with a lot of disjoint features, and
+  particularly if you're new to the project, smaller changes are much easier
+  for maintainers to accept.
 * Add new unit tests for your code.
+* Follow the style guides for the part(s) of the project you're modifying.
+  Some languages (C++, Python, and Rust, for example) run a lint check in
+  continuous integration. For all languages, see their respective developer
+  documentation and READMEs for style guidance. In general, try to make it look
+  as if the codebase has a single author, and emulate any conventions you see,
+  whether or not they are officially documented or checked.
+
+When tests are passing and the pull request has been approved by the interested
+parties, a committer will merge the pull request. This is done with a
+command-line utility that does a squash merge, so all of your commits will be
+registered as a single commit to the master branch; this simplifies the
+connection between JIRA issues and commits, and it makes it easier to bisect
+history to identify where changes were introduced. A side effect of this way of
+merging is that your pull request will appear in the GitHub interface to have
+been "closed without merge". Do not be alarmed: if you look at the bottom, you
+will see a message that says "@user closed this in $COMMIT".
+
+Local git conventions
++++++++++++++++++++++
+
+If you are tracking the Arrow source repository locally, here are some tips
+for using ``git``.
+
+All Arrow contributors work off of their personal fork of ``apache/arrow``
+and submit pull requests "upstream". Once you've cloned your fork of Arrow,
+be sure to::
+
+    $ git remote add upstream https://github.com/apache/arrow
+
+to set the "upstream" repository.
+
+You are encouraged to develop on branches, rather than your own "master" branch,
+and it helps to keep your fork's master branch synced with ``upstream/master``.
 
-Thank you in advance for your contributions!
+To start a new branch, pull the latest from upstream first::
 
-Common Git conventions followed within the project
---------------------------------------------------
+   $ git fetch upstream
+   $ git checkout master
+   $ git reset --hard upstream/master
+   $ git checkout -b $NEW_BRANCH_NAME
 
-If you are tracking the Arrow source repository locally, following some common Git
-conventions would make everyone's workflow compatible.  These recommendations along with
-their rationale are outlined below.
+It does not matter what you call your branch. Some people like to use the JIRA
+number as branch name, others use descriptive names.
 
-It is strongly discouraged to use a regular ``git merge``, as a linear commit history is
-prefered by the project.  It is much easier to maintain, and makes for easier
-``cherry-picking`` of features; useful for backporting fixes to maintenance releases.
+Once you have a branch going, you should sync with ``upstream/master``
+regularly, as many commits merge to master every day.
+It is recommended to use ``git rebase`` rather than ``git merge``.

Review comment:
       > Resolving conflicts in a PR with merge commits can be a nightmare
   
   If you only `merge upstream/master`, then that is in my experience never a nightmare (you should of course never mix rebasing and merging, as that indeed will give nightmares). 
   
   Also, when merging master instead of rebasing, you only need to fix merge conflicts once. While now we have here a complicated section about how to simplify the conflict resolution by squashing your commits while rebasing. This is never needed in a merging workflow (which IMO is also nicer because it preserves that you can see what has been changed since a last review on github).
   
   Anyway, we are not going to resolve that discussion here ;) (and both workflows have its pros/cons). I was mainly wondering to what extent we want to push contributors to a chosen workflow.




----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [arrow] nealrichardson commented on a change in pull request #7520: ARROW-9189: [Website] Improve contributor guide

Posted by GitBox <gi...@apache.org>.

nealrichardson commented on a change in pull request #7520:
URL: https://github.com/apache/arrow/pull/7520#discussion_r444322251



##########
File path: docs/source/developers/contributing.rst
##########
@@ -76,46 +96,83 @@ visibility. They may add a "Fix version" to indicate that they're considering
 it for inclusion in the next release, though adding that tag is not a
 commitment that it will be done in the next release.
 
-Advanced use
-------------
-
-Once you are involved in the project and want to do more on JIRA, such as
-assign yourself an issue, you will need "Contributor" permissions on the
-Apache Arrow JIRA. To get this role, ask on the mailing list for a project
-maintainer's help.
-
-GitHub issues
--------------
-
-We support `GitHub issues <https://github.com/apache/arrow/issues>`_ as a
-lightweight way to ask questions and engage with
-the Arrow developer community. We use JIRA for maintaining a queue of
-development work and as the public record for work on the project. So, feel
-free to open GitHub issues, but bugs and feature requests will eventually need
-to end up in JIRA, either before or after completing a pull request. Don't be
-surprised if you are immediately asked by a project maintainer to open a JIRA
-issue.
-
-How to contribute patches
-=========================
-
-We prefer to receive contributions in the form of GitHub pull requests. Please
-send pull requests against the `github.com/apache/arrow
-<https://github.com/apache/arrow>`_ repository following the procedure below.
-
-If you are looking for some ideas on what to contribute, check out the JIRA
-issues for the Apache Arrow project. Comment on the issue and/or contact
-dev@arrow.apache.org with your questions and ideas.
-
-If you’d like to report a bug but don’t have time to fix it, you can still post
-it on JIRA, or email the mailing list dev@arrow.apache.org.
+Tips for successful bug reports
++++++++++++++++++++++++++++++++
+
+No one likes having bugs in their software, and in an ideal world, all bugs
+would get fixed as soon as they were reported. However, time and attention are
+finite, especially in an open-source project where most contributors are
+participating in their spare time. In order for your bug to get prompt
+attention, there are things you can do to make it easier for contributors to
+reproduce and fix it.
+
+When you're reporting a bug, please help us understand the issue by providing,
+to the best of your ability,
+
+* Clear, minimal steps to reproduce the issue, with as few non-Arrow
+  dependencies as possible. If there's a problem on reading a file, try to
+  provide as small of an example file as possible, or code to create one.
+  If your bug report says "it crashes trying to read my file, but I can't
+  share it with you," it's really hard for us to debug.
+* Any relevant operating system, language, and library version information
+* If it isn't obvious, clearly state the expected behavior and what actually
+  happened.
+
+If a developer can't get a failing unit test, they won't be able to know that
+the issue has been identified, and they won't know when it has been fixed.
+Try to anticipate the questions you might be asked by someone working to
+understand the issue and provide those supporting details up front.
+

Review comment:
       Clearly there is lots of prior art out there on how to write a good bug report. I hesitated to add links for the reason you mentioned, but I'll see if I can collect a few links that say the same things but in different (programming) languages.




----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [arrow] jorisvandenbossche commented on a change in pull request #7520: ARROW-9189: [Website] Improve contributor guide

Posted by GitBox <gi...@apache.org>.

jorisvandenbossche commented on a change in pull request #7520:
URL: https://github.com/apache/arrow/pull/7520#discussion_r444295036



##########
File path: docs/source/developers/contributing.rst
##########
@@ -124,29 +181,72 @@ To contribute a patch:
   `ARROW-767: [C++] Filesystem abstraction <https://github.com/apache/arrow/pull/4225>`_).
 * Make sure that your code passes the unit tests. You can find instructions how
   to run the unit tests for each Arrow component in its respective README file.
+
+Core developers and others with a stake in the part of the project your change
+affects will review, request changes, and hopefully indicate their approval
+in the end. To make the review process smooth for everyone, try to
+
+* Break your work into small, single-purpose patches if possible. It’s much
+  harder to merge in a large change with a lot of disjoint features, and
+  particularly if you're new to the project, smaller changes are much easier
+  for maintainers to accept.
 * Add new unit tests for your code.
+* Follow the style guides for the part(s) of the project you're modifying.
+  Some languages (C++, Python, and Rust, for example) run a lint check in
+  continuous integration. For all languages, see their respective developer
+  documentation and READMEs for style guidance. In general, try to make it look
+  as if the codebase has a single author, and emulate any conventions you see,
+  whether or not they are officially documented or checked.
+
+When tests are passing and the pull request has been approved by the interested
+parties, a committer will merge the pull request. This is done with a
+command-line utility that does a squash merge, so all of your commits will be
+registered as a single commit to the master branch; this simplifies the
+connection between JIRA issues and commits, and it makes it easier to bisect
+history to identify where changes were introduced. A side effect of this way of
+merging is that your pull request will appear in the GitHub interface to have
+been "closed without merge". Do not be alarmed: if you look at the bottom, you
+will see a message that says "@user closed this in $COMMIT".
+
+Local git conventions
++++++++++++++++++++++
+
+If you are tracking the Arrow source repository locally, here are some tips
+for using ``git``.
+
+All Arrow contributors work off of their personal fork of ``apache/arrow``
+and submit pull requests "upstream". Once you've cloned your fork of Arrow,
+be sure to::
+
+    $ git remote add upstream https://github.com/apache/arrow
+
+to set the "upstream" repository.
+
+You are encouraged to develop on branches, rather than your own "master" branch,
+and it helps to keep your fork's master branch synced with ``upstream/master``.
 
-Thank you in advance for your contributions!
+To start a new branch, pull the latest from upstream first::
 
-Common Git conventions followed within the project
---------------------------------------------------
+   $ git fetch upstream
+   $ git checkout master
+   $ git reset --hard upstream/master
+   $ git checkout -b $NEW_BRANCH_NAME
 
-If you are tracking the Arrow source repository locally, following some common Git
-conventions would make everyone's workflow compatible.  These recommendations along with
-their rationale are outlined below.
+It does not matter what you call your branch. Some people like to use the JIRA
+number as branch name, others use descriptive names.
 
-It is strongly discouraged to use a regular ``git merge``, as a linear commit history is
-prefered by the project.  It is much easier to maintain, and makes for easier
-``cherry-picking`` of features; useful for backporting fixes to maintenance releases.
+Once you have a branch going, you should sync with ``upstream/master``
+regularly, as many commits merge to master every day.
+It is recommended to use ``git rebase`` rather than ``git merge``.

Review comment:
       Yes, it's partly a lack of GitHub's reviewing functionalities, but *when* using GitHub (which is the case right now), my feeling is that a merging workflow works better with it.




----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [arrow] wesm closed pull request #7520: ARROW-9189: [Website] Improve contributor guide

Posted by GitBox <gi...@apache.org>.

wesm closed pull request #7520:
URL: https://github.com/apache/arrow/pull/7520


   


----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [arrow] nealrichardson commented on a change in pull request #7520: ARROW-9189: [Website] Improve contributor guide

Posted by GitBox <gi...@apache.org>.

nealrichardson commented on a change in pull request #7520:
URL: https://github.com/apache/arrow/pull/7520#discussion_r444330998



##########
File path: docs/source/developers/contributing.rst
##########
@@ -124,29 +181,72 @@ To contribute a patch:
   `ARROW-767: [C++] Filesystem abstraction <https://github.com/apache/arrow/pull/4225>`_).
 * Make sure that your code passes the unit tests. You can find instructions how
   to run the unit tests for each Arrow component in its respective README file.
+
+Core developers and others with a stake in the part of the project your change
+affects will review, request changes, and hopefully indicate their approval
+in the end. To make the review process smooth for everyone, try to
+
+* Break your work into small, single-purpose patches if possible. It’s much
+  harder to merge in a large change with a lot of disjoint features, and
+  particularly if you're new to the project, smaller changes are much easier
+  for maintainers to accept.
 * Add new unit tests for your code.
+* Follow the style guides for the part(s) of the project you're modifying.
+  Some languages (C++, Python, and Rust, for example) run a lint check in
+  continuous integration. For all languages, see their respective developer
+  documentation and READMEs for style guidance. In general, try to make it look
+  as if the codebase has a single author, and emulate any conventions you see,
+  whether or not they are officially documented or checked.
+
+When tests are passing and the pull request has been approved by the interested
+parties, a committer will merge the pull request. This is done with a
+command-line utility that does a squash merge, so all of your commits will be
+registered as a single commit to the master branch; this simplifies the
+connection between JIRA issues and commits, and it makes it easier to bisect
+history to identify where changes were introduced. A side effect of this way of
+merging is that your pull request will appear in the GitHub interface to have
+been "closed without merge". Do not be alarmed: if you look at the bottom, you
+will see a message that says "@user closed this in $COMMIT".
+
+Local git conventions
++++++++++++++++++++++
+
+If you are tracking the Arrow source repository locally, here are some tips
+for using ``git``.
+
+All Arrow contributors work off of their personal fork of ``apache/arrow``
+and submit pull requests "upstream". Once you've cloned your fork of Arrow,
+be sure to::
+
+    $ git remote add upstream https://github.com/apache/arrow
+
+to set the "upstream" repository.
+
+You are encouraged to develop on branches, rather than your own "master" branch,
+and it helps to keep your fork's master branch synced with ``upstream/master``.
 
-Thank you in advance for your contributions!
+To start a new branch, pull the latest from upstream first::
 
-Common Git conventions followed within the project
---------------------------------------------------
+   $ git fetch upstream
+   $ git checkout master
+   $ git reset --hard upstream/master

Review comment:
       Learn something new every day. 
   
   I generally treat `origin/master` as disposable and wish GitHub had a way to keep it automatically in sync with `upstream/master`, but that's neither here nor there.




----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [arrow] github-actions[bot] commented on pull request #7520: ARROW-9189: [Website] Improve contributor guide

Posted by GitBox <gi...@apache.org>.

github-actions[bot] commented on pull request #7520:
URL: https://github.com/apache/arrow/pull/7520#issuecomment-647796781


   https://issues.apache.org/jira/browse/ARROW-9189


----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [arrow] nealrichardson commented on a change in pull request #7520: ARROW-9189: [Website] Improve contributor guide

Posted by GitBox <gi...@apache.org>.

nealrichardson commented on a change in pull request #7520:
URL: https://github.com/apache/arrow/pull/7520#discussion_r444333447



##########
File path: docs/source/developers/contributing.rst
##########
@@ -124,29 +181,72 @@ To contribute a patch:
   `ARROW-767: [C++] Filesystem abstraction <https://github.com/apache/arrow/pull/4225>`_).
 * Make sure that your code passes the unit tests. You can find instructions how
   to run the unit tests for each Arrow component in its respective README file.
+
+Core developers and others with a stake in the part of the project your change
+affects will review, request changes, and hopefully indicate their approval
+in the end. To make the review process smooth for everyone, try to
+
+* Break your work into small, single-purpose patches if possible. It’s much
+  harder to merge in a large change with a lot of disjoint features, and
+  particularly if you're new to the project, smaller changes are much easier
+  for maintainers to accept.
 * Add new unit tests for your code.
+* Follow the style guides for the part(s) of the project you're modifying.
+  Some languages (C++, Python, and Rust, for example) run a lint check in
+  continuous integration. For all languages, see their respective developer
+  documentation and READMEs for style guidance. In general, try to make it look
+  as if the codebase has a single author, and emulate any conventions you see,
+  whether or not they are officially documented or checked.
+
+When tests are passing and the pull request has been approved by the interested
+parties, a committer will merge the pull request. This is done with a
+command-line utility that does a squash merge, so all of your commits will be
+registered as a single commit to the master branch; this simplifies the
+connection between JIRA issues and commits, and it makes it easier to bisect
+history to identify where changes were introduced. A side effect of this way of
+merging is that your pull request will appear in the GitHub interface to have
+been "closed without merge". Do not be alarmed: if you look at the bottom, you
+will see a message that says "@user closed this in $COMMIT".
+
+Local git conventions
++++++++++++++++++++++
+
+If you are tracking the Arrow source repository locally, here are some tips
+for using ``git``.
+
+All Arrow contributors work off of their personal fork of ``apache/arrow``
+and submit pull requests "upstream". Once you've cloned your fork of Arrow,
+be sure to::
+
+    $ git remote add upstream https://github.com/apache/arrow
+
+to set the "upstream" repository.
+
+You are encouraged to develop on branches, rather than your own "master" branch,
+and it helps to keep your fork's master branch synced with ``upstream/master``.
 
-Thank you in advance for your contributions!
+To start a new branch, pull the latest from upstream first::
 
-Common Git conventions followed within the project
---------------------------------------------------
+   $ git fetch upstream
+   $ git checkout master
+   $ git reset --hard upstream/master
+   $ git checkout -b $NEW_BRANCH_NAME
 
-If you are tracking the Arrow source repository locally, following some common Git
-conventions would make everyone's workflow compatible.  These recommendations along with
-their rationale are outlined below.
+It does not matter what you call your branch. Some people like to use the JIRA
+number as branch name, others use descriptive names.
 
-It is strongly discouraged to use a regular ``git merge``, as a linear commit history is
-prefered by the project.  It is much easier to maintain, and makes for easier
-``cherry-picking`` of features; useful for backporting fixes to maintenance releases.
+Once you have a branch going, you should sync with ``upstream/master``
+regularly, as many commits merge to master every day.
+It is recommended to use ``git rebase`` rather than ``git merge``.

Review comment:
       Honestly I don't think it matters what people do on their branches since we squash merge in the end, right?
   
   The last thing I want out of this document is to spark a flame war between `rebase` and `merge` partisans. I wouldn't have added this section myself but there was a JIRA requesting it and someone else added it this weekend.




----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [arrow] wesm commented on a change in pull request #7520: ARROW-9189: [Website] Improve contributor guide

Posted by GitBox <gi...@apache.org>.

wesm commented on a change in pull request #7520:
URL: https://github.com/apache/arrow/pull/7520#discussion_r444288120



##########
File path: docs/source/developers/contributing.rst
##########
@@ -124,29 +181,72 @@ To contribute a patch:
   `ARROW-767: [C++] Filesystem abstraction <https://github.com/apache/arrow/pull/4225>`_).
 * Make sure that your code passes the unit tests. You can find instructions how
   to run the unit tests for each Arrow component in its respective README file.
+
+Core developers and others with a stake in the part of the project your change
+affects will review, request changes, and hopefully indicate their approval
+in the end. To make the review process smooth for everyone, try to
+
+* Break your work into small, single-purpose patches if possible. It’s much
+  harder to merge in a large change with a lot of disjoint features, and
+  particularly if you're new to the project, smaller changes are much easier
+  for maintainers to accept.
 * Add new unit tests for your code.
+* Follow the style guides for the part(s) of the project you're modifying.
+  Some languages (C++, Python, and Rust, for example) run a lint check in
+  continuous integration. For all languages, see their respective developer
+  documentation and READMEs for style guidance. In general, try to make it look
+  as if the codebase has a single author, and emulate any conventions you see,
+  whether or not they are officially documented or checked.
+
+When tests are passing and the pull request has been approved by the interested
+parties, a committer will merge the pull request. This is done with a
+command-line utility that does a squash merge, so all of your commits will be
+registered as a single commit to the master branch; this simplifies the
+connection between JIRA issues and commits, and it makes it easier to bisect
+history to identify where changes were introduced. A side effect of this way of
+merging is that your pull request will appear in the GitHub interface to have
+been "closed without merge". Do not be alarmed: if you look at the bottom, you
+will see a message that says "@user closed this in $COMMIT".
+
+Local git conventions
++++++++++++++++++++++
+
+If you are tracking the Arrow source repository locally, here are some tips
+for using ``git``.
+
+All Arrow contributors work off of their personal fork of ``apache/arrow``
+and submit pull requests "upstream". Once you've cloned your fork of Arrow,
+be sure to::
+
+    $ git remote add upstream https://github.com/apache/arrow
+
+to set the "upstream" repository.
+
+You are encouraged to develop on branches, rather than your own "master" branch,
+and it helps to keep your fork's master branch synced with ``upstream/master``.
 
-Thank you in advance for your contributions!
+To start a new branch, pull the latest from upstream first::
 
-Common Git conventions followed within the project
---------------------------------------------------
+   $ git fetch upstream
+   $ git checkout master
+   $ git reset --hard upstream/master
+   $ git checkout -b $NEW_BRANCH_NAME
 
-If you are tracking the Arrow source repository locally, following some common Git
-conventions would make everyone's workflow compatible.  These recommendations along with
-their rationale are outlined below.
+It does not matter what you call your branch. Some people like to use the JIRA
+number as branch name, others use descriptive names.
 
-It is strongly discouraged to use a regular ``git merge``, as a linear commit history is
-prefered by the project.  It is much easier to maintain, and makes for easier
-``cherry-picking`` of features; useful for backporting fixes to maintenance releases.
+Once you have a branch going, you should sync with ``upstream/master``
+regularly, as many commits merge to master every day.
+It is recommended to use ``git rebase`` rather than ``git merge``.

Review comment:
       FWIW at large organizations like Google, PRs (which are called "changelists") with more than one commit are not accepted. Every proposed patch must be a single rebased commit (this is tightly integrated with Gerrit, Google's code review system). I would be much happier using Gerrit than GitHub PRs because of the incremental code diffing system -- once you experience it, it is difficult to go back. 




----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [arrow] wesm commented on a change in pull request #7520: ARROW-9189: [Website] Improve contributor guide

Posted by GitBox <gi...@apache.org>.

wesm commented on a change in pull request #7520:
URL: https://github.com/apache/arrow/pull/7520#discussion_r444285972



##########
File path: docs/source/developers/contributing.rst
##########
@@ -124,29 +181,72 @@ To contribute a patch:
   `ARROW-767: [C++] Filesystem abstraction <https://github.com/apache/arrow/pull/4225>`_).
 * Make sure that your code passes the unit tests. You can find instructions how
   to run the unit tests for each Arrow component in its respective README file.
+
+Core developers and others with a stake in the part of the project your change
+affects will review, request changes, and hopefully indicate their approval
+in the end. To make the review process smooth for everyone, try to
+
+* Break your work into small, single-purpose patches if possible. It’s much
+  harder to merge in a large change with a lot of disjoint features, and
+  particularly if you're new to the project, smaller changes are much easier
+  for maintainers to accept.
 * Add new unit tests for your code.
+* Follow the style guides for the part(s) of the project you're modifying.
+  Some languages (C++, Python, and Rust, for example) run a lint check in
+  continuous integration. For all languages, see their respective developer
+  documentation and READMEs for style guidance. In general, try to make it look
+  as if the codebase has a single author, and emulate any conventions you see,
+  whether or not they are officially documented or checked.
+
+When tests are passing and the pull request has been approved by the interested
+parties, a committer will merge the pull request. This is done with a
+command-line utility that does a squash merge, so all of your commits will be
+registered as a single commit to the master branch; this simplifies the
+connection between JIRA issues and commits, and it makes it easier to bisect
+history to identify where changes were introduced. A side effect of this way of
+merging is that your pull request will appear in the GitHub interface to have
+been "closed without merge". Do not be alarmed: if you look at the bottom, you
+will see a message that says "@user closed this in $COMMIT".
+
+Local git conventions
++++++++++++++++++++++
+
+If you are tracking the Arrow source repository locally, here are some tips
+for using ``git``.
+
+All Arrow contributors work off of their personal fork of ``apache/arrow``
+and submit pull requests "upstream". Once you've cloned your fork of Arrow,
+be sure to::
+
+    $ git remote add upstream https://github.com/apache/arrow
+
+to set the "upstream" repository.
+
+You are encouraged to develop on branches, rather than your own "master" branch,
+and it helps to keep your fork's master branch synced with ``upstream/master``.
 
-Thank you in advance for your contributions!
+To start a new branch, pull the latest from upstream first::
 
-Common Git conventions followed within the project
---------------------------------------------------
+   $ git fetch upstream
+   $ git checkout master
+   $ git reset --hard upstream/master
+   $ git checkout -b $NEW_BRANCH_NAME
 
-If you are tracking the Arrow source repository locally, following some common Git
-conventions would make everyone's workflow compatible.  These recommendations along with
-their rationale are outlined below.
+It does not matter what you call your branch. Some people like to use the JIRA
+number as branch name, others use descriptive names.
 
-It is strongly discouraged to use a regular ``git merge``, as a linear commit history is
-prefered by the project.  It is much easier to maintain, and makes for easier
-``cherry-picking`` of features; useful for backporting fixes to maintenance releases.
+Once you have a branch going, you should sync with ``upstream/master``
+regularly, as many commits merge to master every day.
+It is recommended to use ``git rebase`` rather than ``git merge``.

Review comment:
       Resolving conflicts in a PR with merge commits can be a nightmare, whereas resolving the same conflicts in a PR that doesn't have the merges is, to me, relatively straightforward. Maybe I'm doing something wrong. Very rarely have I seen anything good come out of `git merge`
   
   So I think we can say "The project maintainers prefer to handle conflict resolution from a rebase standpoint rather than from a merge standpoint. If a PR contains merge commits and contains conflicts, then a maintainer may squash the changes and rebase them to remove the merge commits."




----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [arrow] wesm commented on a change in pull request #7520: ARROW-9189: [Website] Improve contributor guide

Posted by GitBox <gi...@apache.org>.

wesm commented on a change in pull request #7520:
URL: https://github.com/apache/arrow/pull/7520#discussion_r443914793



##########
File path: docs/source/developers/contributing.rst
##########
@@ -17,53 +17,73 @@
 
 .. _contributing:
 
-***********************
-Contribution Guidelines
-***********************
+****************************
+Contributing to Apache Arrow
+****************************
 
-There are many ways to contribute to Apache Arrow:
+Thanks for your interest in the Apache Arrow project. Arrow is a large project
+and may seem overwhelming when you're first getting involved.
+Contributing code is great, but that's probably not the first place to start.
+There are lots of ways to make valuable contributions to the project and
+community.
 
-* Contributing code (we call them "patches")
-* Writing documentation (another form of code, in a way)
-* Participating in discussions on `JIRA <https://issues.apache.org/jira/projects/ARROW/issues>`_ or the `mailing list <ht...@arrow.apache.org>`_
-* Helping users of the libraries
-* Reporting bugs and asking questions
+This page provides some orientation for how to get involved. It also offers
+some recommendations on how to get best results when engaging with the
+community.
 
-Mailing List
-============
+Join the mailing lists
+======================
 
+A good first step to getting involved in the Arrow project is to join the
+mailing lists and participate in discussions where you can.
 Projects in The Apache Software Foundation ("the ASF") use public, archived
 mailing lists to create a public record of each project's development
-activities and decision-making process. As such, all contributors generally
-must be subscribed to the dev@arrow.apache.org mailing list to participate in
-the community.
+activities and decision-making process.
+While lacking the immediacy of chat or other forms of communication,
+the mailing lists give participants the opportunity to slow down and be
+thoughtful in their responses, and they help developers who are spread across
+many timezones to participate more equally.

Review comment:
       Good. 

##########
File path: docs/source/developers/contributing.rst
##########
@@ -76,46 +96,83 @@ visibility. They may add a "Fix version" to indicate that they're considering
 it for inclusion in the next release, though adding that tag is not a
 commitment that it will be done in the next release.
 
-Advanced use
-------------
-
-Once you are involved in the project and want to do more on JIRA, such as
-assign yourself an issue, you will need "Contributor" permissions on the
-Apache Arrow JIRA. To get this role, ask on the mailing list for a project
-maintainer's help.
-
-GitHub issues
--------------
-
-We support `GitHub issues <https://github.com/apache/arrow/issues>`_ as a
-lightweight way to ask questions and engage with
-the Arrow developer community. We use JIRA for maintaining a queue of
-development work and as the public record for work on the project. So, feel
-free to open GitHub issues, but bugs and feature requests will eventually need
-to end up in JIRA, either before or after completing a pull request. Don't be
-surprised if you are immediately asked by a project maintainer to open a JIRA
-issue.
-
-How to contribute patches
-=========================
-
-We prefer to receive contributions in the form of GitHub pull requests. Please
-send pull requests against the `github.com/apache/arrow
-<https://github.com/apache/arrow>`_ repository following the procedure below.
-
-If you are looking for some ideas on what to contribute, check out the JIRA
-issues for the Apache Arrow project. Comment on the issue and/or contact
-dev@arrow.apache.org with your questions and ideas.
-
-If you’d like to report a bug but don’t have time to fix it, you can still post
-it on JIRA, or email the mailing list dev@arrow.apache.org.
+Tips for successful bug reports
++++++++++++++++++++++++++++++++
+
+No one likes having bugs in their software, and in an ideal world, all bugs
+would get fixed as soon as they were reported. However, time and attention are
+finite, especially in an open-source project where most contributors are
+participating in their spare time. In order for your bug to get prompt

Review comment:
       May be worth emphasizing here that all contributors in Apache projects are volunteers and act as individuals, even if they are contributing to the project as part of their job responsibilities. 

##########
File path: docs/source/developers/contributing.rst
##########
@@ -17,53 +17,73 @@
 
 .. _contributing:
 
-***********************
-Contribution Guidelines
-***********************
+****************************
+Contributing to Apache Arrow
+****************************
 
-There are many ways to contribute to Apache Arrow:
+Thanks for your interest in the Apache Arrow project. Arrow is a large project
+and may seem overwhelming when you're first getting involved.
+Contributing code is great, but that's probably not the first place to start.
+There are lots of ways to make valuable contributions to the project and
+community.
 
-* Contributing code (we call them "patches")
-* Writing documentation (another form of code, in a way)
-* Participating in discussions on `JIRA <https://issues.apache.org/jira/projects/ARROW/issues>`_ or the `mailing list <ht...@arrow.apache.org>`_
-* Helping users of the libraries
-* Reporting bugs and asking questions
+This page provides some orientation for how to get involved. It also offers
+some recommendations on how to get best results when engaging with the
+community.
 
-Mailing List
-============
+Join the mailing lists
+======================
 
+A good first step to getting involved in the Arrow project is to join the
+mailing lists and participate in discussions where you can.
 Projects in The Apache Software Foundation ("the ASF") use public, archived
 mailing lists to create a public record of each project's development
-activities and decision-making process. As such, all contributors generally
-must be subscribed to the dev@arrow.apache.org mailing list to participate in
-the community.
+activities and decision-making process.
+While lacking the immediacy of chat or other forms of communication,
+the mailing lists give participants the opportunity to slow down and be
+thoughtful in their responses, and they help developers who are spread across
+many timezones to participate more equally.
 
-Note that you must be subscribed to the mailing list in order to post to it. To
-subscribe, send a blank email to dev-subscribe@arrow.apache.org.
+See `the community page <https://arrow.apache.org/community/>`_ for links to
+subscribe to the mailing lists and to view archives.
 
-Mailing list archives can be found `here <ht...@arrow.apache.org>`_.
+Report bugs and request features
+================================
 
-Issue Tracking
-==============
+Using the software and sharing your experience is a very helpful contribution
+itself. Those who actively develop Arrow need feedback from users on what
+works and what doesn't. Alerting us to unexpected behavior and missing features,
+even if you can't solve the problems yourself, help us understand and prioritize
+work to improve the libraries.
 
-We use the `ASF JIRA <https://issues.apache.org/jira/projects/ARROW/issues>`_
+We use `JIRA <https://issues.apache.org/jira/projects/ARROW/issues>`_
 to manage our development "todo" list and to maintain changelogs for releases.
 In addition, the project's `Confluence site <https://cwiki.apache.org/confluence/display/ARROW>`_
 has some useful higher-level views of the JIRA issues.
 
 To create a JIRA issue, you'll need to have an account on the ASF JIRA, which
 you can `sign yourself up for <https://issues.apache.org/jira/secure/Signup!default.jspa>`_.
-The JIRA server hosts bugs and issues for multiple Apache projects.  The JIRA
+The JIRA server hosts bugs and issues for multiple Apache projects. The JIRA
 project name for Arrow is "ARROW".
 
-Before you create a new bug entry, we recommend you first
-`search <https://issues.apache.org/jira/projects/ARROW/issues/ARROW-5140?filter=allopenissues>`_
+You don't need any special permissions on JIRA to be able to create issues.
+Once you are more involved in the project and want to do more on JIRA, such as
+assign yourself an issue, you will need "Contributor" permissions on the
+Apache Arrow JIRA. To get this role, ask on the mailing list for a project
+maintainer's help.
+
+Tips for using JIRA
++++++++++++++++++++
+
+Before you create a new issue, we recommend you first
+`search <https://issues.apache.org/jira/issues/?jql=project%20%3D%20ARROW%20AND%20resolution%20%3D%20Unresolved>`_
 among existing Arrow issues.
 
 When reporting a new issue, follow these conventions to help make sure the
 right people see it:
 
-* Enter the component your issue pertains to (for example "Python" or "C++").
+* Use the **Component** field to indicate the area of the project that your
+  issue pertains to (for example "Python" or "C++").
 * Also prefix the issue title with the component name in brackets, for example
   ``[Python] issue name`` ; this helps when navigating lists of open issues.

Review comment:
       May want to mention here that the component name helps generate more readable changelogs when we release

##########
File path: docs/source/developers/contributing.rst
##########
@@ -124,29 +181,72 @@ To contribute a patch:
   `ARROW-767: [C++] Filesystem abstraction <https://github.com/apache/arrow/pull/4225>`_).
 * Make sure that your code passes the unit tests. You can find instructions how
   to run the unit tests for each Arrow component in its respective README file.
+
+Core developers and others with a stake in the part of the project your change
+affects will review, request changes, and hopefully indicate their approval
+in the end. To make the review process smooth for everyone, try to
+
+* Break your work into small, single-purpose patches if possible. It’s much
+  harder to merge in a large change with a lot of disjoint features, and
+  particularly if you're new to the project, smaller changes are much easier
+  for maintainers to accept.
 * Add new unit tests for your code.
+* Follow the style guides for the part(s) of the project you're modifying.
+  Some languages (C++, Python, and Rust, for example) run a lint check in
+  continuous integration. For all languages, see their respective developer
+  documentation and READMEs for style guidance. In general, try to make it look
+  as if the codebase has a single author, and emulate any conventions you see,
+  whether or not they are officially documented or checked.
+
+When tests are passing and the pull request has been approved by the interested
+parties, a committer will merge the pull request. This is done with a
+command-line utility that does a squash merge, so all of your commits will be
+registered as a single commit to the master branch; this simplifies the
+connection between JIRA issues and commits, and it makes it easier to bisect
+history to identify where changes were introduced. A side effect of this way of

Review comment:
       Mention here that the merge tool includes the PR description in the commit message while excluding any comments from the individual commits, so they should put the information about what is in the patch in the GitHub PR description. 

##########
File path: docs/source/developers/contributing.rst
##########
@@ -124,29 +181,72 @@ To contribute a patch:
   `ARROW-767: [C++] Filesystem abstraction <https://github.com/apache/arrow/pull/4225>`_).
 * Make sure that your code passes the unit tests. You can find instructions how
   to run the unit tests for each Arrow component in its respective README file.
+
+Core developers and others with a stake in the part of the project your change
+affects will review, request changes, and hopefully indicate their approval
+in the end. To make the review process smooth for everyone, try to
+
+* Break your work into small, single-purpose patches if possible. It’s much
+  harder to merge in a large change with a lot of disjoint features, and
+  particularly if you're new to the project, smaller changes are much easier
+  for maintainers to accept.
 * Add new unit tests for your code.
+* Follow the style guides for the part(s) of the project you're modifying.
+  Some languages (C++, Python, and Rust, for example) run a lint check in
+  continuous integration. For all languages, see their respective developer
+  documentation and READMEs for style guidance. In general, try to make it look
+  as if the codebase has a single author, and emulate any conventions you see,
+  whether or not they are officially documented or checked.
+
+When tests are passing and the pull request has been approved by the interested
+parties, a committer will merge the pull request. This is done with a

Review comment:
       link to the committer page on the website?

##########
File path: docs/source/developers/contributing.rst
##########
@@ -124,29 +181,72 @@ To contribute a patch:
   `ARROW-767: [C++] Filesystem abstraction <https://github.com/apache/arrow/pull/4225>`_).
 * Make sure that your code passes the unit tests. You can find instructions how
   to run the unit tests for each Arrow component in its respective README file.
+
+Core developers and others with a stake in the part of the project your change
+affects will review, request changes, and hopefully indicate their approval
+in the end. To make the review process smooth for everyone, try to
+
+* Break your work into small, single-purpose patches if possible. It’s much
+  harder to merge in a large change with a lot of disjoint features, and
+  particularly if you're new to the project, smaller changes are much easier
+  for maintainers to accept.
 * Add new unit tests for your code.
+* Follow the style guides for the part(s) of the project you're modifying.
+  Some languages (C++, Python, and Rust, for example) run a lint check in
+  continuous integration. For all languages, see their respective developer
+  documentation and READMEs for style guidance. In general, try to make it look
+  as if the codebase has a single author, and emulate any conventions you see,
+  whether or not they are officially documented or checked.
+
+When tests are passing and the pull request has been approved by the interested
+parties, a committer will merge the pull request. This is done with a
+command-line utility that does a squash merge, so all of your commits will be
+registered as a single commit to the master branch; this simplifies the
+connection between JIRA issues and commits, and it makes it easier to bisect
+history to identify where changes were introduced. A side effect of this way of
+merging is that your pull request will appear in the GitHub interface to have
+been "closed without merge". Do not be alarmed: if you look at the bottom, you
+will see a message that says "@user closed this in $COMMIT".

Review comment:
       Mention that the commit message of the merged commit contains the name of the contributor along with any co-authors and a reference to the pull request number on GitHub

##########
File path: docs/source/developers/contributing.rst
##########
@@ -124,29 +181,72 @@ To contribute a patch:
   `ARROW-767: [C++] Filesystem abstraction <https://github.com/apache/arrow/pull/4225>`_).
 * Make sure that your code passes the unit tests. You can find instructions how
   to run the unit tests for each Arrow component in its respective README file.
+
+Core developers and others with a stake in the part of the project your change
+affects will review, request changes, and hopefully indicate their approval
+in the end. To make the review process smooth for everyone, try to
+
+* Break your work into small, single-purpose patches if possible. It’s much
+  harder to merge in a large change with a lot of disjoint features, and
+  particularly if you're new to the project, smaller changes are much easier
+  for maintainers to accept.
 * Add new unit tests for your code.
+* Follow the style guides for the part(s) of the project you're modifying.
+  Some languages (C++, Python, and Rust, for example) run a lint check in
+  continuous integration. For all languages, see their respective developer
+  documentation and READMEs for style guidance. In general, try to make it look
+  as if the codebase has a single author, and emulate any conventions you see,
+  whether or not they are officially documented or checked.
+
+When tests are passing and the pull request has been approved by the interested
+parties, a committer will merge the pull request. This is done with a
+command-line utility that does a squash merge, so all of your commits will be
+registered as a single commit to the master branch; this simplifies the
+connection between JIRA issues and commits, and it makes it easier to bisect
+history to identify where changes were introduced. A side effect of this way of
+merging is that your pull request will appear in the GitHub interface to have
+been "closed without merge". Do not be alarmed: if you look at the bottom, you
+will see a message that says "@user closed this in $COMMIT".
+
+Local git conventions
++++++++++++++++++++++
+
+If you are tracking the Arrow source repository locally, here are some tips
+for using ``git``.
+
+All Arrow contributors work off of their personal fork of ``apache/arrow``
+and submit pull requests "upstream". Once you've cloned your fork of Arrow,
+be sure to::
+
+    $ git remote add upstream https://github.com/apache/arrow
+
+to set the "upstream" repository.
+
+You are encouraged to develop on branches, rather than your own "master" branch,
+and it helps to keep your fork's master branch synced with ``upstream/master``.
 
-Thank you in advance for your contributions!
+To start a new branch, pull the latest from upstream first::
 
-Common Git conventions followed within the project
---------------------------------------------------
+   $ git fetch upstream
+   $ git checkout master
+   $ git reset --hard upstream/master
+   $ git checkout -b $NEW_BRANCH_NAME
 
-If you are tracking the Arrow source repository locally, following some common Git
-conventions would make everyone's workflow compatible.  These recommendations along with
-their rationale are outlined below.
+It does not matter what you call your branch. Some people like to use the JIRA
+number as branch name, others use descriptive names.
 
-It is strongly discouraged to use a regular ``git merge``, as a linear commit history is
-prefered by the project.  It is much easier to maintain, and makes for easier
-``cherry-picking`` of features; useful for backporting fixes to maintenance releases.
+Once you have a branch going, you should sync with ``upstream/master``
+regularly, as many commits merge to master every day.

Review comment:
       "are merged"

##########
File path: docs/source/developers/contributing.rst
##########
@@ -168,11 +274,15 @@ remote repo still holds the old history, you would need to do a force push. ::
 look at your updates, please ensure you comment on the PR on GitHub as simply force
 pushing does not trigger a notification in the GitHub user interface.
 
-Simplifying ``rebase``
-++++++++++++++++++++++
+Also, once you have a pull request up, be sure you pull from ``origin``
+before rebasing and force-pushing. Arrow maintainers can push commits directly
+to your branch, which they sometimes do to help move a pull request along.
+In addition, the GitHub PR "suggestion" feature can also add commits to
+your branch, so it is possible that your local copy of your branch is missing
+some additions.

Review comment:
       I'm not a fan of the "suggestion" feature and don't want to encourage its use

##########
File path: docs/source/developers/contributing.rst
##########
@@ -124,29 +181,72 @@ To contribute a patch:
   `ARROW-767: [C++] Filesystem abstraction <https://github.com/apache/arrow/pull/4225>`_).
 * Make sure that your code passes the unit tests. You can find instructions how
   to run the unit tests for each Arrow component in its respective README file.
+
+Core developers and others with a stake in the part of the project your change
+affects will review, request changes, and hopefully indicate their approval
+in the end. To make the review process smooth for everyone, try to
+
+* Break your work into small, single-purpose patches if possible. It’s much
+  harder to merge in a large change with a lot of disjoint features, and
+  particularly if you're new to the project, smaller changes are much easier
+  for maintainers to accept.
 * Add new unit tests for your code.
+* Follow the style guides for the part(s) of the project you're modifying.
+  Some languages (C++, Python, and Rust, for example) run a lint check in
+  continuous integration. For all languages, see their respective developer
+  documentation and READMEs for style guidance. In general, try to make it look
+  as if the codebase has a single author, and emulate any conventions you see,
+  whether or not they are officially documented or checked.
+
+When tests are passing and the pull request has been approved by the interested
+parties, a committer will merge the pull request. This is done with a
+command-line utility that does a squash merge, so all of your commits will be

Review comment:
       May also want to mention that it makes it easier for maintainers to prepare patch releases by cherry-picking patches into maintenance branches. There are still some people out there who aren't convinced by the squash-merge-linear-history paradigm so it helps to offer as many justifications as possible =)

##########
File path: docs/source/developers/contributing.rst
##########
@@ -168,11 +274,15 @@ remote repo still holds the old history, you would need to do a force push. ::
 look at your updates, please ensure you comment on the PR on GitHub as simply force
 pushing does not trigger a notification in the GitHub user interface.
 
-Simplifying ``rebase``
-++++++++++++++++++++++
+Also, once you have a pull request up, be sure you pull from ``origin``
+before rebasing and force-pushing. Arrow maintainers can push commits directly
+to your branch, which they sometimes do to help move a pull request along.
+In addition, the GitHub PR "suggestion" feature can also add commits to
+your branch, so it is possible that your local copy of your branch is missing
+some additions.
 
-If you set the following in your repo's ``.git/config``, the ``--rebase`` option can be
-ommitted from the ``git pull`` command, as it is implied by default. ::
+Code of Conduct

Review comment:
       Can you put this at the top of the document?

##########
File path: docs/source/developers/contributing.rst
##########
@@ -124,29 +181,72 @@ To contribute a patch:
   `ARROW-767: [C++] Filesystem abstraction <https://github.com/apache/arrow/pull/4225>`_).
 * Make sure that your code passes the unit tests. You can find instructions how
   to run the unit tests for each Arrow component in its respective README file.
+
+Core developers and others with a stake in the part of the project your change
+affects will review, request changes, and hopefully indicate their approval
+in the end. To make the review process smooth for everyone, try to
+
+* Break your work into small, single-purpose patches if possible. It’s much
+  harder to merge in a large change with a lot of disjoint features, and
+  particularly if you're new to the project, smaller changes are much easier
+  for maintainers to accept.
 * Add new unit tests for your code.
+* Follow the style guides for the part(s) of the project you're modifying.
+  Some languages (C++, Python, and Rust, for example) run a lint check in
+  continuous integration. For all languages, see their respective developer
+  documentation and READMEs for style guidance. In general, try to make it look
+  as if the codebase has a single author, and emulate any conventions you see,
+  whether or not they are officially documented or checked.
+
+When tests are passing and the pull request has been approved by the interested
+parties, a committer will merge the pull request. This is done with a
+command-line utility that does a squash merge, so all of your commits will be
+registered as a single commit to the master branch; this simplifies the
+connection between JIRA issues and commits, and it makes it easier to bisect
+history to identify where changes were introduced. A side effect of this way of
+merging is that your pull request will appear in the GitHub interface to have
+been "closed without merge". Do not be alarmed: if you look at the bottom, you
+will see a message that says "@user closed this in $COMMIT".
+
+Local git conventions
++++++++++++++++++++++
+
+If you are tracking the Arrow source repository locally, here are some tips
+for using ``git``.
+
+All Arrow contributors work off of their personal fork of ``apache/arrow``
+and submit pull requests "upstream". Once you've cloned your fork of Arrow,
+be sure to::
+
+    $ git remote add upstream https://github.com/apache/arrow
+
+to set the "upstream" repository.
+
+You are encouraged to develop on branches, rather than your own "master" branch,
+and it helps to keep your fork's master branch synced with ``upstream/master``.
 
-Thank you in advance for your contributions!
+To start a new branch, pull the latest from upstream first::
 
-Common Git conventions followed within the project
---------------------------------------------------
+   $ git fetch upstream
+   $ git checkout master
+   $ git reset --hard upstream/master

Review comment:
       I use `pull --ff-only upstream master`. `reset --hard` should only ever be necessary if you did something wrong before, and `reset` could actually be destructive (of course everything is preserved in `git reflog`)

##########
File path: docs/source/developers/contributing.rst
##########
@@ -124,29 +181,72 @@ To contribute a patch:
   `ARROW-767: [C++] Filesystem abstraction <https://github.com/apache/arrow/pull/4225>`_).
 * Make sure that your code passes the unit tests. You can find instructions how
   to run the unit tests for each Arrow component in its respective README file.
+
+Core developers and others with a stake in the part of the project your change
+affects will review, request changes, and hopefully indicate their approval
+in the end. To make the review process smooth for everyone, try to
+
+* Break your work into small, single-purpose patches if possible. It’s much
+  harder to merge in a large change with a lot of disjoint features, and
+  particularly if you're new to the project, smaller changes are much easier
+  for maintainers to accept.
 * Add new unit tests for your code.
+* Follow the style guides for the part(s) of the project you're modifying.
+  Some languages (C++, Python, and Rust, for example) run a lint check in
+  continuous integration. For all languages, see their respective developer
+  documentation and READMEs for style guidance. In general, try to make it look
+  as if the codebase has a single author, and emulate any conventions you see,
+  whether or not they are officially documented or checked.
+
+When tests are passing and the pull request has been approved by the interested
+parties, a committer will merge the pull request. This is done with a
+command-line utility that does a squash merge, so all of your commits will be
+registered as a single commit to the master branch; this simplifies the
+connection between JIRA issues and commits, and it makes it easier to bisect
+history to identify where changes were introduced. A side effect of this way of
+merging is that your pull request will appear in the GitHub interface to have
+been "closed without merge". Do not be alarmed: if you look at the bottom, you
+will see a message that says "@user closed this in $COMMIT".
+
+Local git conventions
++++++++++++++++++++++
+
+If you are tracking the Arrow source repository locally, here are some tips
+for using ``git``.
+
+All Arrow contributors work off of their personal fork of ``apache/arrow``
+and submit pull requests "upstream". Once you've cloned your fork of Arrow,
+be sure to::
+
+    $ git remote add upstream https://github.com/apache/arrow
+
+to set the "upstream" repository.
+
+You are encouraged to develop on branches, rather than your own "master" branch,
+and it helps to keep your fork's master branch synced with ``upstream/master``.
 
-Thank you in advance for your contributions!
+To start a new branch, pull the latest from upstream first::
 
-Common Git conventions followed within the project
---------------------------------------------------
+   $ git fetch upstream
+   $ git checkout master
+   $ git reset --hard upstream/master
+   $ git checkout -b $NEW_BRANCH_NAME
 
-If you are tracking the Arrow source repository locally, following some common Git
-conventions would make everyone's workflow compatible.  These recommendations along with
-their rationale are outlined below.
+It does not matter what you call your branch. Some people like to use the JIRA
+number as branch name, others use descriptive names.
 
-It is strongly discouraged to use a regular ``git merge``, as a linear commit history is
-prefered by the project.  It is much easier to maintain, and makes for easier
-``cherry-picking`` of features; useful for backporting fixes to maintenance releases.
+Once you have a branch going, you should sync with ``upstream/master``
+regularly, as many commits merge to master every day.
+It is recommended to use ``git rebase`` rather than ``git merge``.
 To sync your local copy of a branch, you may do the following::
 
     $ git pull upstream branch --rebase

Review comment:
       maybe write `$BRANCH` here for clarity




----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [arrow] nealrichardson commented on a change in pull request #7520: ARROW-9189: [Website] Improve contributor guide

Posted by GitBox <gi...@apache.org>.

nealrichardson commented on a change in pull request #7520:
URL: https://github.com/apache/arrow/pull/7520#discussion_r444318497



##########
File path: docs/source/developers/contributing.rst
##########
@@ -124,29 +181,72 @@ To contribute a patch:
   `ARROW-767: [C++] Filesystem abstraction <https://github.com/apache/arrow/pull/4225>`_).
 * Make sure that your code passes the unit tests. You can find instructions how
   to run the unit tests for each Arrow component in its respective README file.
+
+Core developers and others with a stake in the part of the project your change
+affects will review, request changes, and hopefully indicate their approval
+in the end. To make the review process smooth for everyone, try to
+
+* Break your work into small, single-purpose patches if possible. It’s much
+  harder to merge in a large change with a lot of disjoint features, and
+  particularly if you're new to the project, smaller changes are much easier
+  for maintainers to accept.
 * Add new unit tests for your code.
+* Follow the style guides for the part(s) of the project you're modifying.
+  Some languages (C++, Python, and Rust, for example) run a lint check in
+  continuous integration. For all languages, see their respective developer
+  documentation and READMEs for style guidance. In general, try to make it look
+  as if the codebase has a single author, and emulate any conventions you see,
+  whether or not they are officially documented or checked.
+
+When tests are passing and the pull request has been approved by the interested
+parties, a committer will merge the pull request. This is done with a
+command-line utility that does a squash merge, so all of your commits will be
+registered as a single commit to the master branch; this simplifies the
+connection between JIRA issues and commits, and it makes it easier to bisect
+history to identify where changes were introduced. A side effect of this way of
+merging is that your pull request will appear in the GitHub interface to have
+been "closed without merge". Do not be alarmed: if you look at the bottom, you
+will see a message that says "@user closed this in $COMMIT".
+
+Local git conventions
++++++++++++++++++++++
+
+If you are tracking the Arrow source repository locally, here are some tips
+for using ``git``.
+
+All Arrow contributors work off of their personal fork of ``apache/arrow``
+and submit pull requests "upstream". Once you've cloned your fork of Arrow,
+be sure to::
+
+    $ git remote add upstream https://github.com/apache/arrow
+
+to set the "upstream" repository.
+
+You are encouraged to develop on branches, rather than your own "master" branch,
+and it helps to keep your fork's master branch synced with ``upstream/master``.
 
-Thank you in advance for your contributions!
+To start a new branch, pull the latest from upstream first::
 
-Common Git conventions followed within the project
---------------------------------------------------
+   $ git fetch upstream
+   $ git checkout master
+   $ git reset --hard upstream/master
+   $ git checkout -b $NEW_BRANCH_NAME
 
-If you are tracking the Arrow source repository locally, following some common Git
-conventions would make everyone's workflow compatible.  These recommendations along with
-their rationale are outlined below.
+It does not matter what you call your branch. Some people like to use the JIRA
+number as branch name, others use descriptive names.
 
-It is strongly discouraged to use a regular ``git merge``, as a linear commit history is
-prefered by the project.  It is much easier to maintain, and makes for easier
-``cherry-picking`` of features; useful for backporting fixes to maintenance releases.
+Once you have a branch going, you should sync with ``upstream/master``
+regularly, as many commits merge to master every day.
+It is recommended to use ``git rebase`` rather than ``git merge``.
 To sync your local copy of a branch, you may do the following::
 
     $ git pull upstream branch --rebase

Review comment:
       IDK personally, and IMO it's hard to give `git` advice because everyone has slightly different workflows that work for them




----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [arrow] nealrichardson commented on a change in pull request #7520: ARROW-9189: [Website] Improve contributor guide

Posted by GitBox <gi...@apache.org>.

nealrichardson commented on a change in pull request #7520:
URL: https://github.com/apache/arrow/pull/7520#discussion_r444533246



##########
File path: docs/source/developers/contributing.rst
##########
@@ -76,46 +96,83 @@ visibility. They may add a "Fix version" to indicate that they're considering
 it for inclusion in the next release, though adding that tag is not a
 commitment that it will be done in the next release.
 
-Advanced use
-------------
-
-Once you are involved in the project and want to do more on JIRA, such as
-assign yourself an issue, you will need "Contributor" permissions on the
-Apache Arrow JIRA. To get this role, ask on the mailing list for a project
-maintainer's help.
-
-GitHub issues
--------------
-
-We support `GitHub issues <https://github.com/apache/arrow/issues>`_ as a
-lightweight way to ask questions and engage with
-the Arrow developer community. We use JIRA for maintaining a queue of
-development work and as the public record for work on the project. So, feel
-free to open GitHub issues, but bugs and feature requests will eventually need
-to end up in JIRA, either before or after completing a pull request. Don't be
-surprised if you are immediately asked by a project maintainer to open a JIRA
-issue.
-
-How to contribute patches
-=========================
-
-We prefer to receive contributions in the form of GitHub pull requests. Please
-send pull requests against the `github.com/apache/arrow
-<https://github.com/apache/arrow>`_ repository following the procedure below.
-
-If you are looking for some ideas on what to contribute, check out the JIRA
-issues for the Apache Arrow project. Comment on the issue and/or contact
-dev@arrow.apache.org with your questions and ideas.
-
-If you’d like to report a bug but don’t have time to fix it, you can still post
-it on JIRA, or email the mailing list dev@arrow.apache.org.
+Tips for successful bug reports
++++++++++++++++++++++++++++++++
+
+No one likes having bugs in their software, and in an ideal world, all bugs
+would get fixed as soon as they were reported. However, time and attention are
+finite, especially in an open-source project where most contributors are
+participating in their spare time. In order for your bug to get prompt
+attention, there are things you can do to make it easier for contributors to
+reproduce and fix it.
+
+When you're reporting a bug, please help us understand the issue by providing,
+to the best of your ability,
+
+* Clear, minimal steps to reproduce the issue, with as few non-Arrow
+  dependencies as possible. If there's a problem on reading a file, try to
+  provide as small of an example file as possible, or code to create one.
+  If your bug report says "it crashes trying to read my file, but I can't
+  share it with you," it's really hard for us to debug.
+* Any relevant operating system, language, and library version information
+* If it isn't obvious, clearly state the expected behavior and what actually
+  happened.
+
+If a developer can't get a failing unit test, they won't be able to know that
+the issue has been identified, and they won't know when it has been fixed.
+Try to anticipate the questions you might be asked by someone working to
+understand the issue and provide those supporting details up front.
+

Review comment:
       I added a couple of links; feel free to add others if you have favorites




----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [arrow] jorisvandenbossche commented on a change in pull request #7520: ARROW-9189: [Website] Improve contributor guide

Posted by GitBox <gi...@apache.org>.

jorisvandenbossche commented on a change in pull request #7520:
URL: https://github.com/apache/arrow/pull/7520#discussion_r444268553



##########
File path: docs/source/developers/contributing.rst
##########
@@ -124,29 +181,72 @@ To contribute a patch:
   `ARROW-767: [C++] Filesystem abstraction <https://github.com/apache/arrow/pull/4225>`_).
 * Make sure that your code passes the unit tests. You can find instructions how
   to run the unit tests for each Arrow component in its respective README file.
+
+Core developers and others with a stake in the part of the project your change
+affects will review, request changes, and hopefully indicate their approval
+in the end. To make the review process smooth for everyone, try to
+
+* Break your work into small, single-purpose patches if possible. It’s much
+  harder to merge in a large change with a lot of disjoint features, and
+  particularly if you're new to the project, smaller changes are much easier
+  for maintainers to accept.
 * Add new unit tests for your code.
+* Follow the style guides for the part(s) of the project you're modifying.
+  Some languages (C++, Python, and Rust, for example) run a lint check in
+  continuous integration. For all languages, see their respective developer
+  documentation and READMEs for style guidance. In general, try to make it look
+  as if the codebase has a single author, and emulate any conventions you see,
+  whether or not they are officially documented or checked.
+
+When tests are passing and the pull request has been approved by the interested
+parties, a committer will merge the pull request. This is done with a
+command-line utility that does a squash merge, so all of your commits will be
+registered as a single commit to the master branch; this simplifies the
+connection between JIRA issues and commits, and it makes it easier to bisect
+history to identify where changes were introduced. A side effect of this way of
+merging is that your pull request will appear in the GitHub interface to have
+been "closed without merge". Do not be alarmed: if you look at the bottom, you
+will see a message that says "@user closed this in $COMMIT".
+
+Local git conventions
++++++++++++++++++++++
+
+If you are tracking the Arrow source repository locally, here are some tips
+for using ``git``.
+
+All Arrow contributors work off of their personal fork of ``apache/arrow``
+and submit pull requests "upstream". Once you've cloned your fork of Arrow,
+be sure to::
+
+    $ git remote add upstream https://github.com/apache/arrow
+
+to set the "upstream" repository.
+
+You are encouraged to develop on branches, rather than your own "master" branch,
+and it helps to keep your fork's master branch synced with ``upstream/master``.
 
-Thank you in advance for your contributions!
+To start a new branch, pull the latest from upstream first::
 
-Common Git conventions followed within the project
---------------------------------------------------
+   $ git fetch upstream
+   $ git checkout master
+   $ git reset --hard upstream/master
+   $ git checkout -b $NEW_BRANCH_NAME
 
-If you are tracking the Arrow source repository locally, following some common Git
-conventions would make everyone's workflow compatible.  These recommendations along with
-their rationale are outlined below.
+It does not matter what you call your branch. Some people like to use the JIRA
+number as branch name, others use descriptive names.
 
-It is strongly discouraged to use a regular ``git merge``, as a linear commit history is
-prefered by the project.  It is much easier to maintain, and makes for easier
-``cherry-picking`` of features; useful for backporting fixes to maintenance releases.
+Once you have a branch going, you should sync with ``upstream/master``
+regularly, as many commits merge to master every day.
+It is recommended to use ``git rebase`` rather than ``git merge``.
 To sync your local copy of a branch, you may do the following::
 
     $ git pull upstream branch --rebase

Review comment:
       Is this doing the same as `git rebase upstream/master` ? (I am used to doing this)
   
   EDIT: ah, I suppose my suggestion needs a `git fetch upstream/master` first, so the above is probably the one-liner to do this

##########
File path: docs/source/developers/contributing.rst
##########
@@ -17,53 +17,73 @@
 
 .. _contributing:
 
-***********************
-Contribution Guidelines
-***********************
+****************************
+Contributing to Apache Arrow
+****************************
 
-There are many ways to contribute to Apache Arrow:
+Thanks for your interest in the Apache Arrow project. Arrow is a large project
+and may seem overwhelming when you're first getting involved.
+Contributing code is great, but that's probably not the first place to start.
+There are lots of ways to make valuable contributions to the project and
+community.
 
-* Contributing code (we call them "patches")
-* Writing documentation (another form of code, in a way)
-* Participating in discussions on `JIRA <https://issues.apache.org/jira/projects/ARROW/issues>`_ or the `mailing list <ht...@arrow.apache.org>`_
-* Helping users of the libraries
-* Reporting bugs and asking questions
+This page provides some orientation for how to get involved. It also offers
+some recommendations on how to get best results when engaging with the
+community.
 
-Mailing List
-============
+Join the mailing lists
+======================
 
+A good first step to getting involved in the Arrow project is to join the
+mailing lists and participate in discussions where you can.
 Projects in The Apache Software Foundation ("the ASF") use public, archived
 mailing lists to create a public record of each project's development
-activities and decision-making process. As such, all contributors generally
-must be subscribed to the dev@arrow.apache.org mailing list to participate in
-the community.
+activities and decision-making process.
+While lacking the immediacy of chat or other forms of communication,
+the mailing lists give participants the opportunity to slow down and be
+thoughtful in their responses, and they help developers who are spread across
+many timezones to participate more equally.
 
-Note that you must be subscribed to the mailing list in order to post to it. To
-subscribe, send a blank email to dev-subscribe@arrow.apache.org.
+See `the community page <https://arrow.apache.org/community/>`_ for links to
+subscribe to the mailing lists and to view archives.
 
-Mailing list archives can be found `here <ht...@arrow.apache.org>`_.
+Report bugs and request features

Review comment:
       ```suggestion
   Report bugs and propose features
   ```
   
   (not necessarily better language, but just needed to think about how we sometimes complain about users gratuituously "requesting" features in the meaning of expecting them to be implemented)

##########
File path: docs/source/developers/contributing.rst
##########
@@ -76,46 +96,83 @@ visibility. They may add a "Fix version" to indicate that they're considering
 it for inclusion in the next release, though adding that tag is not a
 commitment that it will be done in the next release.
 
-Advanced use
-------------
-
-Once you are involved in the project and want to do more on JIRA, such as
-assign yourself an issue, you will need "Contributor" permissions on the
-Apache Arrow JIRA. To get this role, ask on the mailing list for a project
-maintainer's help.
-
-GitHub issues
--------------
-
-We support `GitHub issues <https://github.com/apache/arrow/issues>`_ as a
-lightweight way to ask questions and engage with
-the Arrow developer community. We use JIRA for maintaining a queue of
-development work and as the public record for work on the project. So, feel
-free to open GitHub issues, but bugs and feature requests will eventually need
-to end up in JIRA, either before or after completing a pull request. Don't be
-surprised if you are immediately asked by a project maintainer to open a JIRA
-issue.
-
-How to contribute patches
-=========================
-
-We prefer to receive contributions in the form of GitHub pull requests. Please
-send pull requests against the `github.com/apache/arrow
-<https://github.com/apache/arrow>`_ repository following the procedure below.
-
-If you are looking for some ideas on what to contribute, check out the JIRA
-issues for the Apache Arrow project. Comment on the issue and/or contact
-dev@arrow.apache.org with your questions and ideas.
-
-If you’d like to report a bug but don’t have time to fix it, you can still post
-it on JIRA, or email the mailing list dev@arrow.apache.org.
+Tips for successful bug reports
++++++++++++++++++++++++++++++++
+
+No one likes having bugs in their software, and in an ideal world, all bugs
+would get fixed as soon as they were reported. However, time and attention are
+finite, especially in an open-source project where most contributors are
+participating in their spare time. In order for your bug to get prompt
+attention, there are things you can do to make it easier for contributors to
+reproduce and fix it.
+
+When you're reporting a bug, please help us understand the issue by providing,
+to the best of your ability,
+
+* Clear, minimal steps to reproduce the issue, with as few non-Arrow
+  dependencies as possible. If there's a problem on reading a file, try to
+  provide as small of an example file as possible, or code to create one.
+  If your bug report says "it crashes trying to read my file, but I can't
+  share it with you," it's really hard for us to debug.
+* Any relevant operating system, language, and library version information
+* If it isn't obvious, clearly state the expected behavior and what actually
+  happened.
+
+If a developer can't get a failing unit test, they won't be able to know that
+the issue has been identified, and they won't know when it has been fixed.
+Try to anticipate the questions you might be asked by someone working to
+understand the issue and provide those supporting details up front.
+

Review comment:
       Would it be helpful to link here to some resources about this that are language specific (eg reprex in R), although we want to keep it general here I suppose.

##########
File path: docs/source/developers/contributing.rst
##########
@@ -168,11 +274,15 @@ remote repo still holds the old history, you would need to do a force push. ::
 look at your updates, please ensure you comment on the PR on GitHub as simply force
 pushing does not trigger a notification in the GitHub user interface.
 
-Simplifying ``rebase``
-++++++++++++++++++++++
+Also, once you have a pull request up, be sure you pull from ``origin``
+before rebasing and force-pushing. Arrow maintainers can push commits directly
+to your branch, which they sometimes do to help move a pull request along.
+In addition, the GitHub PR "suggestion" feature can also add commits to
+your branch, so it is possible that your local copy of your branch is missing
+some additions.

Review comment:
       I don't think this paragraph is necessarily encouraging it, just mentioning how to resolve it if some reviewers use it
   
   (I personally like the feature, not necessarily to then commit through the github interface, but just as a means to give a much more concrete review comment, instead of trying to describe in words what you would propose to change)

##########
File path: docs/source/developers/contributing.rst
##########
@@ -124,29 +181,72 @@ To contribute a patch:
   `ARROW-767: [C++] Filesystem abstraction <https://github.com/apache/arrow/pull/4225>`_).
 * Make sure that your code passes the unit tests. You can find instructions how
   to run the unit tests for each Arrow component in its respective README file.
+
+Core developers and others with a stake in the part of the project your change
+affects will review, request changes, and hopefully indicate their approval
+in the end. To make the review process smooth for everyone, try to
+
+* Break your work into small, single-purpose patches if possible. It’s much
+  harder to merge in a large change with a lot of disjoint features, and
+  particularly if you're new to the project, smaller changes are much easier
+  for maintainers to accept.
 * Add new unit tests for your code.
+* Follow the style guides for the part(s) of the project you're modifying.
+  Some languages (C++, Python, and Rust, for example) run a lint check in
+  continuous integration. For all languages, see their respective developer
+  documentation and READMEs for style guidance. In general, try to make it look
+  as if the codebase has a single author, and emulate any conventions you see,
+  whether or not they are officially documented or checked.
+
+When tests are passing and the pull request has been approved by the interested
+parties, a committer will merge the pull request. This is done with a
+command-line utility that does a squash merge, so all of your commits will be
+registered as a single commit to the master branch; this simplifies the
+connection between JIRA issues and commits, and it makes it easier to bisect
+history to identify where changes were introduced. A side effect of this way of
+merging is that your pull request will appear in the GitHub interface to have
+been "closed without merge". Do not be alarmed: if you look at the bottom, you
+will see a message that says "@user closed this in $COMMIT".
+
+Local git conventions
++++++++++++++++++++++
+
+If you are tracking the Arrow source repository locally, here are some tips
+for using ``git``.
+
+All Arrow contributors work off of their personal fork of ``apache/arrow``
+and submit pull requests "upstream". Once you've cloned your fork of Arrow,
+be sure to::
+
+    $ git remote add upstream https://github.com/apache/arrow
+
+to set the "upstream" repository.
+
+You are encouraged to develop on branches, rather than your own "master" branch,
+and it helps to keep your fork's master branch synced with ``upstream/master``.
 
-Thank you in advance for your contributions!
+To start a new branch, pull the latest from upstream first::
 
-Common Git conventions followed within the project
---------------------------------------------------
+   $ git fetch upstream
+   $ git checkout master
+   $ git reset --hard upstream/master
+   $ git checkout -b $NEW_BRANCH_NAME
 
-If you are tracking the Arrow source repository locally, following some common Git
-conventions would make everyone's workflow compatible.  These recommendations along with
-their rationale are outlined below.
+It does not matter what you call your branch. Some people like to use the JIRA
+number as branch name, others use descriptive names.
 
-It is strongly discouraged to use a regular ``git merge``, as a linear commit history is
-prefered by the project.  It is much easier to maintain, and makes for easier
-``cherry-picking`` of features; useful for backporting fixes to maintenance releases.
+Once you have a branch going, you should sync with ``upstream/master``
+regularly, as many commits merge to master every day.
+It is recommended to use ``git rebase`` rather than ``git merge``.

Review comment:
       Should this "recommended" be a bit stronger? 
   
   As I think quite some people are used to a merge-workflow rather than a rebase-workflow (including myself), and my understanding was that we really prefer the rebasing workflow (for reasons that I don't understand ;)).

##########
File path: docs/source/developers/contributing.rst
##########
@@ -124,29 +181,72 @@ To contribute a patch:
   `ARROW-767: [C++] Filesystem abstraction <https://github.com/apache/arrow/pull/4225>`_).
 * Make sure that your code passes the unit tests. You can find instructions how
   to run the unit tests for each Arrow component in its respective README file.
+
+Core developers and others with a stake in the part of the project your change
+affects will review, request changes, and hopefully indicate their approval
+in the end. To make the review process smooth for everyone, try to
+
+* Break your work into small, single-purpose patches if possible. It’s much
+  harder to merge in a large change with a lot of disjoint features, and
+  particularly if you're new to the project, smaller changes are much easier
+  for maintainers to accept.
 * Add new unit tests for your code.
+* Follow the style guides for the part(s) of the project you're modifying.
+  Some languages (C++, Python, and Rust, for example) run a lint check in
+  continuous integration. For all languages, see their respective developer
+  documentation and READMEs for style guidance. In general, try to make it look
+  as if the codebase has a single author, and emulate any conventions you see,
+  whether or not they are officially documented or checked.
+
+When tests are passing and the pull request has been approved by the interested
+parties, a committer will merge the pull request. This is done with a
+command-line utility that does a squash merge, so all of your commits will be
+registered as a single commit to the master branch; this simplifies the
+connection between JIRA issues and commits, and it makes it easier to bisect
+history to identify where changes were introduced. A side effect of this way of
+merging is that your pull request will appear in the GitHub interface to have
+been "closed without merge". Do not be alarmed: if you look at the bottom, you
+will see a message that says "@user closed this in $COMMIT".
+
+Local git conventions
++++++++++++++++++++++
+
+If you are tracking the Arrow source repository locally, here are some tips
+for using ``git``.
+
+All Arrow contributors work off of their personal fork of ``apache/arrow``
+and submit pull requests "upstream". Once you've cloned your fork of Arrow,
+be sure to::
+
+    $ git remote add upstream https://github.com/apache/arrow
+
+to set the "upstream" repository.
+
+You are encouraged to develop on branches, rather than your own "master" branch,
+and it helps to keep your fork's master branch synced with ``upstream/master``.
 
-Thank you in advance for your contributions!
+To start a new branch, pull the latest from upstream first::
 
-Common Git conventions followed within the project
---------------------------------------------------
+   $ git fetch upstream
+   $ git checkout master
+   $ git reset --hard upstream/master

Review comment:
       I typically also do `git pull --ff-only` to update my master branch. 
   But mentioning that you might need `git reset --hard upstream/master` (typically after a release) can be useful, as it is something I always have to look for myself after each release ..




----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org