thisisnic commented on a change in pull request #11677: URL: https://github.com/apache/arrow/pull/11677#discussion_r753039517
########## File path: docs/source/developers/guide/introduction.rst ########## @@ -0,0 +1,135 @@ +.. 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. + +.. _introduction: + +********************** +New Contributor's Guide Review comment: > Thanks for starting this! > > I think it is desirable to reframe this a bit before you write too much text: > > * this "contributor's guide" (or "contribution guide"? @thisisnic what do you think?) should IMHO focus on the language-independent aspects, whether technical, social or communicational (how to get set up with Git, fork the repo, use JIRA, ask for help, etc.) > > * all language-specific instructions about building, testing, installing dependencies, etc. should go into language-specific docs (if they are not already there); don't hesitate to open individual JIRAs if such documentation is currently missing! > > > Opinions @amol- @jorisvandenbossche ? I don't think there's enough difference between "contribution guide" and "contributor's guide" for one to be particularly better than the other. I also agree that the language-specific elements should go into their corresponding docs. Just a thought - I wonder if some of the original idea behind this initiative is being diluted a little here? My understanding was that originally this was a guide for new contributors, rather than a new version of the contribution docs, with the point being that there are actually loads of Arrow users who are totally capable of contributing, but maybe don't see themselves as such. And so, it calls for a gentle introduction, helped by the informal language etc, and extra context/descriptive stuff. Whereas there is a secondary task of generally improving the contribution docs, in terms of writing more general content, which may be more concise, more formal, and serve the purpose of just providing information. Things may have evolved from this - feel free to disregard this - but just wanted to check as I feel like there are multiple different approaches 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: github-unsubscr...@arrow.apache.org For queries about this service, please contact Infrastructure at: us...@infra.apache.org
