jorisvandenbossche commented on a change in pull request #11677: URL: https://github.com/apache/arrow/pull/11677#discussion_r758402905
########## File path: docs/source/developers/guide/other.rst ########## @@ -0,0 +1,29 @@ +.. 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 +.. Add articles/resources on concepts important to Arrow as +.. well as recommended books for learning different languages +.. included in the project. + + +.. _other: Review comment: ```suggestion .. _other-resources: ``` or something alike (that will make the target label more descriptive, eg I was seeing this in communication.rst and that was a bit cryptic) ########## File path: docs/source/developers/guide/introduction.rst ########## @@ -0,0 +1,153 @@ +.. 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. + +No matter what your current skills are, you can try and make +your first time contribution to Arrow. + +Starting to contribute to a project like Apache Arrow can be +intimidating. Taking small steps will make this task +easier. + + +Why contribute to Arrow? +======================== +There can be various reasons why you might 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 a project you are working on and you would like + to implement a new feature. + +Read more about the project in the :ref:`architectural_overview` section. + +Quick Reference +=============== + +Here are the basic steps needed to get set up and contribute to Arrow. +This is meant both as a checklist and also to provide an overall picture of the process. + +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, and fork the Arrow repository** + + See detailed instructions on how to :ref:`set-up` Git and fork the + Arrow repository. + +#. **Build Arrow** + + 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. The C++ build guide + has suggestions for for commonly encountered issues - you can find it + `here <https://arrow.apache.org/docs/developers/cpp/index.html#cpp-development>`_. Review comment: You can reference this with the ``:ref:`cpp-development` `` syntax as well here. ########## File path: docs/source/developers/guide/introduction.rst ########## @@ -0,0 +1,153 @@ +.. 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. + +No matter what your current skills are, you can try and make +your first time contribution to Arrow. + +Starting to contribute to a project like Apache Arrow can be +intimidating. Taking small steps will make this task +easier. + + +Why contribute to Arrow? +======================== +There can be various reasons why you might 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 a project you are working on and you would like + to implement a new feature. Review comment: ```suggestion to implement a new feature or fix a bug you encountered. ``` ########## File path: docs/source/developers/guide/step_by_step/index.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. + +.. _step_by_step: + +***************************** +Steps in making your first PR +***************************** + +.. toctree:: + :maxdepth: 2 + + set_up + building + finding_issues + solving_the_problem Review comment: this file doesn't exist anymore? ########## File path: docs/source/developers/guide/introduction.rst ########## @@ -0,0 +1,153 @@ +.. Licensed to the Apache Software Foundation (ASF) under one Review comment: Typically the main page / landing page of a subfolder is called `index.rst`. Could keep that consistent? (but also doesn't matter that much) ########## 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: If this will be only short telling about how documentation is a good place to start contributing, this content could maybe also be added to "Finding good first issues". But that's also something that can be discussed when there's actually new content written for this section ########## 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's libraries 🏋🏿♀️ +***************************** Review comment: Same comment here about the title (it seems that this emoticon is multiple characters?) ########## File path: docs/source/developers/guide/communication.rst ########## @@ -0,0 +1,133 @@ +.. 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 👋 +==================== + +For any question you may have or problems you are facing you can write to +user or development :ref:`mailing_list` or you can create an issue on +:ref:`github`. + +For searching through the issues, reporting bugs and creating feature +requests or proposals you can use :ref:`jira` issue tracker. + +.. _jira: + +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 issue comments. It is good to mention the +way you are planning to solve the issue and have one of the Arrow +developers agree with your basic proposal for fixing it. Better +to ask before you spend too much of your time on something that we +might think is not a good idea. + +.. seealso:: + How to create 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 issue comments. + +JIRA is used to discuss the problem before a Pull Request is possibly made +(how to start, where to search for the solution, etc..). + +.. _github: + +GitHub +~~~~~~ + +Further options of communicating are provided through GitHub where the project +is hosted. What we use are GitGub Issues and Pull Requests. + +When to use GitHub? + +- If you have **a problem with building** one of the Arrow libraries, you can + create 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. + + .. note:: + 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 can create a Pull Request after Review comment: ```suggestion - If you have **a new contribution already written**, you can create a Pull Request after ``` ? (to be more general, since this can also be a bug fix or documentation update) ########## File path: docs/source/developers/guide/other.rst ########## @@ -0,0 +1,29 @@ +.. 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 +.. Add articles/resources on concepts important to Arrow as +.. well as recommended books for learning different languages +.. included in the project. + + +.. _other: + +***************************** +Additional information and resources +***************************** Review comment: sphinx gives warnings if the over/underline is shorter than the title text, so best add some more `*`'s -- 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]
