pitrou commented on a change in pull request #11677: URL: https://github.com/apache/arrow/pull/11677#discussion_r756939383
########## File path: docs/source/developers/guide/communication.rst ########## @@ -0,0 +1,116 @@ +.. Licensed to the Apache Software Foundation (ASF) under one +.. or more contributor license agreements. See the NOTICE file +.. distributed with this work for additional information +.. regarding copyright ownership. The ASF licenses this file +.. to you under the Apache License, Version 2.0 (the +.. "License"); you may not use this file except in compliance +.. with the License. You may obtain a copy of the License at + +.. http://www.apache.org/licenses/LICENSE-2.0 + +.. Unless required by applicable law or agreed to in writing, +.. software distributed under the License is distributed on an +.. "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +.. KIND, either express or implied. See the License for the +.. specific language governing permissions and limitations +.. under the License. + + +.. SCOPE OF THIS SECTION +.. Present Arrow developers to the general public to make +.. the barrier of contributing lower as new contributors will +.. have a feeling of joint work and possible help. Add ways +.. of communication and add description of what is expected. +.. Also add a link to other resources. + + +.. _communication: + +************* +Communication +************* + +**About the contributors** + +The group of contributors is full of experts, software engineers and core +developers but also full of users, learners and enthusiasts that love doing +what we do and we want to spread this enthusiasm to you also. + +We all have silly questions and we all need help lots of times. +We encourage you to be open to communication and we will help as much as +we can. + +Due to the scale of the project which includes many languages, everybody +contributing will be faced with new things needed to be learned. Even the most +seasoned C++ developer will need to ask basic questions about R for example. Review comment: :-D ########## File path: docs/source/developers/guide/communication.rst ########## @@ -0,0 +1,116 @@ +.. Licensed to the Apache Software Foundation (ASF) under one +.. or more contributor license agreements. See the NOTICE file +.. distributed with this work for additional information +.. regarding copyright ownership. The ASF licenses this file +.. to you under the Apache License, Version 2.0 (the +.. "License"); you may not use this file except in compliance +.. with the License. You may obtain a copy of the License at + +.. http://www.apache.org/licenses/LICENSE-2.0 + +.. Unless required by applicable law or agreed to in writing, +.. software distributed under the License is distributed on an +.. "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +.. KIND, either express or implied. See the License for the +.. specific language governing permissions and limitations +.. under the License. + + +.. SCOPE OF THIS SECTION +.. Present Arrow developers to the general public to make +.. the barrier of contributing lower as new contributors will +.. have a feeling of joint work and possible help. Add ways +.. of communication and add description of what is expected. +.. Also add a link to other resources. + + +.. _communication: + +************* +Communication +************* + +**About the contributors** + +The group of contributors is full of experts, software engineers and core +developers but also full of users, learners and enthusiasts that love doing +what we do and we want to spread this enthusiasm to you also. + +We all have silly questions and we all need help lots of times. +We encourage you to be open to communication and we will help as much as +we can. + +Due to the scale of the project which includes many languages, everybody +contributing will be faced with new things needed to be learned. Even the most +seasoned C++ developer will need to ask basic questions about R for example. + +When communicating, it's important you mark your communication with appropriate +tags ([C++], [R], [Ruby] etc.) so it gets noticed by the right people. + +Where to get help 👋 +==================== + +JIRA +~~~~ + +The most used way is to communicate through JIRA. + +When to use JIRA? + +- If you want to **report a bug**. +- If you want to **propose a new feature**. +- If you want to **propose a bigger change in the documentation**. + +In these cases you can create a JIRA issue and connect +with other contributors in the comments. + +.. note:: + How to make a JIRA issue. See `Tips for using JIRA <https://arrow.apache.org/docs/developers/contributing.html#tips-for-using-jira/>`_. + +- If you want to **solve an issue that is already in JIRA**, you should + connect with other contributors in the comments. + +JIRA is used to discuss the problem before the pull request is made (how to start, Review comment: "before a Pull Request is possibly made" (not all JIRAs may lead to a PR) ########## File path: docs/source/developers/guide/introduction.rst ########## @@ -0,0 +1,142 @@ +.. Licensed to the Apache Software Foundation (ASF) under one +.. or more contributor license agreements. See the NOTICE file +.. distributed with this work for additional information +.. regarding copyright ownership. The ASF licenses this file +.. to you under the Apache License, Version 2.0 (the +.. "License"); you may not use this file except in compliance +.. with the License. You may obtain a copy of the License at + +.. http://www.apache.org/licenses/LICENSE-2.0 + +.. Unless required by applicable law or agreed to in writing, +.. software distributed under the License is distributed on an +.. "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +.. KIND, either express or implied. See the License for the +.. specific language governing permissions and limitations +.. under the License. + + +.. SCOPE OF THIS SECTION +.. Make an introduction to the Guide for New Contributors. +.. Add an introduction to the project, why to get involved +.. and a quick checklist of the contributing process. +.. Add the Table of Contents. All detailed explanations +.. should be added as a link in the content. + + +.. _introduction: + +*********************** +New Contributor's Guide +*********************** + +This guide is meant to be a resource for contributing to +`Arrow <https://arrow.apache.org//>`_ for new contributors. + +Starting to contribute to a project like Apache Arrow can look +scary. Taking small steps will help making this tack easier. Review comment: I would rather say "intimidating" rather than "scary". The negative wording can be offputting or worrying. (btw, I don't know what a "tack" is in this context? the explanations I find seem unrelated to software) ########## File path: docs/source/developers/guide/communication.rst ########## @@ -0,0 +1,116 @@ +.. Licensed to the Apache Software Foundation (ASF) under one +.. or more contributor license agreements. See the NOTICE file +.. distributed with this work for additional information +.. regarding copyright ownership. The ASF licenses this file +.. to you under the Apache License, Version 2.0 (the +.. "License"); you may not use this file except in compliance +.. with the License. You may obtain a copy of the License at + +.. http://www.apache.org/licenses/LICENSE-2.0 + +.. Unless required by applicable law or agreed to in writing, +.. software distributed under the License is distributed on an +.. "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +.. KIND, either express or implied. See the License for the +.. specific language governing permissions and limitations +.. under the License. + + +.. SCOPE OF THIS SECTION +.. Present Arrow developers to the general public to make +.. the barrier of contributing lower as new contributors will +.. have a feeling of joint work and possible help. Add ways +.. of communication and add description of what is expected. +.. Also add a link to other resources. + + +.. _communication: + +************* +Communication +************* + +**About the contributors** + +The group of contributors is full of experts, software engineers and core +developers but also full of users, learners and enthusiasts that love doing +what we do and we want to spread this enthusiasm to you also. + +We all have silly questions and we all need help lots of times. +We encourage you to be open to communication and we will help as much as +we can. + +Due to the scale of the project which includes many languages, everybody +contributing will be faced with new things needed to be learned. Even the most +seasoned C++ developer will need to ask basic questions about R for example. + +When communicating, it's important you mark your communication with appropriate +tags ([C++], [R], [Ruby] etc.) so it gets noticed by the right people. + +Where to get help 👋 +==================== + +JIRA +~~~~ + +The most used way is to communicate through JIRA. + +When to use JIRA? + +- If you want to **report a bug**. +- If you want to **propose a new feature**. +- If you want to **propose a bigger change in the documentation**. + +In these cases you can create a JIRA issue and connect +with other contributors in the comments. + +.. note:: + How to make a JIRA issue. See `Tips for using JIRA <https://arrow.apache.org/docs/developers/contributing.html#tips-for-using-jira/>`_. + +- If you want to **solve an issue that is already in JIRA**, you should + connect with other contributors in the comments. + +JIRA is used to discuss the problem before the pull request is made (how to start, +where to search for the solution, etc..). + +GitHub +~~~~~~ + +Further options of communicating are provided through GitHub. + +When to use GitHub? + +- **For any question you may have or problems you are facing, you can make an issue on GutHub.** +- If you have **a problem with the build**, you can make an issue on GitHub Review comment: In this context, it's not obvious what "the build" is. Perhaps "a problem building one of the Arrow libraries"? ########## File path: docs/source/developers/guide/communication.rst ########## @@ -0,0 +1,116 @@ +.. Licensed to the Apache Software Foundation (ASF) under one +.. or more contributor license agreements. See the NOTICE file +.. distributed with this work for additional information +.. regarding copyright ownership. The ASF licenses this file +.. to you under the Apache License, Version 2.0 (the +.. "License"); you may not use this file except in compliance +.. with the License. You may obtain a copy of the License at + +.. http://www.apache.org/licenses/LICENSE-2.0 + +.. Unless required by applicable law or agreed to in writing, +.. software distributed under the License is distributed on an +.. "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +.. KIND, either express or implied. See the License for the +.. specific language governing permissions and limitations +.. under the License. + + +.. SCOPE OF THIS SECTION +.. Present Arrow developers to the general public to make +.. the barrier of contributing lower as new contributors will +.. have a feeling of joint work and possible help. Add ways +.. of communication and add description of what is expected. +.. Also add a link to other resources. + + +.. _communication: + +************* +Communication +************* + +**About the contributors** + +The group of contributors is full of experts, software engineers and core +developers but also full of users, learners and enthusiasts that love doing +what we do and we want to spread this enthusiasm to you also. + +We all have silly questions and we all need help lots of times. +We encourage you to be open to communication and we will help as much as +we can. + +Due to the scale of the project which includes many languages, everybody +contributing will be faced with new things needed to be learned. Even the most +seasoned C++ developer will need to ask basic questions about R for example. + +When communicating, it's important you mark your communication with appropriate +tags ([C++], [R], [Ruby] etc.) so it gets noticed by the right people. + +Where to get help 👋 +==================== + +JIRA +~~~~ + +The most used way is to communicate through JIRA. + +When to use JIRA? + +- If you want to **report a bug**. +- If you want to **propose a new feature**. +- If you want to **propose a bigger change in the documentation**. + +In these cases you can create a JIRA issue and connect +with other contributors in the comments. + +.. note:: + How to make a JIRA issue. See `Tips for using JIRA <https://arrow.apache.org/docs/developers/contributing.html#tips-for-using-jira/>`_. + +- If you want to **solve an issue that is already in JIRA**, you should + connect with other contributors in the comments. + +JIRA is used to discuss the problem before the pull request is made (how to start, +where to search for the solution, etc..). + +GitHub +~~~~~~ + +Further options of communicating are provided through GitHub. + +When to use GitHub? + +- **For any question you may have or problems you are facing, you can make an issue on GutHub.** Review comment: Also "GitHub" not "GutHub" ;-) ########## File path: docs/source/developers/guide/step_by_step/pr_and_github.rst ########## @@ -0,0 +1,37 @@ +.. Licensed to the Apache Software Foundation (ASF) under one +.. or more contributor license agreements. See the NOTICE file +.. distributed with this work for additional information +.. regarding copyright ownership. The ASF licenses this file +.. to you under the Apache License, Version 2.0 (the +.. "License"); you may not use this file except in compliance +.. with the License. You may obtain a copy of the License at + +.. http://www.apache.org/licenses/LICENSE-2.0 + +.. Unless required by applicable law or agreed to in writing, +.. software distributed under the License is distributed on an +.. "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +.. KIND, either express or implied. See the License for the +.. specific language governing permissions and limitations +.. under the License. + + +.. SCOPE OF THIS SECTION +.. This section should include all steps in making a pull +.. request (until it is merged) on Arrow GitHub repository +.. using git. + + +.. _pr_and_github: + +**************************** +Life cycle of a Pull Request +**************************** + + +Making the PR 🙀 Review comment: "Opening a PR" or "Creating a PR"? ########## File path: docs/source/developers/guide/introduction.rst ########## @@ -0,0 +1,142 @@ +.. Licensed to the Apache Software Foundation (ASF) under one +.. or more contributor license agreements. See the NOTICE file +.. distributed with this work for additional information +.. regarding copyright ownership. The ASF licenses this file +.. to you under the Apache License, Version 2.0 (the +.. "License"); you may not use this file except in compliance +.. with the License. You may obtain a copy of the License at + +.. http://www.apache.org/licenses/LICENSE-2.0 + +.. Unless required by applicable law or agreed to in writing, +.. software distributed under the License is distributed on an +.. "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +.. KIND, either express or implied. See the License for the +.. specific language governing permissions and limitations +.. under the License. + + +.. SCOPE OF THIS SECTION +.. Make an introduction to the Guide for New Contributors. +.. Add an introduction to the project, why to get involved +.. and a quick checklist of the contributing process. +.. Add the Table of Contents. All detailed explanations +.. should be added as a link in the content. + + +.. _introduction: + +*********************** +New Contributor's Guide +*********************** + +This guide is meant to be a resource for contributing to +`Arrow <https://arrow.apache.org//>`_ for new contributors. + +Starting to contribute to a project like Apache Arrow can look +scary. Taking small steps will help making this tack easier. + + +Why contribute to Arrow? +======================== +There can be various reasons why someone would want to contribute +to Arrow: + +* You find the project interesting and would like to try making + a contribution to learn more about the library and grow your skills. + +* You use Arrow in the project you are working on and you would like + to make a new feature or fix a bug yourself. + +Read more about the project in the :ref:`about_arrow` section. + +Quick Reference +=============== + +Here are the basic steps needed to get set up and contribute to Arrow. +This is meant as a checklist and also to have an overall picture. + +For complete instructions please follow :ref:`step_by_step` (a +step-by-step guide) or R and Python :ref:`tutorial-index` for an example +of adding a basic feature. + + +#. **Install and set up Git, fork the Arrow repository** + + See detailed instructions on how to :ref:`set-up` Git and fork the + Arrow repository. + +#. **Build Arrow** + + This can be quite easy or a real blocker. Be prepared to dig through the + additional flags for cmake in the C++ build guide and read the doc carefully + to not miss any suggestions already given there. Anytime you are stuck, + reach out to us via appropriate :ref:`communication` channel. + + See detailed instructions on how to :ref:`build-arrow`. + +#. **Run the tests** + + Run the tests from a terminal for Python + + .. code-block:: + + $ pytest pyarrow + + or R + + .. code-block:: + + $ devtools::test() Review comment: By the way, if I run `devtools::test()` from a bash prompt, I don't think it will work, will it? ########## File path: docs/source/developers/guide/communication.rst ########## @@ -0,0 +1,116 @@ +.. Licensed to the Apache Software Foundation (ASF) under one +.. or more contributor license agreements. See the NOTICE file +.. distributed with this work for additional information +.. regarding copyright ownership. The ASF licenses this file +.. to you under the Apache License, Version 2.0 (the +.. "License"); you may not use this file except in compliance +.. with the License. You may obtain a copy of the License at + +.. http://www.apache.org/licenses/LICENSE-2.0 + +.. Unless required by applicable law or agreed to in writing, +.. software distributed under the License is distributed on an +.. "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +.. KIND, either express or implied. See the License for the +.. specific language governing permissions and limitations +.. under the License. + + +.. SCOPE OF THIS SECTION +.. Present Arrow developers to the general public to make +.. the barrier of contributing lower as new contributors will +.. have a feeling of joint work and possible help. Add ways +.. of communication and add description of what is expected. +.. Also add a link to other resources. + + +.. _communication: + +************* +Communication +************* + +**About the contributors** + +The group of contributors is full of experts, software engineers and core +developers but also full of users, learners and enthusiasts that love doing +what we do and we want to spread this enthusiasm to you also. + +We all have silly questions and we all need help lots of times. +We encourage you to be open to communication and we will help as much as +we can. + +Due to the scale of the project which includes many languages, everybody +contributing will be faced with new things needed to be learned. Even the most +seasoned C++ developer will need to ask basic questions about R for example. + +When communicating, it's important you mark your communication with appropriate +tags ([C++], [R], [Ruby] etc.) so it gets noticed by the right people. + +Where to get help 👋 +==================== + +JIRA +~~~~ + +The most used way is to communicate through JIRA. + +When to use JIRA? + +- If you want to **report a bug**. +- If you want to **propose a new feature**. +- If you want to **propose a bigger change in the documentation**. + +In these cases you can create a JIRA issue and connect +with other contributors in the comments. + +.. note:: + How to make a JIRA issue. See `Tips for using JIRA <https://arrow.apache.org/docs/developers/contributing.html#tips-for-using-jira/>`_. + +- If you want to **solve an issue that is already in JIRA**, you should + connect with other contributors in the comments. + +JIRA is used to discuss the problem before the pull request is made (how to start, +where to search for the solution, etc..). + +GitHub +~~~~~~ + +Further options of communicating are provided through GitHub. + +When to use GitHub? + +- **For any question you may have or problems you are facing, you can make an issue on GutHub.** +- If you have **a problem with the build**, you can make an issue on GitHub + and discuss the possible solution (or write to the user mailing list). + + Making an issue about things you are not sure about may feel intimidating, + but it is also useful for others and the project. + + .. warning:: Review comment: Nit: a warning is a bit intimidating for this, just make it a note? ########## File path: docs/source/developers/guide/documentation.rst ########## @@ -0,0 +1,30 @@ +.. Licensed to the Apache Software Foundation (ASF) under one +.. or more contributor license agreements. See the NOTICE file +.. distributed with this work for additional information +.. regarding copyright ownership. The ASF licenses this file +.. to you under the Apache License, Version 2.0 (the +.. "License"); you may not use this file except in compliance +.. with the License. You may obtain a copy of the License at + +.. http://www.apache.org/licenses/LICENSE-2.0 + +.. Unless required by applicable law or agreed to in writing, +.. software distributed under the License is distributed on an +.. "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +.. KIND, either express or implied. See the License for the +.. specific language governing permissions and limitations +.. under the License. + + +.. SCOPE OF THIS SECTION +.. To expose that help with existing documentation is a +.. very good way to start and also a very important part of +.. the project! If possible add summary of the structure of +.. the existing documentation, including different Cookbooks. + + +.. _documentation: + +************************** +Helping with documentation +************************** Review comment: What is the plan for filling this page? Depending on what we add to this page we may also want to move it to the upper "developers" section. ########## File path: docs/source/developers/guide/communication.rst ########## @@ -0,0 +1,116 @@ +.. Licensed to the Apache Software Foundation (ASF) under one +.. or more contributor license agreements. See the NOTICE file +.. distributed with this work for additional information +.. regarding copyright ownership. The ASF licenses this file +.. to you under the Apache License, Version 2.0 (the +.. "License"); you may not use this file except in compliance +.. with the License. You may obtain a copy of the License at + +.. http://www.apache.org/licenses/LICENSE-2.0 + +.. Unless required by applicable law or agreed to in writing, +.. software distributed under the License is distributed on an +.. "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +.. KIND, either express or implied. See the License for the +.. specific language governing permissions and limitations +.. under the License. + + +.. SCOPE OF THIS SECTION +.. Present Arrow developers to the general public to make +.. the barrier of contributing lower as new contributors will +.. have a feeling of joint work and possible help. Add ways +.. of communication and add description of what is expected. +.. Also add a link to other resources. + + +.. _communication: + +************* +Communication +************* + +**About the contributors** + +The group of contributors is full of experts, software engineers and core +developers but also full of users, learners and enthusiasts that love doing +what we do and we want to spread this enthusiasm to you also. + +We all have silly questions and we all need help lots of times. +We encourage you to be open to communication and we will help as much as +we can. + +Due to the scale of the project which includes many languages, everybody +contributing will be faced with new things needed to be learned. Even the most +seasoned C++ developer will need to ask basic questions about R for example. + +When communicating, it's important you mark your communication with appropriate +tags ([C++], [R], [Ruby] etc.) so it gets noticed by the right people. + +Where to get help 👋 +==================== + +JIRA +~~~~ + +The most used way is to communicate through JIRA. + +When to use JIRA? + +- If you want to **report a bug**. +- If you want to **propose a new feature**. +- If you want to **propose a bigger change in the documentation**. + +In these cases you can create a JIRA issue and connect +with other contributors in the comments. + +.. note:: + How to make a JIRA issue. See `Tips for using JIRA <https://arrow.apache.org/docs/developers/contributing.html#tips-for-using-jira/>`_. + +- If you want to **solve an issue that is already in JIRA**, you should + connect with other contributors in the comments. Review comment: "in the issue comments"? ########## File path: docs/source/developers/guide/communication.rst ########## @@ -0,0 +1,116 @@ +.. Licensed to the Apache Software Foundation (ASF) under one +.. or more contributor license agreements. See the NOTICE file +.. distributed with this work for additional information +.. regarding copyright ownership. The ASF licenses this file +.. to you under the Apache License, Version 2.0 (the +.. "License"); you may not use this file except in compliance +.. with the License. You may obtain a copy of the License at + +.. http://www.apache.org/licenses/LICENSE-2.0 + +.. Unless required by applicable law or agreed to in writing, +.. software distributed under the License is distributed on an +.. "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +.. KIND, either express or implied. See the License for the +.. specific language governing permissions and limitations +.. under the License. + + +.. SCOPE OF THIS SECTION +.. Present Arrow developers to the general public to make +.. the barrier of contributing lower as new contributors will +.. have a feeling of joint work and possible help. Add ways +.. of communication and add description of what is expected. +.. Also add a link to other resources. + + +.. _communication: + +************* +Communication +************* + +**About the contributors** + +The group of contributors is full of experts, software engineers and core +developers but also full of users, learners and enthusiasts that love doing +what we do and we want to spread this enthusiasm to you also. + +We all have silly questions and we all need help lots of times. +We encourage you to be open to communication and we will help as much as +we can. + +Due to the scale of the project which includes many languages, everybody +contributing will be faced with new things needed to be learned. Even the most +seasoned C++ developer will need to ask basic questions about R for example. + +When communicating, it's important you mark your communication with appropriate +tags ([C++], [R], [Ruby] etc.) so it gets noticed by the right people. + +Where to get help 👋 +==================== + +JIRA +~~~~ + +The most used way is to communicate through JIRA. + +When to use JIRA? + +- If you want to **report a bug**. +- If you want to **propose a new feature**. +- If you want to **propose a bigger change in the documentation**. + +In these cases you can create a JIRA issue and connect +with other contributors in the comments. + +.. note:: Review comment: Nit: I would make it a "seealso": https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-seealso ########## File path: docs/source/developers/guide/communication.rst ########## @@ -0,0 +1,116 @@ +.. Licensed to the Apache Software Foundation (ASF) under one +.. or more contributor license agreements. See the NOTICE file +.. distributed with this work for additional information +.. regarding copyright ownership. The ASF licenses this file +.. to you under the Apache License, Version 2.0 (the +.. "License"); you may not use this file except in compliance +.. with the License. You may obtain a copy of the License at + +.. http://www.apache.org/licenses/LICENSE-2.0 + +.. Unless required by applicable law or agreed to in writing, +.. software distributed under the License is distributed on an +.. "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +.. KIND, either express or implied. See the License for the +.. specific language governing permissions and limitations +.. under the License. + + +.. SCOPE OF THIS SECTION +.. Present Arrow developers to the general public to make +.. the barrier of contributing lower as new contributors will +.. have a feeling of joint work and possible help. Add ways +.. of communication and add description of what is expected. +.. Also add a link to other resources. + + +.. _communication: + +************* +Communication +************* + +**About the contributors** + +The group of contributors is full of experts, software engineers and core +developers but also full of users, learners and enthusiasts that love doing +what we do and we want to spread this enthusiasm to you also. + +We all have silly questions and we all need help lots of times. +We encourage you to be open to communication and we will help as much as +we can. + +Due to the scale of the project which includes many languages, everybody +contributing will be faced with new things needed to be learned. Even the most +seasoned C++ developer will need to ask basic questions about R for example. + +When communicating, it's important you mark your communication with appropriate +tags ([C++], [R], [Ruby] etc.) so it gets noticed by the right people. + +Where to get help 👋 +==================== + +JIRA +~~~~ + +The most used way is to communicate through JIRA. + +When to use JIRA? + +- If you want to **report a bug**. +- If you want to **propose a new feature**. +- If you want to **propose a bigger change in the documentation**. + +In these cases you can create a JIRA issue and connect +with other contributors in the comments. Review comment: "in the issue comments", perhaps? ########## File path: docs/source/developers/guide/communication.rst ########## @@ -0,0 +1,116 @@ +.. Licensed to the Apache Software Foundation (ASF) under one +.. or more contributor license agreements. See the NOTICE file +.. distributed with this work for additional information +.. regarding copyright ownership. The ASF licenses this file +.. to you under the Apache License, Version 2.0 (the +.. "License"); you may not use this file except in compliance +.. with the License. You may obtain a copy of the License at + +.. http://www.apache.org/licenses/LICENSE-2.0 + +.. Unless required by applicable law or agreed to in writing, +.. software distributed under the License is distributed on an +.. "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +.. KIND, either express or implied. See the License for the +.. specific language governing permissions and limitations +.. under the License. + + +.. SCOPE OF THIS SECTION +.. Present Arrow developers to the general public to make +.. the barrier of contributing lower as new contributors will +.. have a feeling of joint work and possible help. Add ways +.. of communication and add description of what is expected. +.. Also add a link to other resources. + + +.. _communication: + +************* +Communication +************* + +**About the contributors** + +The group of contributors is full of experts, software engineers and core +developers but also full of users, learners and enthusiasts that love doing +what we do and we want to spread this enthusiasm to you also. + +We all have silly questions and we all need help lots of times. +We encourage you to be open to communication and we will help as much as +we can. + +Due to the scale of the project which includes many languages, everybody +contributing will be faced with new things needed to be learned. Even the most +seasoned C++ developer will need to ask basic questions about R for example. + +When communicating, it's important you mark your communication with appropriate +tags ([C++], [R], [Ruby] etc.) so it gets noticed by the right people. + +Where to get help 👋 +==================== + +JIRA +~~~~ + +The most used way is to communicate through JIRA. + +When to use JIRA? + +- If you want to **report a bug**. +- If you want to **propose a new feature**. +- If you want to **propose a bigger change in the documentation**. + +In these cases you can create a JIRA issue and connect +with other contributors in the comments. + +.. note:: + How to make a JIRA issue. See `Tips for using JIRA <https://arrow.apache.org/docs/developers/contributing.html#tips-for-using-jira/>`_. + +- If you want to **solve an issue that is already in JIRA**, you should + connect with other contributors in the comments. + +JIRA is used to discuss the problem before the pull request is made (how to start, +where to search for the solution, etc..). + +GitHub +~~~~~~ + +Further options of communicating are provided through GitHub. + +When to use GitHub? + +- **For any question you may have or problems you are facing, you can make an issue on GutHub.** Review comment: This is true, though IMHO we'd rather have people write to the mailing-list if they're comfortable with it. I think most committers never GitHub issues, they only notice about them when they are pinged explicitly. ########## File path: docs/source/developers/guide/communication.rst ########## @@ -0,0 +1,116 @@ +.. Licensed to the Apache Software Foundation (ASF) under one +.. or more contributor license agreements. See the NOTICE file +.. distributed with this work for additional information +.. regarding copyright ownership. The ASF licenses this file +.. to you under the Apache License, Version 2.0 (the +.. "License"); you may not use this file except in compliance +.. with the License. You may obtain a copy of the License at + +.. http://www.apache.org/licenses/LICENSE-2.0 + +.. Unless required by applicable law or agreed to in writing, +.. software distributed under the License is distributed on an +.. "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +.. KIND, either express or implied. See the License for the +.. specific language governing permissions and limitations +.. under the License. + + +.. SCOPE OF THIS SECTION +.. Present Arrow developers to the general public to make +.. the barrier of contributing lower as new contributors will +.. have a feeling of joint work and possible help. Add ways +.. of communication and add description of what is expected. +.. Also add a link to other resources. + + +.. _communication: + +************* +Communication +************* + +**About the contributors** + +The group of contributors is full of experts, software engineers and core +developers but also full of users, learners and enthusiasts that love doing +what we do and we want to spread this enthusiasm to you also. + +We all have silly questions and we all need help lots of times. +We encourage you to be open to communication and we will help as much as +we can. + +Due to the scale of the project which includes many languages, everybody +contributing will be faced with new things needed to be learned. Even the most +seasoned C++ developer will need to ask basic questions about R for example. + +When communicating, it's important you mark your communication with appropriate +tags ([C++], [R], [Ruby] etc.) so it gets noticed by the right people. + +Where to get help 👋 +==================== + +JIRA +~~~~ + +The most used way is to communicate through JIRA. + +When to use JIRA? + +- If you want to **report a bug**. +- If you want to **propose a new feature**. +- If you want to **propose a bigger change in the documentation**. + +In these cases you can create a JIRA issue and connect +with other contributors in the comments. + +.. note:: + How to make a JIRA issue. See `Tips for using JIRA <https://arrow.apache.org/docs/developers/contributing.html#tips-for-using-jira/>`_. + +- If you want to **solve an issue that is already in JIRA**, you should + connect with other contributors in the comments. + +JIRA is used to discuss the problem before the pull request is made (how to start, +where to search for the solution, etc..). + +GitHub +~~~~~~ + +Further options of communicating are provided through GitHub. Review comment: "Through GitHub" is a bit vague, because it has issues, PRs and possibly other channels. Would you like to qualify this a bit more? ########## File path: docs/source/developers/guide/introduction.rst ########## @@ -0,0 +1,142 @@ +.. Licensed to the Apache Software Foundation (ASF) under one +.. or more contributor license agreements. See the NOTICE file +.. distributed with this work for additional information +.. regarding copyright ownership. The ASF licenses this file +.. to you under the Apache License, Version 2.0 (the +.. "License"); you may not use this file except in compliance +.. with the License. You may obtain a copy of the License at + +.. http://www.apache.org/licenses/LICENSE-2.0 + +.. Unless required by applicable law or agreed to in writing, +.. software distributed under the License is distributed on an +.. "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +.. KIND, either express or implied. See the License for the +.. specific language governing permissions and limitations +.. under the License. + + +.. SCOPE OF THIS SECTION +.. Make an introduction to the Guide for New Contributors. +.. Add an introduction to the project, why to get involved +.. and a quick checklist of the contributing process. +.. Add the Table of Contents. All detailed explanations +.. should be added as a link in the content. + + +.. _introduction: + +*********************** +New Contributor's Guide +*********************** + +This guide is meant to be a resource for contributing to +`Arrow <https://arrow.apache.org//>`_ for new contributors. + +Starting to contribute to a project like Apache Arrow can look +scary. Taking small steps will help making this tack easier. + + +Why contribute to Arrow? +======================== +There can be various reasons why someone would want to contribute +to Arrow: + +* You find the project interesting and would like to try making + a contribution to learn more about the library and grow your skills. + +* You use Arrow in the project you are working on and you would like + to make a new feature or fix a bug yourself. + +Read more about the project in the :ref:`about_arrow` section. + +Quick Reference +=============== + +Here are the basic steps needed to get set up and contribute to Arrow. +This is meant as a checklist and also to have an overall picture. + +For complete instructions please follow :ref:`step_by_step` (a +step-by-step guide) or R and Python :ref:`tutorial-index` for an example +of adding a basic feature. + + +#. **Install and set up Git, fork the Arrow repository** + + See detailed instructions on how to :ref:`set-up` Git and fork the + Arrow repository. + +#. **Build Arrow** + + This can be quite easy or a real blocker. Be prepared to dig through the + additional flags for cmake in the C++ build guide and read the doc carefully + to not miss any suggestions already given there. Anytime you are stuck, + reach out to us via appropriate :ref:`communication` channel. + + See detailed instructions on how to :ref:`build-arrow`. + +#. **Run the tests** + + Run the tests from a terminal for Python + + .. code-block:: + + $ pytest pyarrow + + or R + + .. code-block:: + + $ devtools::test() Review comment: Are there other documentation sections expanding on this? If so, perhaps link to them as well? ########## File path: docs/source/developers/guide/introduction.rst ########## @@ -0,0 +1,142 @@ +.. Licensed to the Apache Software Foundation (ASF) under one +.. or more contributor license agreements. See the NOTICE file +.. distributed with this work for additional information +.. regarding copyright ownership. The ASF licenses this file +.. to you under the Apache License, Version 2.0 (the +.. "License"); you may not use this file except in compliance +.. with the License. You may obtain a copy of the License at + +.. http://www.apache.org/licenses/LICENSE-2.0 + +.. Unless required by applicable law or agreed to in writing, +.. software distributed under the License is distributed on an +.. "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +.. KIND, either express or implied. See the License for the +.. specific language governing permissions and limitations +.. under the License. + + +.. SCOPE OF THIS SECTION +.. Make an introduction to the Guide for New Contributors. +.. Add an introduction to the project, why to get involved +.. and a quick checklist of the contributing process. +.. Add the Table of Contents. All detailed explanations +.. should be added as a link in the content. + + +.. _introduction: + +*********************** +New Contributor's Guide +*********************** + +This guide is meant to be a resource for contributing to +`Arrow <https://arrow.apache.org//>`_ for new contributors. + +Starting to contribute to a project like Apache Arrow can look +scary. Taking small steps will help making this tack easier. + + +Why contribute to Arrow? +======================== +There can be various reasons why someone would want to contribute +to Arrow: + +* You find the project interesting and would like to try making + a contribution to learn more about the library and grow your skills. + +* You use Arrow in the project you are working on and you would like + to make a new feature or fix a bug yourself. + +Read more about the project in the :ref:`about_arrow` section. + +Quick Reference +=============== + +Here are the basic steps needed to get set up and contribute to Arrow. +This is meant as a checklist and also to have an overall picture. + +For complete instructions please follow :ref:`step_by_step` (a +step-by-step guide) or R and Python :ref:`tutorial-index` for an example +of adding a basic feature. + + +#. **Install and set up Git, fork the Arrow repository** + + See detailed instructions on how to :ref:`set-up` Git and fork the + Arrow repository. + +#. **Build Arrow** + + This can be quite easy or a real blocker. Be prepared to dig through the + additional flags for cmake in the C++ build guide and read the doc carefully + to not miss any suggestions already given there. Anytime you are stuck, Review comment: Again, I fear this language may be demotivating. How about making the language more neutral, something like: > Arrow libraries include a wide range of functionalities and may require the installation of third-party packages, depending on which build options and components you enable. For example, the C++ build guide has suggestions for whenever you are experiencing difficulties, be sure to read them. Anytime you are stuck, feel free to reach out ... ########## File path: docs/source/developers/guide/about_arrow.rst ########## @@ -0,0 +1,37 @@ +.. Licensed to the Apache Software Foundation (ASF) under one +.. or more contributor license agreements. See the NOTICE file +.. distributed with this work for additional information +.. regarding copyright ownership. The ASF licenses this file +.. to you under the Apache License, Version 2.0 (the +.. "License"); you may not use this file except in compliance +.. with the License. You may obtain a copy of the License at + +.. http://www.apache.org/licenses/LICENSE-2.0 + +.. Unless required by applicable law or agreed to in writing, +.. software distributed under the License is distributed on an +.. "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +.. KIND, either express or implied. See the License for the +.. specific language governing permissions and limitations +.. under the License. + + +.. SCOPE OF THIS SECTION +.. This section should include basic information +.. about the Arrow project. If possible the content should be +.. written in words easy understandable to beginner notß +.. necessary acquainted with the library and the technical +.. details. + +.. _about_arrow: + +*********** +About Arrow +*********** + +General overview. TODO Review comment: I think an "About Arrow" page (if we need one) would not live in the developers section but rather at the top level. ########## File path: docs/source/developers/guide/introduction.rst ########## @@ -0,0 +1,142 @@ +.. Licensed to the Apache Software Foundation (ASF) under one +.. or more contributor license agreements. See the NOTICE file +.. distributed with this work for additional information +.. regarding copyright ownership. The ASF licenses this file +.. to you under the Apache License, Version 2.0 (the +.. "License"); you may not use this file except in compliance +.. with the License. You may obtain a copy of the License at + +.. http://www.apache.org/licenses/LICENSE-2.0 + +.. Unless required by applicable law or agreed to in writing, +.. software distributed under the License is distributed on an +.. "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +.. KIND, either express or implied. See the License for the +.. specific language governing permissions and limitations +.. under the License. + + +.. SCOPE OF THIS SECTION +.. Make an introduction to the Guide for New Contributors. +.. Add an introduction to the project, why to get involved +.. and a quick checklist of the contributing process. +.. Add the Table of Contents. All detailed explanations +.. should be added as a link in the content. + + +.. _introduction: + +*********************** +New Contributor's Guide +*********************** + +This guide is meant to be a resource for contributing to +`Arrow <https://arrow.apache.org//>`_ for new contributors. + +Starting to contribute to a project like Apache Arrow can look +scary. Taking small steps will help making this tack easier. + + +Why contribute to Arrow? +======================== +There can be various reasons why someone would want to contribute +to Arrow: + +* You find the project interesting and would like to try making + a contribution to learn more about the library and grow your skills. + +* You use Arrow in the project you are working on and you would like + to make a new feature or fix a bug yourself. + +Read more about the project in the :ref:`about_arrow` section. + +Quick Reference +=============== + +Here are the basic steps needed to get set up and contribute to Arrow. +This is meant as a checklist and also to have an overall picture. + +For complete instructions please follow :ref:`step_by_step` (a +step-by-step guide) or R and Python :ref:`tutorial-index` for an example +of adding a basic feature. + + +#. **Install and set up Git, fork the Arrow repository** + + See detailed instructions on how to :ref:`set-up` Git and fork the + Arrow repository. + +#. **Build Arrow** + + This can be quite easy or a real blocker. Be prepared to dig through the + additional flags for cmake in the C++ build guide and read the doc carefully + to not miss any suggestions already given there. Anytime you are stuck, + reach out to us via appropriate :ref:`communication` channel. + + See detailed instructions on how to :ref:`build-arrow`. Review comment: One general question: is this guide mostly for contributing to the R, Python and C++ parts? When it is the case, it should probably be stated at the beginning of the relevant section rather than remain implicit. (there are also other implementations in the repository: Java, C#, Go...) ########## File path: docs/source/developers/guide/introduction.rst ########## @@ -0,0 +1,142 @@ +.. Licensed to the Apache Software Foundation (ASF) under one +.. or more contributor license agreements. See the NOTICE file +.. distributed with this work for additional information +.. regarding copyright ownership. The ASF licenses this file +.. to you under the Apache License, Version 2.0 (the +.. "License"); you may not use this file except in compliance +.. with the License. You may obtain a copy of the License at + +.. http://www.apache.org/licenses/LICENSE-2.0 + +.. Unless required by applicable law or agreed to in writing, +.. software distributed under the License is distributed on an +.. "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +.. KIND, either express or implied. See the License for the +.. specific language governing permissions and limitations +.. under the License. + + +.. SCOPE OF THIS SECTION +.. Make an introduction to the Guide for New Contributors. +.. Add an introduction to the project, why to get involved +.. and a quick checklist of the contributing process. +.. Add the Table of Contents. All detailed explanations +.. should be added as a link in the content. + + +.. _introduction: + +*********************** +New Contributor's Guide +*********************** + +This guide is meant to be a resource for contributing to +`Arrow <https://arrow.apache.org//>`_ for new contributors. + +Starting to contribute to a project like Apache Arrow can look +scary. Taking small steps will help making this tack easier. + + +Why contribute to Arrow? +======================== +There can be various reasons why someone would want to contribute +to Arrow: + +* You find the project interesting and would like to try making + a contribution to learn more about the library and grow your skills. + +* You use Arrow in the project you are working on and you would like + to make a new feature or fix a bug yourself. + +Read more about the project in the :ref:`about_arrow` section. + +Quick Reference +=============== + +Here are the basic steps needed to get set up and contribute to Arrow. +This is meant as a checklist and also to have an overall picture. + +For complete instructions please follow :ref:`step_by_step` (a +step-by-step guide) or R and Python :ref:`tutorial-index` for an example +of adding a basic feature. + + +#. **Install and set up Git, fork the Arrow repository** + + See detailed instructions on how to :ref:`set-up` Git and fork the + Arrow repository. + +#. **Build Arrow** + + This can be quite easy or a real blocker. Be prepared to dig through the + additional flags for cmake in the C++ build guide and read the doc carefully + to not miss any suggestions already given there. Anytime you are stuck, + reach out to us via appropriate :ref:`communication` channel. + + See detailed instructions on how to :ref:`build-arrow`. + +#. **Run the tests** + + Run the tests from a terminal for Python + + .. code-block:: + + $ pytest pyarrow + + or R + + .. code-block:: + + $ devtools::test() + +#. **Find an issue, create a new branch and work on the problem** + + **Finding an issue** + + Not so easy, we agree. + Read through the :ref:`finding-issues` section to get some ideas. + + **Finding your way through the project** + + The first step when starting a new project is the hardest. We wrote some + help guides that we used when we were looking for solutions and we hope + they will help. + + Read through :ref:`solving` section. + + **Communication** + + Communication is very important. You may need some help solving the problem + (happening to developers all the time). Also, when you have an issue you want + to solve it is advisable to let the team know you are working on it and may + need some help. + + See possible channels of :ref:`communication`. + +#. **Once you found the solution, write and run the test** + + See detailed instructions on how to do the :ref:`testing`. Review comment: "on how to test", perhaps? ########## File path: docs/source/developers/guide/introduction.rst ########## @@ -0,0 +1,142 @@ +.. Licensed to the Apache Software Foundation (ASF) under one +.. or more contributor license agreements. See the NOTICE file +.. distributed with this work for additional information +.. regarding copyright ownership. The ASF licenses this file +.. to you under the Apache License, Version 2.0 (the +.. "License"); you may not use this file except in compliance +.. with the License. You may obtain a copy of the License at + +.. http://www.apache.org/licenses/LICENSE-2.0 + +.. Unless required by applicable law or agreed to in writing, +.. software distributed under the License is distributed on an +.. "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +.. KIND, either express or implied. See the License for the +.. specific language governing permissions and limitations +.. under the License. + + +.. SCOPE OF THIS SECTION +.. Make an introduction to the Guide for New Contributors. +.. Add an introduction to the project, why to get involved +.. and a quick checklist of the contributing process. +.. Add the Table of Contents. All detailed explanations +.. should be added as a link in the content. + + +.. _introduction: + +*********************** +New Contributor's Guide +*********************** + +This guide is meant to be a resource for contributing to +`Arrow <https://arrow.apache.org//>`_ for new contributors. + +Starting to contribute to a project like Apache Arrow can look +scary. Taking small steps will help making this tack easier. + + +Why contribute to Arrow? +======================== +There can be various reasons why someone would want to contribute +to Arrow: + +* You find the project interesting and would like to try making + a contribution to learn more about the library and grow your skills. + +* You use Arrow in the project you are working on and you would like + to make a new feature or fix a bug yourself. + +Read more about the project in the :ref:`about_arrow` section. + +Quick Reference +=============== + +Here are the basic steps needed to get set up and contribute to Arrow. +This is meant as a checklist and also to have an overall picture. + +For complete instructions please follow :ref:`step_by_step` (a +step-by-step guide) or R and Python :ref:`tutorial-index` for an example +of adding a basic feature. + + +#. **Install and set up Git, fork the Arrow repository** + + See detailed instructions on how to :ref:`set-up` Git and fork the + Arrow repository. + +#. **Build Arrow** + + This can be quite easy or a real blocker. Be prepared to dig through the + additional flags for cmake in the C++ build guide and read the doc carefully + to not miss any suggestions already given there. Anytime you are stuck, + reach out to us via appropriate :ref:`communication` channel. + + See detailed instructions on how to :ref:`build-arrow`. + +#. **Run the tests** + + Run the tests from a terminal for Python + + .. code-block:: + + $ pytest pyarrow + + or R + + .. code-block:: + + $ devtools::test() + +#. **Find an issue, create a new branch and work on the problem** + + **Finding an issue** + + Not so easy, we agree. + Read through the :ref:`finding-issues` section to get some ideas. + + **Finding your way through the project** + + The first step when starting a new project is the hardest. We wrote some + help guides that we used when we were looking for solutions and we hope + they will help. + + Read through :ref:`solving` section. + + **Communication** + + Communication is very important. You may need some help solving the problem + (happening to developers all the time). Also, when you have an issue you want + to solve it is advisable to let the team know you are working on it and may + need some help. + + See possible channels of :ref:`communication`. + +#. **Once you found the solution, write and run the test** Review comment: This implies there is a single solution (and that one exists!) and a single test. I would rephrase it for example as: > Once you implemented the planned fix or feature, write and run tests for it ########## File path: docs/source/developers/guide/communication.rst ########## @@ -0,0 +1,116 @@ +.. Licensed to the Apache Software Foundation (ASF) under one +.. or more contributor license agreements. See the NOTICE file +.. distributed with this work for additional information +.. regarding copyright ownership. The ASF licenses this file +.. to you under the Apache License, Version 2.0 (the +.. "License"); you may not use this file except in compliance +.. with the License. You may obtain a copy of the License at + +.. http://www.apache.org/licenses/LICENSE-2.0 + +.. Unless required by applicable law or agreed to in writing, +.. software distributed under the License is distributed on an +.. "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +.. KIND, either express or implied. See the License for the +.. specific language governing permissions and limitations +.. under the License. + + +.. SCOPE OF THIS SECTION +.. Present Arrow developers to the general public to make +.. the barrier of contributing lower as new contributors will +.. have a feeling of joint work and possible help. Add ways +.. of communication and add description of what is expected. +.. Also add a link to other resources. + + +.. _communication: + +************* +Communication +************* + +**About the contributors** + +The group of contributors is full of experts, software engineers and core +developers but also full of users, learners and enthusiasts that love doing +what we do and we want to spread this enthusiasm to you also. + +We all have silly questions and we all need help lots of times. +We encourage you to be open to communication and we will help as much as +we can. + +Due to the scale of the project which includes many languages, everybody +contributing will be faced with new things needed to be learned. Even the most +seasoned C++ developer will need to ask basic questions about R for example. + +When communicating, it's important you mark your communication with appropriate +tags ([C++], [R], [Ruby] etc.) so it gets noticed by the right people. + +Where to get help 👋 +==================== + +JIRA +~~~~ + +The most used way is to communicate through JIRA. + +When to use JIRA? + +- If you want to **report a bug**. +- If you want to **propose a new feature**. +- If you want to **propose a bigger change in the documentation**. + +In these cases you can create a JIRA issue and connect +with other contributors in the comments. + +.. note:: + How to make a JIRA issue. See `Tips for using JIRA <https://arrow.apache.org/docs/developers/contributing.html#tips-for-using-jira/>`_. + +- If you want to **solve an issue that is already in JIRA**, you should + connect with other contributors in the comments. + +JIRA is used to discuss the problem before the pull request is made (how to start, +where to search for the solution, etc..). + +GitHub +~~~~~~ + +Further options of communicating are provided through GitHub. + +When to use GitHub? + +- **For any question you may have or problems you are facing, you can make an issue on GutHub.** +- If you have **a problem with the build**, you can make an issue on GitHub + and discuss the possible solution (or write to the user mailing list). + + Making an issue about things you are not sure about may feel intimidating, + but it is also useful for others and the project. + + .. warning:: + Make sure to add which operating system and Arrow version you are using in the + ticket description plus the debug information/error. + +- If you have **a new feature already written**, you should make a pull request and Review comment: Hmm, but in this case I would still expect the contributor to create a JIRA first. ########## File path: docs/source/developers/guide/introduction.rst ########## @@ -0,0 +1,142 @@ +.. Licensed to the Apache Software Foundation (ASF) under one +.. or more contributor license agreements. See the NOTICE file +.. distributed with this work for additional information +.. regarding copyright ownership. The ASF licenses this file +.. to you under the Apache License, Version 2.0 (the +.. "License"); you may not use this file except in compliance +.. with the License. You may obtain a copy of the License at + +.. http://www.apache.org/licenses/LICENSE-2.0 + +.. Unless required by applicable law or agreed to in writing, +.. software distributed under the License is distributed on an +.. "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +.. KIND, either express or implied. See the License for the +.. specific language governing permissions and limitations +.. under the License. + + +.. SCOPE OF THIS SECTION +.. Make an introduction to the Guide for New Contributors. +.. Add an introduction to the project, why to get involved +.. and a quick checklist of the contributing process. +.. Add the Table of Contents. All detailed explanations +.. should be added as a link in the content. + + +.. _introduction: + +*********************** +New Contributor's Guide +*********************** + +This guide is meant to be a resource for contributing to +`Arrow <https://arrow.apache.org//>`_ for new contributors. + +Starting to contribute to a project like Apache Arrow can look +scary. Taking small steps will help making this tack easier. + + +Why contribute to Arrow? +======================== +There can be various reasons why someone would want to contribute +to Arrow: + +* You find the project interesting and would like to try making + a contribution to learn more about the library and grow your skills. + +* You use Arrow in the project you are working on and you would like + to make a new feature or fix a bug yourself. Review comment: I would say "implement a new feature" ########## File path: docs/source/developers/guide/step_by_step/building.rst ########## @@ -0,0 +1,51 @@ +.. Licensed to the Apache Software Foundation (ASF) under one +.. or more contributor license agreements. See the NOTICE file +.. distributed with this work for additional information +.. regarding copyright ownership. The ASF licenses this file +.. to you under the Apache License, Version 2.0 (the +.. "License"); you may not use this file except in compliance +.. with the License. You may obtain a copy of the License at + +.. http://www.apache.org/licenses/LICENSE-2.0 + +.. Unless required by applicable law or agreed to in writing, +.. software distributed under the License is distributed on an +.. "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +.. KIND, either express or implied. See the License for the +.. specific language governing permissions and limitations +.. under the License. + + +.. SCOPE OF THIS SECTION +.. The aim of this section is to provide extra description to +.. the process of building Arow library. It could include: +.. what does building mean, what is CMake, what are flags and why +.. do we use them, is building Arrow supposed to be straigtforward? +.. etc. + +.. Be sure not to duplicate with existing documentation! +.. All language-specific instructions about building, testing, +.. installing dependencies, etc. should go into language-specific +.. documentation. + + +.. _build-arrow: + +************************* +Building Arrow package 🏋🏿♀️ Review comment: "Arrow package" is quite vague. There are many implementations... ########## File path: docs/source/developers/guide/introduction.rst ########## @@ -0,0 +1,142 @@ +.. Licensed to the Apache Software Foundation (ASF) under one +.. or more contributor license agreements. See the NOTICE file +.. distributed with this work for additional information +.. regarding copyright ownership. The ASF licenses this file +.. to you under the Apache License, Version 2.0 (the +.. "License"); you may not use this file except in compliance +.. with the License. You may obtain a copy of the License at + +.. http://www.apache.org/licenses/LICENSE-2.0 + +.. Unless required by applicable law or agreed to in writing, +.. software distributed under the License is distributed on an +.. "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +.. KIND, either express or implied. See the License for the +.. specific language governing permissions and limitations +.. under the License. + + +.. SCOPE OF THIS SECTION +.. Make an introduction to the Guide for New Contributors. +.. Add an introduction to the project, why to get involved +.. and a quick checklist of the contributing process. +.. Add the Table of Contents. All detailed explanations +.. should be added as a link in the content. + + +.. _introduction: + +*********************** +New Contributor's Guide +*********************** + +This guide is meant to be a resource for contributing to +`Arrow <https://arrow.apache.org//>`_ for new contributors. + +Starting to contribute to a project like Apache Arrow can look +scary. Taking small steps will help making this tack easier. + + +Why contribute to Arrow? +======================== +There can be various reasons why someone would want to contribute +to Arrow: + +* You find the project interesting and would like to try making + a contribution to learn more about the library and grow your skills. + +* You use Arrow in the project you are working on and you would like + to make a new feature or fix a bug yourself. + +Read more about the project in the :ref:`about_arrow` section. + +Quick Reference +=============== + +Here are the basic steps needed to get set up and contribute to Arrow. +This is meant as a checklist and also to have an overall picture. + +For complete instructions please follow :ref:`step_by_step` (a +step-by-step guide) or R and Python :ref:`tutorial-index` for an example +of adding a basic feature. + + +#. **Install and set up Git, fork the Arrow repository** + + See detailed instructions on how to :ref:`set-up` Git and fork the + Arrow repository. + +#. **Build Arrow** + + This can be quite easy or a real blocker. Be prepared to dig through the + additional flags for cmake in the C++ build guide and read the doc carefully + to not miss any suggestions already given there. Anytime you are stuck, + reach out to us via appropriate :ref:`communication` channel. + + See detailed instructions on how to :ref:`build-arrow`. + +#. **Run the tests** + + Run the tests from a terminal for Python + + .. code-block:: + + $ pytest pyarrow + + or R + + .. code-block:: + + $ devtools::test() + +#. **Find an issue, create a new branch and work on the problem** Review comment: I don't know what "find an issue" means here. Is it find an existing JIRA to work on? Finding a new bug or feature that isn't tracked on JIRA? ########## File path: docs/source/developers/guide/introduction.rst ########## @@ -0,0 +1,142 @@ +.. Licensed to the Apache Software Foundation (ASF) under one +.. or more contributor license agreements. See the NOTICE file +.. distributed with this work for additional information +.. regarding copyright ownership. The ASF licenses this file +.. to you under the Apache License, Version 2.0 (the +.. "License"); you may not use this file except in compliance +.. with the License. You may obtain a copy of the License at + +.. http://www.apache.org/licenses/LICENSE-2.0 + +.. Unless required by applicable law or agreed to in writing, +.. software distributed under the License is distributed on an +.. "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +.. KIND, either express or implied. See the License for the +.. specific language governing permissions and limitations +.. under the License. + + +.. SCOPE OF THIS SECTION +.. Make an introduction to the Guide for New Contributors. +.. Add an introduction to the project, why to get involved +.. and a quick checklist of the contributing process. +.. Add the Table of Contents. All detailed explanations +.. should be added as a link in the content. + + +.. _introduction: + +*********************** +New Contributor's Guide +*********************** + +This guide is meant to be a resource for contributing to +`Arrow <https://arrow.apache.org//>`_ for new contributors. + +Starting to contribute to a project like Apache Arrow can look +scary. Taking small steps will help making this tack easier. + + +Why contribute to Arrow? +======================== +There can be various reasons why someone would want to contribute +to Arrow: + +* You find the project interesting and would like to try making + a contribution to learn more about the library and grow your skills. + +* You use Arrow in the project you are working on and you would like + to make a new feature or fix a bug yourself. + +Read more about the project in the :ref:`about_arrow` section. + +Quick Reference +=============== + +Here are the basic steps needed to get set up and contribute to Arrow. +This is meant as a checklist and also to have an overall picture. + +For complete instructions please follow :ref:`step_by_step` (a +step-by-step guide) or R and Python :ref:`tutorial-index` for an example +of adding a basic feature. + + +#. **Install and set up Git, fork the Arrow repository** + + See detailed instructions on how to :ref:`set-up` Git and fork the + Arrow repository. + +#. **Build Arrow** + + This can be quite easy or a real blocker. Be prepared to dig through the + additional flags for cmake in the C++ build guide and read the doc carefully + to not miss any suggestions already given there. Anytime you are stuck, + reach out to us via appropriate :ref:`communication` channel. + + See detailed instructions on how to :ref:`build-arrow`. + +#. **Run the tests** + + Run the tests from a terminal for Python + + .. code-block:: + + $ pytest pyarrow + + or R + + .. code-block:: + + $ devtools::test() + +#. **Find an issue, create a new branch and work on the problem** + + **Finding an issue** + + Not so easy, we agree. + Read through the :ref:`finding-issues` section to get some ideas. + + **Finding your way through the project** + + The first step when starting a new project is the hardest. We wrote some + help guides that we used when we were looking for solutions and we hope + they will help. + + Read through :ref:`solving` section. + + **Communication** + + Communication is very important. You may need some help solving the problem + (happening to developers all the time). Also, when you have an issue you want Review comment: It's not clear what "have an issue" refers to. Is it a JIRA? ########## File path: docs/source/developers/guide/communication.rst ########## @@ -0,0 +1,116 @@ +.. Licensed to the Apache Software Foundation (ASF) under one +.. or more contributor license agreements. See the NOTICE file +.. distributed with this work for additional information +.. regarding copyright ownership. The ASF licenses this file +.. to you under the Apache License, Version 2.0 (the +.. "License"); you may not use this file except in compliance +.. with the License. You may obtain a copy of the License at + +.. http://www.apache.org/licenses/LICENSE-2.0 + +.. Unless required by applicable law or agreed to in writing, +.. software distributed under the License is distributed on an +.. "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +.. KIND, either express or implied. See the License for the +.. specific language governing permissions and limitations +.. under the License. + + +.. SCOPE OF THIS SECTION +.. Present Arrow developers to the general public to make +.. the barrier of contributing lower as new contributors will +.. have a feeling of joint work and possible help. Add ways +.. of communication and add description of what is expected. +.. Also add a link to other resources. + + +.. _communication: + +************* +Communication +************* + +**About the contributors** + +The group of contributors is full of experts, software engineers and core +developers but also full of users, learners and enthusiasts that love doing +what we do and we want to spread this enthusiasm to you also. + +We all have silly questions and we all need help lots of times. +We encourage you to be open to communication and we will help as much as +we can. + +Due to the scale of the project which includes many languages, everybody +contributing will be faced with new things needed to be learned. Even the most +seasoned C++ developer will need to ask basic questions about R for example. + +When communicating, it's important you mark your communication with appropriate +tags ([C++], [R], [Ruby] etc.) so it gets noticed by the right people. + +Where to get help 👋 +==================== + +JIRA +~~~~ + +The most used way is to communicate through JIRA. + +When to use JIRA? + +- If you want to **report a bug**. +- If you want to **propose a new feature**. +- If you want to **propose a bigger change in the documentation**. + +In these cases you can create a JIRA issue and connect +with other contributors in the comments. + +.. note:: + How to make a JIRA issue. See `Tips for using JIRA <https://arrow.apache.org/docs/developers/contributing.html#tips-for-using-jira/>`_. + +- If you want to **solve an issue that is already in JIRA**, you should + connect with other contributors in the comments. + +JIRA is used to discuss the problem before the pull request is made (how to start, +where to search for the solution, etc..). + +GitHub +~~~~~~ + +Further options of communicating are provided through GitHub. + +When to use GitHub? + +- **For any question you may have or problems you are facing, you can make an issue on GutHub.** +- If you have **a problem with the build**, you can make an issue on GitHub + and discuss the possible solution (or write to the user mailing list). + + Making an issue about things you are not sure about may feel intimidating, + but it is also useful for others and the project. + + .. warning:: + Make sure to add which operating system and Arrow version you are using in the + ticket description plus the debug information/error. + +- If you have **a new feature already written**, you should make a pull request and + write in the comment about the feature you are proposing. +- GitHub is also used to discuss your work after the **pull request** is made. + +Mailing List +~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can subscribe to the **user** or **development** mailing list and browse for +previous topics or ask questions. Whereas discussion on GitHub and JIRA +only notifies people who have subscribed to that particular pull request or ticket, +the mailing list allows you to broadcast to all users or developers. Use these when +you want to get feedback or answers from a wider audience. + +There is also a **biweekly developers sync call** that anyone is welcome to join. +It is announced on the development mailing list together with the link to join. + +.. note:: Review comment: "seealso" as well? ########## File path: docs/source/developers/guide/step_by_step/solving_the_problem.rst ########## @@ -0,0 +1,28 @@ +.. Licensed to the Apache Software Foundation (ASF) under one +.. or more contributor license agreements. See the NOTICE file +.. distributed with this work for additional information +.. regarding copyright ownership. The ASF licenses this file +.. to you under the Apache License, Version 2.0 (the +.. "License"); you may not use this file except in compliance +.. with the License. You may obtain a copy of the License at + +.. http://www.apache.org/licenses/LICENSE-2.0 + +.. Unless required by applicable law or agreed to in writing, +.. software distributed under the License is distributed on an +.. "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +.. KIND, either express or implied. See the License for the +.. specific language governing permissions and limitations +.. under the License. + +.. _solving: + +********************** +Solving the problem 🧐 Review comment: If it's not clear what this page will contain, it can be removed for now (it's empty) and re-added if the need surfaces. ########## File path: docs/source/developers/guide/tutorials/index.rst ########## @@ -0,0 +1,28 @@ +.. Licensed to the Apache Software Foundation (ASF) under one +.. or more contributor license agreements. See the NOTICE file +.. distributed with this work for additional information +.. regarding copyright ownership. The ASF licenses this file +.. to you under the Apache License, Version 2.0 (the +.. "License"); you may not use this file except in compliance +.. with the License. You may obtain a copy of the License at + +.. http://www.apache.org/licenses/LICENSE-2.0 + +.. Unless required by applicable law or agreed to in writing, +.. software distributed under the License is distributed on an +.. "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +.. KIND, either express or implied. See the License for the +.. specific language governing permissions and limitations +.. under the License. + +.. _tutorial-index: + +********* +Tutorials +********* Review comment: What do you intend these pages to contain? Tutorials for PyArrow and R-Arrow? For adding a feature? ########## File path: docs/source/developers/guide/introduction.rst ########## @@ -0,0 +1,142 @@ +.. Licensed to the Apache Software Foundation (ASF) under one +.. or more contributor license agreements. See the NOTICE file +.. distributed with this work for additional information +.. regarding copyright ownership. The ASF licenses this file +.. to you under the Apache License, Version 2.0 (the +.. "License"); you may not use this file except in compliance +.. with the License. You may obtain a copy of the License at + +.. http://www.apache.org/licenses/LICENSE-2.0 + +.. Unless required by applicable law or agreed to in writing, +.. software distributed under the License is distributed on an +.. "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +.. KIND, either express or implied. See the License for the +.. specific language governing permissions and limitations +.. under the License. + + +.. SCOPE OF THIS SECTION +.. Make an introduction to the Guide for New Contributors. +.. Add an introduction to the project, why to get involved +.. and a quick checklist of the contributing process. +.. Add the Table of Contents. All detailed explanations +.. should be added as a link in the content. + + +.. _introduction: + +*********************** +New Contributor's Guide +*********************** + +This guide is meant to be a resource for contributing to +`Arrow <https://arrow.apache.org//>`_ for new contributors. + +Starting to contribute to a project like Apache Arrow can look +scary. Taking small steps will help making this tack easier. + + +Why contribute to Arrow? +======================== +There can be various reasons why someone would want to contribute +to Arrow: + +* You find the project interesting and would like to try making + a contribution to learn more about the library and grow your skills. + +* You use Arrow in the project you are working on and you would like + to make a new feature or fix a bug yourself. + +Read more about the project in the :ref:`about_arrow` section. + +Quick Reference +=============== + +Here are the basic steps needed to get set up and contribute to Arrow. +This is meant as a checklist and also to have an overall picture. + +For complete instructions please follow :ref:`step_by_step` (a +step-by-step guide) or R and Python :ref:`tutorial-index` for an example +of adding a basic feature. + + +#. **Install and set up Git, fork the Arrow repository** + + See detailed instructions on how to :ref:`set-up` Git and fork the + Arrow repository. + +#. **Build Arrow** + + This can be quite easy or a real blocker. Be prepared to dig through the + additional flags for cmake in the C++ build guide and read the doc carefully + to not miss any suggestions already given there. Anytime you are stuck, + reach out to us via appropriate :ref:`communication` channel. + + See detailed instructions on how to :ref:`build-arrow`. + +#. **Run the tests** + + Run the tests from a terminal for Python + + .. code-block:: + + $ pytest pyarrow + + or R + + .. code-block:: + + $ devtools::test() + +#. **Find an issue, create a new branch and work on the problem** + + **Finding an issue** + + Not so easy, we agree. + Read through the :ref:`finding-issues` section to get some ideas. + + **Finding your way through the project** + + The first step when starting a new project is the hardest. We wrote some + help guides that we used when we were looking for solutions and we hope + they will help. + + Read through :ref:`solving` section. + + **Communication** + + Communication is very important. You may need some help solving the problem Review comment: "solving a problem" or "solving problems you encounter on the way", perhaps? ########## File path: docs/source/developers/guide/communication.rst ########## @@ -0,0 +1,116 @@ +.. Licensed to the Apache Software Foundation (ASF) under one +.. or more contributor license agreements. See the NOTICE file +.. distributed with this work for additional information +.. regarding copyright ownership. The ASF licenses this file +.. to you under the Apache License, Version 2.0 (the +.. "License"); you may not use this file except in compliance +.. with the License. You may obtain a copy of the License at + +.. http://www.apache.org/licenses/LICENSE-2.0 + +.. Unless required by applicable law or agreed to in writing, +.. software distributed under the License is distributed on an +.. "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +.. KIND, either express or implied. See the License for the +.. specific language governing permissions and limitations +.. under the License. + + +.. SCOPE OF THIS SECTION +.. Present Arrow developers to the general public to make +.. the barrier of contributing lower as new contributors will +.. have a feeling of joint work and possible help. Add ways +.. of communication and add description of what is expected. +.. Also add a link to other resources. + + +.. _communication: + +************* +Communication +************* + +**About the contributors** + +The group of contributors is full of experts, software engineers and core +developers but also full of users, learners and enthusiasts that love doing +what we do and we want to spread this enthusiasm to you also. + +We all have silly questions and we all need help lots of times. +We encourage you to be open to communication and we will help as much as +we can. + +Due to the scale of the project which includes many languages, everybody +contributing will be faced with new things needed to be learned. Even the most +seasoned C++ developer will need to ask basic questions about R for example. + +When communicating, it's important you mark your communication with appropriate +tags ([C++], [R], [Ruby] etc.) so it gets noticed by the right people. + +Where to get help 👋 +==================== + +JIRA +~~~~ + +The most used way is to communicate through JIRA. + +When to use JIRA? + +- If you want to **report a bug**. +- If you want to **propose a new feature**. +- If you want to **propose a bigger change in the documentation**. + +In these cases you can create a JIRA issue and connect +with other contributors in the comments. + +.. note:: + How to make a JIRA issue. See `Tips for using JIRA <https://arrow.apache.org/docs/developers/contributing.html#tips-for-using-jira/>`_. + +- If you want to **solve an issue that is already in JIRA**, you should + connect with other contributors in the comments. + +JIRA is used to discuss the problem before the pull request is made (how to start, +where to search for the solution, etc..). + +GitHub +~~~~~~ + +Further options of communicating are provided through GitHub. + +When to use GitHub? + +- **For any question you may have or problems you are facing, you can make an issue on GutHub.** Review comment: Other wording nit: "create an issue" is probably better than "make an issue" (not 100% sure, as I'm not a native English speaker) ########## File path: docs/source/developers/guide/step_by_step/finding_issues.rst ########## @@ -0,0 +1,32 @@ +.. Licensed to the Apache Software Foundation (ASF) under one +.. or more contributor license agreements. See the NOTICE file +.. distributed with this work for additional information +.. regarding copyright ownership. The ASF licenses this file +.. to you under the Apache License, Version 2.0 (the +.. "License"); you may not use this file except in compliance +.. with the License. You may obtain a copy of the License at + +.. http://www.apache.org/licenses/LICENSE-2.0 + +.. Unless required by applicable law or agreed to in writing, +.. software distributed under the License is distributed on an +.. "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +.. KIND, either express or implied. See the License for the +.. specific language governing permissions and limitations +.. under the License. + + +.. SCOPE OF THIS SECTION +.. This section should include additional information +.. about JIRA, how to find issues or how to create one. +.. Should not duplicate with Report bugs and propose features +.. section: + +.. https://arrow.apache.org/docs/developers/contributing.html#tips-for-using-jira + + +.. _finding-issues: + +**************************** +Finding good first issues 🔎 Review comment: +1 for writing this section ########## File path: docs/source/developers/guide/about_arrow.rst ########## @@ -0,0 +1,37 @@ +.. Licensed to the Apache Software Foundation (ASF) under one +.. or more contributor license agreements. See the NOTICE file +.. distributed with this work for additional information +.. regarding copyright ownership. The ASF licenses this file +.. to you under the Apache License, Version 2.0 (the +.. "License"); you may not use this file except in compliance +.. with the License. You may obtain a copy of the License at + +.. http://www.apache.org/licenses/LICENSE-2.0 + +.. Unless required by applicable law or agreed to in writing, +.. software distributed under the License is distributed on an +.. "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +.. KIND, either express or implied. See the License for the +.. specific language governing permissions and limitations +.. under the License. + + +.. SCOPE OF THIS SECTION +.. This section should include basic information +.. about the Arrow project. If possible the content should be +.. written in words easy understandable to beginner notß +.. necessary acquainted with the library and the technical +.. details. + +.. _about_arrow: + +*********** +About Arrow +*********** + +General overview. TODO Review comment: That said, if https://arrow.apache.org/ and https://arrow.apache.org/overview/ are not informative enough, we should perhaps try to improve them instead of adding another resource here. -- 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. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
