You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@arrow.apache.org by ap...@apache.org on 2019/05/15 17:08:59 UTC
[arrow] branch master updated: ARROW-5288: [Documentation] Enhance
the contribution guidelines page
This is an automated email from the ASF dual-hosted git repository.
apitrou pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/arrow.git
The following commit(s) were added to refs/heads/master by this push:
new 10db674 ARROW-5288: [Documentation] Enhance the contribution guidelines page
10db674 is described below
commit 10db6745159b69c0cff3ea75e551a4337b3e385f
Author: Neal Richardson <ne...@gmail.com>
AuthorDate: Wed May 15 19:08:49 2019 +0200
ARROW-5288: [Documentation] Enhance the contribution guidelines page
In addition to recording some of the usage conventions for JIRA fields, I added a bunch of links to resources that were discussed in the document and fixed a ToC breadcrumb.
Author: Neal Richardson <ne...@gmail.com>
Closes #4279 from nealrichardson/jira-conventions and squashes the following commits:
d72853432 <Neal Richardson> Remove developers/index.rst because sphinx warns about it
7c9927dd6 <Neal Richardson> Squash a silly sphinx warning
e900a3979 <Neal Richardson> Add friendlier mailing list archive link
05c5799c1 <Neal Richardson> A few more revisions to contribution guidelines
2ab713f4f <Neal Richardson> Code review feedback
1defd961a <Neal Richardson> Enhance the contribution guidelines page
---
.github/CONTRIBUTING.md | 12 ++++----
.github/ISSUE_TEMPLATE.md | 7 +++--
docs/source/developers/contributing.rst | 54 ++++++++++++++++++++++++---------
docs/source/developers/index.rst | 26 ----------------
docs/source/index.rst | 7 ++++-
5 files changed, 56 insertions(+), 50 deletions(-)
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
index c762fd6..bbabe35 100644
--- a/.github/CONTRIBUTING.md
+++ b/.github/CONTRIBUTING.md
@@ -42,23 +42,23 @@ the procedure below.
If you are looking for some ideas on what to contribute, check out the [JIRA
issues][3] for the Apache Arrow project. Comment on the issue and/or contact
-[dev@arrow.apache.org](http://mail-archives.apache.org/mod_mbox/arrow-dev/)
+[dev@arrow.apache.org](https://lists.apache.org/list.html?dev@arrow.apache.org)
with your questions and ideas.
If you’d like to report a bug but don’t have time to fix it, you can still post
it on JIRA, or email the mailing list
-[dev@arrow.apache.org](http://mail-archives.apache.org/mod_mbox/arrow-dev/)
+[dev@arrow.apache.org](https://lists.apache.org/list.html?dev@arrow.apache.org)
To contribute a patch:
1. Break your work into small, single-purpose patches if possible. It’s much
harder to merge in a large change with a lot of disjoint features.
-2. Create a JIRA for your patch on the [Arrow Project
+2. If one doesn't already exist, create a JIRA for your patch on the [Arrow Project
JIRA](https://issues.apache.org/jira/browse/ARROW).
3. Submit the patch as a GitHub pull request against the master branch. For a
-tutorial, see the GitHub guides on forking a repo and sending a pull
-request. Prefix your pull request name with the JIRA name (ex:
-https://github.com/apache/arrow/pull/240).
+tutorial, see the GitHub guides on [forking a repo](https://help.github.com/en/articles/fork-a-repo)
+and [sending a pull request](https://help.github.com/en/articles/creating-a-pull-request-from-a-fork). So that your pull request syncs with the JIRA issue, prefix your pull request
+name with the JIRA issue id (ex: [ARROW-767: [C++] Filesystem abstraction](https://github.com/apache/arrow/pull/4225))
4. Make sure that your code passes the unit tests. You can find instructions
how to run the unit tests for each Arrow component in its respective README
file.
diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md
index fb8d249..b7962a1 100644
--- a/.github/ISSUE_TEMPLATE.md
+++ b/.github/ISSUE_TEMPLATE.md
@@ -6,10 +6,11 @@ instance for maintaining a queue of development work and as the public record
for work on the project. So, feel free to delete this text and open an issue
here if you have a question or aren't sure whether something is a bug or
feature request. Any bugs, suggestions, or feature requests will eventually
-need to end up in JIRA, either before or after completing a pull request.
+need to end up in JIRA (https://issues.apache.org/jira/browse/ARROW),
+either before or after completing a pull request.
-See the Arrow JIRA project here: https://issues.apache.org/jira/browse/ARROW.
+See our contribution guidelines for more information: http://arrow.apache.org/docs/developers/contributing.html
For more in-depth development discussions, please use the public mailing list
dev@arrow.apache.org (first subscribe by sending an e-mail to
-dev-subscribe@arrow.apache.org).
\ No newline at end of file
+dev-subscribe@arrow.apache.org).
diff --git a/docs/source/developers/contributing.rst b/docs/source/developers/contributing.rst
index 326bdda..14de516 100644
--- a/docs/source/developers/contributing.rst
+++ b/docs/source/developers/contributing.rst
@@ -25,32 +25,55 @@ There are many ways to contribute to Apache Arrow:
* Contributing code (we call them "patches")
* Writing documentation (another form of code, in a way)
-* Participating in discussions on JIRA or the mailing list
+* Participating in discussions on `JIRA <https://issues.apache.org/jira/projects/ARROW/issues>`_ or the `mailing list <ht...@arrow.apache.org>`_
* Helping users of the libraries
* Reporting bugs and asking questions
-Mailing Lists and Issue Tracker
-===============================
+Mailing List
+============
Projects in The Apache Software Foundation ("the ASF") use public, archived
mailing lists to create a public record of each project's development
-activities and decision making process. As such, all contributors generally
+activities and decision-making process. As such, all contributors generally
must be subscribed to the dev@arrow.apache.org mailing list to participate in
the community.
Note that you must be subscribed to the mailing list in order to post to it. To
subscribe, send a blank email to dev-subscribe@arrow.apache.org.
-We use the `ASF JIRA <https://issues.apache.org/jira>`_ to manage our
-development "todo" list and to maintain changelogs for releases. You must
-create an account and be added as a "Contributor" to Apache Arrow to be able to
-assign yourself issues. Any project maintainer will be able to help you with
-this one-time setup.
+Mailing list archives can be found `here <ht...@arrow.apache.org>`_.
+
+Issue Tracking
+==============
+
+We use the `ASF JIRA <https://issues.apache.org/jira/projects/ARROW/issues>`_
+to manage our development "todo" list and to maintain changelogs for releases.
+In addition, the project's `Confluence site <https://cwiki.apache.org/confluence/display/ARROW>`_
+has some useful higher-level views of the JIRA issues.
+
+To create a JIRA issue, you'll need to have an account on the ASF JIRA, which
+you can `sign yourself up for <https://issues.apache.org/jira/secure/Signup!default.jspa>`_. No
+additional permissions are needed to create issues. Only once you are involved
+in the project and want to do more on JIRA, such as assign yourself an issue,
+will you need "Contributor" permissions on the Apache Arrow JIRA. To get this
+role, ask on the mailing list for a project maintainer's help.
+
+When reporting a new issue, follow these conventions to help make sure the
+right people see it:
+
+* If the issue is specific to a language binding or other key component, prefix the issue name with it, like ``[Python] issue name``.
+* If you're reporting something that used to work in a previous version but doesn't work in the current release, you can add the "Affects version" field. For feature requests and other proposals, "Affects version" isn't appropriate.
+
+Project maintainers may later tweak formatting and labels to help improve their
+visibility. They may add a "Fix version" to indicate that they're considering
+it for inclusion in the next release, though adding that tag is not a
+commitment that it will be done in the next release.
GitHub issues
-------------
-We support GitHub issues as a lightweight way to ask questions and engage with
+We support `GitHub issues <https://github.com/apache/arrow/issues>`_ as a
+lightweight way to ask questions and engage with
the Arrow developer community. We use JIRA for maintaining a queue of
development work and as the public record for work on the project. So, feel
free to open GitHub issues, but bugs and feature requests will eventually need
@@ -76,11 +99,14 @@ To contribute a patch:
* Break your work into small, single-purpose patches if possible. It’s much
harder to merge in a large change with a lot of disjoint features.
-* Create a JIRA for your patch on the Arrow Project JIRA.
+* If one doesn't already exist, create a JIRA for your patch on the
+ `Arrow Project JIRA <https://issues.apache.org/jira/projects/ARROW/issues>`_.
* Submit the patch as a GitHub pull request against the master branch. For a
- tutorial, see the GitHub guides on forking a repo and sending a pull
- request. Prefix your pull request name with the JIRA name (ex:
- https://github.com/apache/arrow/pull/240).
+ tutorial, see the GitHub guides on `forking a repo <https://help.github.com/en/articles/fork-a-repo>`_
+ and `sending a pull request <https://help.github.com/en/articles/creating-a-pull-request-from-a-fork>`_.
+ So that your pull request syncs with the JIRA issue, prefix your pull request
+ name with the JIRA issue id (ex:
+ `ARROW-767: [C++] Filesystem abstraction <https://github.com/apache/arrow/pull/4225>`_).
* Make sure that your code passes the unit tests. You can find instructions how
to run the unit tests for each Arrow component in its respective README file.
* Add new unit tests for your code.
diff --git a/docs/source/developers/index.rst b/docs/source/developers/index.rst
deleted file mode 100644
index d309638..0000000
--- a/docs/source/developers/index.rst
+++ /dev/null
@@ -1,26 +0,0 @@
-.. 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.
-
-.. toctree::
- :maxdepth: 2
-
- contributing
- cpp
- python
- integration
- benchmarks
- documentation
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 3a5728a..3b639b4 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -59,4 +59,9 @@ such topics as:
:maxdepth: 2
:caption: Development and Contributing
- developers/index
+ developers/contributing
+ developers/cpp
+ developers/python
+ developers/integration
+ developers/benchmarks
+ developers/documentation