thisisnic commented on a change in pull request #12483:
URL: https://github.com/apache/arrow/pull/12483#discussion_r829212895
##########
File path: docs/source/developers/guide/step_by_step/finding_issues.rst
##########
@@ -64,57 +67,88 @@ you will see:
How to create a JIRA issue
==========================
-After creating an account you can click **Create an issue** and select
**Apache Arrow project**
-and **Type** of the issue (Bug, Feature, …).
+After creating an account you can click **Create an issue** and select
+**Apache Arrow project** and **Type** of the issue (Bug, Feature, …).
-.. figure:: jira_create_issue.jpeg
+.. figure:: /developers/images/jira_create_issue.jpeg
:scale: 70 %
:alt: creating JIRA issue
The window to create a JIRA issue.
-If you are already in JIRA dashboard click the red ``create`` button in the
top to do the same.
+If you are already in JIRA dashboard click the red ``create`` button in
+the top to do the same.
-You are ready to create the issue! Add a title and a description following the
-:ref:`tips for using JIRA <jira-tips>` and you are ready to go!
+You are ready to create the issue! Add a title and a description following
+the :ref:`tips for using JIRA <jira-tips>` and you are ready to go!
.. seealso::
:ref:`Tips for using JIRA <jira-tips>`
You don’t need any special permissions on JIRA to be able to create issues.
-Once you are more involved in the project and want to do more on JIRA, for
example assigning
-yourself an issue, you will need **“Contributor” permissions**. To get this
role, ask on the
-:ref:`mailing_list` or in the comment of the JIRA issue you created.
+Once you are more involved in the project and want to do more on JIRA, for
+example assigning yourself an issue, you will need **“Contributor”
permissions**.
+To get this role, ask on the :ref:`mailing_list` or in the comment of the JIRA
+issue you created.
-When the ticket is created you can start a discussion about it in the JIRA
comments section.
+When the ticket is created you can start a discussion about it in the
+JIRA comments section.
How we use JIRA to find an issue
================================
-To make it easier for you to find issues that are well-suited for new
contributors, we have added labels
-like “good-first-issue” or “beginner” to some JIRA tickets.
+To make it easier for you to find issues that are well-suited for new
+contributors, we have added labels like “good-first-issue” or “beginner”
+to some JIRA tickets.
.. seealso::
- Search for good first/second issues with labels like in the `link here
-
<https://issues.apache.org/jira/issues/?filter=-4&jql=project%20%3D%20ARROW%20AND%20status%20%3D%20Open%20AND%20labels%20in%20(Beginner%2C%20beginner%2C%20beginners%2C%20beginnner%2C%20beginner-friendly%2C%20good-first-issue%2C%20good-second-issue%2C%20GoodForNewContributors%2C%20newbie%2C%20easyfix%2C%20documentation)%20order%20by%20created%20DESC>`_
+ Search for good first/second issues with labels like in the `link here
+
<https://issues.apache.org/jira/issues/?filter=-4&jql=project%20%3D%20ARROW%20AND%20status%20%3D%20Open%20AND%20labels%20in%20(Beginner%2C%20beginner%2C%20beginners%2C%20beginnner%2C%20beginner-friendly%2C%20good-first-issue%2C%20good-second-issue%2C%20GoodForNewContributors%2C%20newbie%2C%20easyfix%2C%20documentation)%20order%20by%20created%20DESC>`_
-The issues labeled as good first issues should take no more than two days or a
weekend to
-fix them. Once you dig into the code you may find that the issue is not easy
at all - this can
-happen as the problem could be harder than the person who triaged the ticket
expected it to be.
-Don't hesitate to write that in the comments.
+The issues labeled as good first issues should take no more than two days or
+a weekend to fix them. Once you dig into the code you may find that the issue
+is not easy at all - this can happen as the problem could be harder than the
+person who triaged the ticket expected it to be. Don't hesitate to write that
+in the comments.
-.. figure:: jira_good_first_issue.jpeg
+.. figure:: /developers/images/jira_good_first_issue.jpeg
:scale: 45 %
:alt: finding good first JIRA issue
Example of the list of good first issues.
.. note::
- When you find a JIRA issue you would like to work on, please mention
your interest in the comment
- section of that issue; that way we will know you are working on it.
+
+ When you find a JIRA issue you would like to work on, please mention your
+ interest in the comment section of that issue; that way we will know you
+ are working on it.
Also, do not hesitate to ask questions in the comment section of the issue.
You can get some pointers about where to start and similar issues already
solved.
-**Do not forget to create a new branch once you have created or chosen an
issue you will be
-working on!** Follow the instructions in the :ref:`pr_lifecycle` section or
follow the next section: :ref:`arrow-codebase`.
+**What if an issue is already asigned?**
+Anything that’s not in the “In Progress” state is fair game, even if it is
+“Assigned” to someone, particularly if it has not been recently updated.
+When in doubt, comment on the issue asking if they mind if you try to put
+together a pull request; interpret no response to mean that you’re free to
+proceed.
+
+**Aske questions**
Review comment:
```suggestion
**Ask questions**
```
##########
File path: docs/source/developers/bug_reports.rst
##########
@@ -0,0 +1,206 @@
+.. 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.
+
+.. _bug-reports:
+
+********************************
+Report bugs and propose features
+********************************
+
+Using the software and sharing your experience is a very helpful contribution
+itself. Those who actively develop Arrow need feedback from users on what
+works and what doesn't. Alerting us to unexpected behavior and missing
features,
+even if you can't solve the problems yourself, help us understand and
prioritize
+work to improve the libraries.
+
+We use `JIRA <https://issues.apache.org/jira/projects/ARROW/issues>`_
+to manage our development "todo" list and to maintain changelogs for releases.
+In addition, the project's `Confluence site
<https://cwiki.apache.org/confluence/display/ARROW>`_
+has some useful higher-level views of the JIRA issues.
+
+To create a JIRA issue, you'll need to have an account on the ASF JIRA, which
+you can `sign yourself up for
<https://issues.apache.org/jira/secure/Signup!default.jspa>`_.
+The JIRA server hosts bugs and issues for multiple Apache projects. The JIRA
+project name for Arrow is "ARROW".
+
+You don't need any special permissions on JIRA to be able to create issues.
+Once you are more involved in the project and want to do more on JIRA, such as
+assign yourself an issue, you will need "Contributor" permissions on the
+Apache Arrow JIRA. To get this role, ask on the mailing list for a project
+maintainer's help.
+
+
+.. _jira-tips:
+
+Tips for using JIRA
+===================
+
+Before you create a new issue, we recommend you first
+`search
<https://issues.apache.org/jira/issues/?jql=project%20%3D%20ARROW%20AND%20resolution%20%3D%20Unresolved>`_
+among existing Arrow issues.
+
+When reporting a new issue, follow these conventions to help make sure the
+right people see it:
+
+* Use the **Component** field to indicate the area of the project that your
+ issue pertains to (for example "Python" or "C++").
+* Also prefix the issue title with the component name in brackets, for example
+ ``[Python] issue name`` ; this helps when navigating lists of open issues,
+ and it also makes our changelogs more readable. Most prefixes are exactly
the
+ same as the **Component** name, with the following exceptions:
+
+ * **Component:** Continuous Integration — **Summary prefix:** [CI]
+ * **Component:** Developer Tools — **Summary prefix:** [Dev]
+ * **Component:** Documentation — **Summary prefix:** [Docs]
+
+* 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.
+
+.. _bug-report-tips:
+
+Tips for successful bug reports
+================================
+
+No one likes having bugs in their software, and in an ideal world, all bugs
+would get fixed as soon as they were reported. However, time and attention are
+finite, especially in an open-source project where most contributors are
+participating in their spare time. All contributors in Apache projects are
+volunteers and act as individuals, even if they are contributing to the project
+as part of their job responsibilities.
+
+In order for your bug to get prompt
+attention, there are things you can do to make it easier for contributors to
+reproduce and fix it.
+**When you're reporting a bug, please help us understand the issue by
providing,
+to the best of your ability,**
+
+* **Clear, minimal steps to reproduce the issue, with as few non-Arrow
+ dependencies as possible.** If there's a problem on reading a file, try to
+ provide as small of an example file as possible, or code to create one.
+ If your bug report says "it crashes trying to read my file, but I can't
+ share it with you," it's really hard for us to debug.
+* Any relevant operating system, language, and library version information
+* If it isn't obvious, clearly state the expected behavior and what actually
+ happened.
+
+If a developer can't get a failing unit test, they won't be able to know that
+the issue has been identified, and they won't know when it has been fixed.
+Try to anticipate the questions you might be asked by someone working to
+understand the issue and provide those supporting details up front.
+
+Good reproducible examples or minimal bug reports can be found in next tabs:
+
+.. tabs::
+
+ .. tab:: Python
+
+ The ``print`` method of a timestamp with timezone errors:
+
+ .. code-block:: python
+
+ import pyarrow as pa
+
+ a = pa.array([0], pa.timestamp('s', tz='+02:00'))
+
+ print(a) # representation not correct?
+ # <pyarrow.lib.TimestampArray object at 0x7f834c7cb9a8>
+ # [
+ # 1970-01-01 00:00:00
+ # ]
+
+ print(a[0])
+ #Traceback (most recent call last):
+ # File "<stdin>", line 1, in <module>
+ # File "pyarrow/scalar.pxi", line 80, in pyarrow.lib.Scalar.__repr__
+ # File "pyarrow/scalar.pxi", line 463, in
pyarrow.lib.TimestampScalar.as_py
+ # File "pyarrow/scalar.pxi", line 393, in
pyarrow.lib._datetime_from_int
+ #ValueError: fromutc: dt.tzinfo is not self
+
+ .. tab:: R
+
+ Error when reading a CSV file with ``col_types`` option ``"T"`` or
``"t"``:
+
+ .. code-block:: R
+
+ library(arrow)
+ #>
+ #> Attaching package: 'arrow'
+ #> The following object is masked from 'package:utils':
+ #>
+ #> timestamp
+ tf <- tempfile()
+ write.csv(data.frame(x = '2018-10-07 19:04:05.005'), tf, row.names =
FALSE)
+
+ # successfully read in file
+ read_csv_arrow(tf, as_data_frame = TRUE)
+ #> # A tibble: 1 × 1
+ #> x
+ #> <dttm>
+ #> 1 2018-10-07 20:04:05
+
+ # the unit here is seconds - doesn't work
+ read_csv_arrow(
+ tf,
+ col_names = "x",
+ col_types = "T",
+ skip = 1
+ )
+ #> Error in `handle_csv_read_error()`:
+ #> ! Invalid: In CSV column #0: CSV conversion error to timestamp[s]:
invalid value '2018-10-07 19:04:05.005'
+ #> /home/nic2/arrow/cpp/src/arrow/csv/converter.cc:550
decoder_.Decode(data, size, quoted, &value)
+ #> /home/nic2/arrow/cpp/src/arrow/csv/parser.h:123 status
+ #> /home/nic2/arrow/cpp/src/arrow/csv/converter.cc:554
parser.VisitColumn(col_index, visit)
Review comment:
```suggestion
#> ! Invalid: In CSV column #0: CSV conversion error to
timestamp[s]: invalid value '2018-10-07 19:04:05.005'
```
Trimming the extra bits of error message that wouldn't be here for users who
haven't set the environment variable `ARROW_R_DEV` to `TRUE`
##########
File path: docs/source/developers/bug_reports.rst
##########
@@ -0,0 +1,206 @@
+.. 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.
+
+.. _bug-reports:
+
+********************************
+Report bugs and propose features
+********************************
+
+Using the software and sharing your experience is a very helpful contribution
+itself. Those who actively develop Arrow need feedback from users on what
+works and what doesn't. Alerting us to unexpected behavior and missing
features,
+even if you can't solve the problems yourself, help us understand and
prioritize
+work to improve the libraries.
+
+We use `JIRA <https://issues.apache.org/jira/projects/ARROW/issues>`_
+to manage our development "todo" list and to maintain changelogs for releases.
+In addition, the project's `Confluence site
<https://cwiki.apache.org/confluence/display/ARROW>`_
+has some useful higher-level views of the JIRA issues.
+
+To create a JIRA issue, you'll need to have an account on the ASF JIRA, which
+you can `sign yourself up for
<https://issues.apache.org/jira/secure/Signup!default.jspa>`_.
+The JIRA server hosts bugs and issues for multiple Apache projects. The JIRA
+project name for Arrow is "ARROW".
+
+You don't need any special permissions on JIRA to be able to create issues.
+Once you are more involved in the project and want to do more on JIRA, such as
+assign yourself an issue, you will need "Contributor" permissions on the
+Apache Arrow JIRA. To get this role, ask on the mailing list for a project
+maintainer's help.
+
+
+.. _jira-tips:
+
+Tips for using JIRA
+===================
+
+Before you create a new issue, we recommend you first
+`search
<https://issues.apache.org/jira/issues/?jql=project%20%3D%20ARROW%20AND%20resolution%20%3D%20Unresolved>`_
+among existing Arrow issues.
+
+When reporting a new issue, follow these conventions to help make sure the
+right people see it:
+
+* Use the **Component** field to indicate the area of the project that your
+ issue pertains to (for example "Python" or "C++").
+* Also prefix the issue title with the component name in brackets, for example
+ ``[Python] issue name`` ; this helps when navigating lists of open issues,
+ and it also makes our changelogs more readable. Most prefixes are exactly
the
+ same as the **Component** name, with the following exceptions:
+
+ * **Component:** Continuous Integration — **Summary prefix:** [CI]
+ * **Component:** Developer Tools — **Summary prefix:** [Dev]
+ * **Component:** Documentation — **Summary prefix:** [Docs]
+
+* 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.
+
+.. _bug-report-tips:
+
+Tips for successful bug reports
+================================
+
+No one likes having bugs in their software, and in an ideal world, all bugs
+would get fixed as soon as they were reported. However, time and attention are
+finite, especially in an open-source project where most contributors are
+participating in their spare time. All contributors in Apache projects are
+volunteers and act as individuals, even if they are contributing to the project
+as part of their job responsibilities.
+
+In order for your bug to get prompt
+attention, there are things you can do to make it easier for contributors to
+reproduce and fix it.
+**When you're reporting a bug, please help us understand the issue by
providing,
+to the best of your ability,**
+
+* **Clear, minimal steps to reproduce the issue, with as few non-Arrow
+ dependencies as possible.** If there's a problem on reading a file, try to
+ provide as small of an example file as possible, or code to create one.
+ If your bug report says "it crashes trying to read my file, but I can't
+ share it with you," it's really hard for us to debug.
+* Any relevant operating system, language, and library version information
+* If it isn't obvious, clearly state the expected behavior and what actually
+ happened.
+
+If a developer can't get a failing unit test, they won't be able to know that
+the issue has been identified, and they won't know when it has been fixed.
+Try to anticipate the questions you might be asked by someone working to
+understand the issue and provide those supporting details up front.
+
+Good reproducible examples or minimal bug reports can be found in next tabs:
+
+.. tabs::
+
+ .. tab:: Python
+
+ The ``print`` method of a timestamp with timezone errors:
+
+ .. code-block:: python
+
+ import pyarrow as pa
+
+ a = pa.array([0], pa.timestamp('s', tz='+02:00'))
+
+ print(a) # representation not correct?
+ # <pyarrow.lib.TimestampArray object at 0x7f834c7cb9a8>
+ # [
+ # 1970-01-01 00:00:00
+ # ]
+
+ print(a[0])
+ #Traceback (most recent call last):
+ # File "<stdin>", line 1, in <module>
+ # File "pyarrow/scalar.pxi", line 80, in pyarrow.lib.Scalar.__repr__
+ # File "pyarrow/scalar.pxi", line 463, in
pyarrow.lib.TimestampScalar.as_py
+ # File "pyarrow/scalar.pxi", line 393, in
pyarrow.lib._datetime_from_int
+ #ValueError: fromutc: dt.tzinfo is not self
+
+ .. tab:: R
+
+ Error when reading a CSV file with ``col_types`` option ``"T"`` or
``"t"``:
+
+ .. code-block:: R
+
+ library(arrow)
+ #>
+ #> Attaching package: 'arrow'
+ #> The following object is masked from 'package:utils':
+ #>
+ #> timestamp
+ tf <- tempfile()
+ write.csv(data.frame(x = '2018-10-07 19:04:05.005'), tf, row.names =
FALSE)
+
+ # successfully read in file
+ read_csv_arrow(tf, as_data_frame = TRUE)
+ #> # A tibble: 1 × 1
+ #> x
+ #> <dttm>
+ #> 1 2018-10-07 20:04:05
+
+ # the unit here is seconds - doesn't work
+ read_csv_arrow(
+ tf,
+ col_names = "x",
+ col_types = "T",
+ skip = 1
+ )
+ #> Error in `handle_csv_read_error()`:
+ #> ! Invalid: In CSV column #0: CSV conversion error to timestamp[s]:
invalid value '2018-10-07 19:04:05.005'
+ #> /home/nic2/arrow/cpp/src/arrow/csv/converter.cc:550
decoder_.Decode(data, size, quoted, &value)
+ #> /home/nic2/arrow/cpp/src/arrow/csv/parser.h:123 status
+ #> /home/nic2/arrow/cpp/src/arrow/csv/converter.cc:554
parser.VisitColumn(col_index, visit)
+
+ # the unit here is ms - doesn't work
+ read_csv_arrow(
+ tf,
+ col_names = "x",
+ col_types = "t",
+ skip = 1
+ )
+ #> Error in `handle_csv_read_error()`:
+ #> ! Invalid: In CSV column #0: CSV conversion error to time32[ms]:
invalid value '2018-10-07 19:04:05.005'
+ #> /home/nic2/arrow/cpp/src/arrow/csv/converter.cc:550
decoder_.Decode(data, size, quoted, &value)
+ #> /home/nic2/arrow/cpp/src/arrow/csv/parser.h:123 status
+ #> /home/nic2/arrow/cpp/src/arrow/csv/converter.cc:554
parser.VisitColumn(col_index, visit)
Review comment:
```suggestion
#> ! Invalid: In CSV column #0: CSV conversion error to time32[ms]:
invalid value '2018-10-07 19:04:05.005'
```
##########
File path: docs/source/developers/bug_reports.rst
##########
@@ -0,0 +1,206 @@
+.. 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.
+
+.. _bug-reports:
+
+********************************
+Report bugs and propose features
+********************************
+
+Using the software and sharing your experience is a very helpful contribution
+itself. Those who actively develop Arrow need feedback from users on what
+works and what doesn't. Alerting us to unexpected behavior and missing
features,
+even if you can't solve the problems yourself, help us understand and
prioritize
+work to improve the libraries.
+
+We use `JIRA <https://issues.apache.org/jira/projects/ARROW/issues>`_
+to manage our development "todo" list and to maintain changelogs for releases.
+In addition, the project's `Confluence site
<https://cwiki.apache.org/confluence/display/ARROW>`_
+has some useful higher-level views of the JIRA issues.
+
+To create a JIRA issue, you'll need to have an account on the ASF JIRA, which
+you can `sign yourself up for
<https://issues.apache.org/jira/secure/Signup!default.jspa>`_.
+The JIRA server hosts bugs and issues for multiple Apache projects. The JIRA
+project name for Arrow is "ARROW".
+
+You don't need any special permissions on JIRA to be able to create issues.
+Once you are more involved in the project and want to do more on JIRA, such as
+assign yourself an issue, you will need "Contributor" permissions on the
+Apache Arrow JIRA. To get this role, ask on the mailing list for a project
+maintainer's help.
+
+
+.. _jira-tips:
+
+Tips for using JIRA
+===================
+
+Before you create a new issue, we recommend you first
+`search
<https://issues.apache.org/jira/issues/?jql=project%20%3D%20ARROW%20AND%20resolution%20%3D%20Unresolved>`_
+among existing Arrow issues.
+
+When reporting a new issue, follow these conventions to help make sure the
+right people see it:
+
+* Use the **Component** field to indicate the area of the project that your
+ issue pertains to (for example "Python" or "C++").
+* Also prefix the issue title with the component name in brackets, for example
+ ``[Python] issue name`` ; this helps when navigating lists of open issues,
+ and it also makes our changelogs more readable. Most prefixes are exactly
the
+ same as the **Component** name, with the following exceptions:
+
+ * **Component:** Continuous Integration — **Summary prefix:** [CI]
+ * **Component:** Developer Tools — **Summary prefix:** [Dev]
+ * **Component:** Documentation — **Summary prefix:** [Docs]
+
+* 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.
+
+.. _bug-report-tips:
+
+Tips for successful bug reports
+================================
+
+No one likes having bugs in their software, and in an ideal world, all bugs
+would get fixed as soon as they were reported. However, time and attention are
+finite, especially in an open-source project where most contributors are
+participating in their spare time. All contributors in Apache projects are
+volunteers and act as individuals, even if they are contributing to the project
+as part of their job responsibilities.
+
+In order for your bug to get prompt
+attention, there are things you can do to make it easier for contributors to
+reproduce and fix it.
+**When you're reporting a bug, please help us understand the issue by
providing,
+to the best of your ability,**
+
+* **Clear, minimal steps to reproduce the issue, with as few non-Arrow
+ dependencies as possible.** If there's a problem on reading a file, try to
+ provide as small of an example file as possible, or code to create one.
+ If your bug report says "it crashes trying to read my file, but I can't
+ share it with you," it's really hard for us to debug.
+* Any relevant operating system, language, and library version information
+* If it isn't obvious, clearly state the expected behavior and what actually
+ happened.
+
+If a developer can't get a failing unit test, they won't be able to know that
+the issue has been identified, and they won't know when it has been fixed.
+Try to anticipate the questions you might be asked by someone working to
+understand the issue and provide those supporting details up front.
+
+Good reproducible examples or minimal bug reports can be found in next tabs:
+
+.. tabs::
+
+ .. tab:: Python
+
+ The ``print`` method of a timestamp with timezone errors:
+
+ .. code-block:: python
+
+ import pyarrow as pa
+
+ a = pa.array([0], pa.timestamp('s', tz='+02:00'))
+
+ print(a) # representation not correct?
+ # <pyarrow.lib.TimestampArray object at 0x7f834c7cb9a8>
+ # [
+ # 1970-01-01 00:00:00
+ # ]
+
+ print(a[0])
+ #Traceback (most recent call last):
+ # File "<stdin>", line 1, in <module>
+ # File "pyarrow/scalar.pxi", line 80, in pyarrow.lib.Scalar.__repr__
+ # File "pyarrow/scalar.pxi", line 463, in
pyarrow.lib.TimestampScalar.as_py
+ # File "pyarrow/scalar.pxi", line 393, in
pyarrow.lib._datetime_from_int
+ #ValueError: fromutc: dt.tzinfo is not self
+
+ .. tab:: R
+
+ Error when reading a CSV file with ``col_types`` option ``"T"`` or
``"t"``:
+
+ .. code-block:: R
+
+ library(arrow)
+ #>
+ #> Attaching package: 'arrow'
+ #> The following object is masked from 'package:utils':
+ #>
+ #> timestamp
Review comment:
```suggestion
library(arrow, warn.conflicts = FALSE)
```
Just tidying up a bit of extra unnecessary output.
##########
File path: docs/source/developers/bug_reports.rst
##########
@@ -0,0 +1,206 @@
+.. 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.
+
+.. _bug-reports:
+
+********************************
+Report bugs and propose features
+********************************
+
+Using the software and sharing your experience is a very helpful contribution
+itself. Those who actively develop Arrow need feedback from users on what
+works and what doesn't. Alerting us to unexpected behavior and missing
features,
+even if you can't solve the problems yourself, help us understand and
prioritize
+work to improve the libraries.
+
+We use `JIRA <https://issues.apache.org/jira/projects/ARROW/issues>`_
+to manage our development "todo" list and to maintain changelogs for releases.
+In addition, the project's `Confluence site
<https://cwiki.apache.org/confluence/display/ARROW>`_
+has some useful higher-level views of the JIRA issues.
+
+To create a JIRA issue, you'll need to have an account on the ASF JIRA, which
+you can `sign yourself up for
<https://issues.apache.org/jira/secure/Signup!default.jspa>`_.
+The JIRA server hosts bugs and issues for multiple Apache projects. The JIRA
+project name for Arrow is "ARROW".
+
+You don't need any special permissions on JIRA to be able to create issues.
+Once you are more involved in the project and want to do more on JIRA, such as
+assign yourself an issue, you will need "Contributor" permissions on the
+Apache Arrow JIRA. To get this role, ask on the mailing list for a project
+maintainer's help.
+
+
+.. _jira-tips:
+
+Tips for using JIRA
+===================
+
+Before you create a new issue, we recommend you first
+`search
<https://issues.apache.org/jira/issues/?jql=project%20%3D%20ARROW%20AND%20resolution%20%3D%20Unresolved>`_
+among existing Arrow issues.
+
+When reporting a new issue, follow these conventions to help make sure the
+right people see it:
+
+* Use the **Component** field to indicate the area of the project that your
+ issue pertains to (for example "Python" or "C++").
+* Also prefix the issue title with the component name in brackets, for example
+ ``[Python] issue name`` ; this helps when navigating lists of open issues,
+ and it also makes our changelogs more readable. Most prefixes are exactly
the
+ same as the **Component** name, with the following exceptions:
+
+ * **Component:** Continuous Integration — **Summary prefix:** [CI]
+ * **Component:** Developer Tools — **Summary prefix:** [Dev]
+ * **Component:** Documentation — **Summary prefix:** [Docs]
+
+* 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.
+
+.. _bug-report-tips:
+
+Tips for successful bug reports
+================================
+
+No one likes having bugs in their software, and in an ideal world, all bugs
+would get fixed as soon as they were reported. However, time and attention are
+finite, especially in an open-source project where most contributors are
+participating in their spare time. All contributors in Apache projects are
+volunteers and act as individuals, even if they are contributing to the project
+as part of their job responsibilities.
+
+In order for your bug to get prompt
+attention, there are things you can do to make it easier for contributors to
+reproduce and fix it.
+**When you're reporting a bug, please help us understand the issue by
providing,
+to the best of your ability,**
+
+* **Clear, minimal steps to reproduce the issue, with as few non-Arrow
+ dependencies as possible.** If there's a problem on reading a file, try to
+ provide as small of an example file as possible, or code to create one.
+ If your bug report says "it crashes trying to read my file, but I can't
+ share it with you," it's really hard for us to debug.
+* Any relevant operating system, language, and library version information
+* If it isn't obvious, clearly state the expected behavior and what actually
+ happened.
+
+If a developer can't get a failing unit test, they won't be able to know that
+the issue has been identified, and they won't know when it has been fixed.
+Try to anticipate the questions you might be asked by someone working to
+understand the issue and provide those supporting details up front.
+
+Good reproducible examples or minimal bug reports can be found in next tabs:
+
+.. tabs::
+
+ .. tab:: Python
+
+ The ``print`` method of a timestamp with timezone errors:
+
+ .. code-block:: python
+
+ import pyarrow as pa
+
+ a = pa.array([0], pa.timestamp('s', tz='+02:00'))
+
+ print(a) # representation not correct?
+ # <pyarrow.lib.TimestampArray object at 0x7f834c7cb9a8>
+ # [
+ # 1970-01-01 00:00:00
+ # ]
+
+ print(a[0])
+ #Traceback (most recent call last):
+ # File "<stdin>", line 1, in <module>
+ # File "pyarrow/scalar.pxi", line 80, in pyarrow.lib.Scalar.__repr__
+ # File "pyarrow/scalar.pxi", line 463, in
pyarrow.lib.TimestampScalar.as_py
+ # File "pyarrow/scalar.pxi", line 393, in
pyarrow.lib._datetime_from_int
+ #ValueError: fromutc: dt.tzinfo is not self
+
+ .. tab:: R
+
+ Error when reading a CSV file with ``col_types`` option ``"T"`` or
``"t"``:
Review comment:
```suggestion
Error when reading a CSV file with ``col_types`` option ``"T"`` or
``"t"`` when source data is in millisecond precision:
```
I reckon that bug title could be even better :)
--
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]
