Skip to content

Commit 3b26565

Browse files
AlenkaFjorisvandenbosscheraulcd
authored
GH-14885: [Docs] Make changes to the New Contrib Guide (Jira -> GitHub) (#14889)
This PR is part of the work to update the documentation as we are moving from Jira issue tracker to GitHub issues: #14822 Closes #14885 * Closes: #14885 Lead-authored-by: Alenka Frim <[email protected]> Co-authored-by: Alenka Frim <[email protected]> Co-authored-by: Joris Van den Bossche <[email protected]> Co-authored-by: Raúl Cumplido <[email protected]> Signed-off-by: Joris Van den Bossche <[email protected]>
1 parent 98d7ff0 commit 3b26565

18 files changed

+90
-203
lines changed

‎docs/source/developers/guide/communication.rst‎

Lines changed: 29 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -52,75 +52,57 @@ Where to get help 👋
5252

5353
For any question you may have or problems you are facing you can write to
5454
user or development :ref:`mailing_list` or you can create an issue on
55-
:ref:`github`.
56-
57-
For searching through the issues, reporting bugs and creating feature
58-
requests or proposals you can use :ref:`jira` issue tracker.
59-
60-
.. _jira:
61-
62-
JIRA
63-
~~~~
64-
65-
When to use JIRA?
66-
67-
- If you want to **report a bug**.
68-
- If you want to **propose a new feature**.
69-
- If you want to **propose a bigger change in the documentation**.
70-
71-
In these cases you can create a JIRA issue and connect with other
72-
contributors in the issue comments. It is good to mention the
73-
way you are planning to solve the issue and have one of the Arrow
74-
developers agree with your basic proposal for fixing it. Better
75-
to ask before you spend too much of your time on something that we
76-
might think is not a good idea.
77-
78-
.. seealso::
79-
80-
- :ref:`create_jira`
81-
- :ref:`creating-issues` and :ref:`bug-report-tips`
82-
83-
- If you want to **solve an issue that is already in JIRA**, you should
84-
connect with other contributors in the issue comments.
85-
86-
JIRA is used to discuss the problem before a Pull Request is possibly made
87-
(how to start, where to search for the solution, etc..).
55+
:ref:`github`. Also use GitHub to search through the issues, report bugs
56+
and create feature requests or proposals.
8857

8958
.. _github:
9059

9160
GitHub
9261
~~~~~~
9362

94-
Further options of communicating are provided through GitHub where the project
63+
Different options of communicating are provided through GitHub where the project
9564
is hosted. What we use are GitHub Issues and Pull Requests.
9665

97-
When to use GitHub?
66+
You can use GitHub issues to:
67+
68+
- **ask questions**,
69+
- **report a bug**,
9870

99-
- If you have **a problem with building** one of the Arrow libraries, you can
100-
create an issue on GitHub and discuss the possible solution (or write to the
101-
user mailing list).
71+
.. seealso::
72+
73+
:ref:`How to make good bug reports and feature requests <bug-reports>`
74+
75+
- **propose a new feature**,
76+
- **propose a bigger change in the documentation**,
77+
- report **a problem with building** one of the Arrow libraries and discuss
78+
the possible solution (or write to the user mailing list).
10279

10380
Making an issue about things you are not sure about may feel intimidating,
10481
but it is also useful for others and the project.
10582

10683
.. note::
107-
Make sure to add which operating system and Arrow version you are using in the
108-
issue description plus the debug information/error.
84+
Make sure to add which operating system and Arrow version you are using
85+
in the issue description plus the debug information/error.
86+
87+
If you have **a new contribution already written**, you can create a Pull
88+
Request after creating a GitHub issue and mentioning the way you plan to
89+
implement it. It is important to have one of the Arrow developers agree with
90+
your basic proposal for fixing it. Better to ask before you spend too much of
91+
your time on something that we might think is not a good idea.
10992

110-
- If you have **a new contribution already written**, you can create a Pull Request after
111-
creating a JIRA ticket and mentioning the way you plan to implement it.
112-
- GitHub is also used to discuss your work after the **Pull Request** is made.
93+
If you want to **solve an issue that is already in GitHub**, you should
94+
connect with other contributors in the issue comments.
11395

11496
.. _mailing_list:
11597

11698
Mailing Lists
11799
~~~~~~~~~~~~~
118100

119101
You can subscribe to the **user** or **development** mailing list and browse for
120-
previous topics or ask questions. Whereas discussion on GitHub and JIRA
121-
only notifies people who have subscribed to that particular Pull Request or issue,
122-
the mailing list allows you to broadcast to all users or developers. Use these when
123-
you want to get feedback or answers from a wider audience.
102+
previous topics or ask questions. Whereas discussion on GitHub only notifies people
103+
who are mentioned or are collaborating on a Pull Request, the mailing list allows
104+
you to broadcast to all users or developers. Use these when you want to get feedback
105+
or answers from a wider audience.
124106

125107
There is also a **biweekly developers sync call** that anyone is welcome to join.
126108
It is announced on the development mailing list together with the link to join.

‎docs/source/developers/guide/documentation.rst‎

Lines changed: 6 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -37,26 +37,15 @@ incomplete or inaccurate, share your hard-earned knowledge
3737
with the rest of the community.
3838

3939
If you didn't come across something to improve in the
40-
documentation itself, you can search for an issue on JIRA.
40+
documentation itself, you can search for an issue in GitHub.
4141

4242
.. note::
43-
When searching for JIRA issue that deals with documentation,
44-
try selecting **Components** from the **More** tab in JIRA search
45-
and select **Documentation** from the list.
43+
When searching for an issue that deals with documentation,
44+
navigate to `GitHub labels <https://github.com/apache/arrow/labels>`_
45+
and select **Component: Documentation** or search for **Documentation**
46+
in the "Search all labels" window.
4647

47-
See `Example search. <https://issues.apache.org/jira/issues/?jql=project%20%3D%20ARROW%20AND%20status%20%3D%20Open%20AND%20resolution%20%3D%20Unresolved%20AND%20component%20%3D%20Documentation%20AND%20assignee%20in%20(EMPTY)%20ORDER%20BY%20priority%20DESC%2C%20updated%20DESC>`_
48-
49-
.. figure:: /developers/images/jira_search_component.jpeg
50-
:scale: 40 %
51-
:alt: selecting Components in JIRA search
52-
53-
First select Components tab in JIRA.
54-
55-
.. figure:: /developers/images/jira_search_documentation.jpeg
56-
:scale: 40 %
57-
:alt: selecting Documentation in JIRA search
58-
59-
Then choose Documentation from the Components list.
48+
See `Example search. <https://github.com/apache/arrow/issues?q=is%3Aopen+is%3Aissue+label%3A%22Component%3A+Documentation%22+>`_
6049

6150
Documentation improvements are also a great way to gain some
6251
experience with our submission and review process without

‎docs/source/developers/guide/index.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -128,7 +128,7 @@ of adding a basic feature.
128128

129129
Communication is very important. You may need some help solving problems
130130
you encounter on the way (this happens to developers all the time). Also,
131-
if you have a JIRA issue you want to solve, then it is advisable to let the team
131+
if you have a GitHub issue you want to solve, then it is advisable to let the team
132132
know you are working on it and may need some help.
133133

134134
See possible channels of :ref:`communication`.

‎docs/source/developers/guide/step_by_step/arrow_codebase.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -128,7 +128,7 @@ C++ we must create the binding manually to use it in that implementation.
128128
As mentioned before, the underlying code is written in C++.
129129
Python then connects to it via Cython. If you
130130
are not familiar with it you can ask for help and remember,
131-
**look for similar Pull Requests and JIRA issues!**
131+
**look for similar Pull Requests and GitHub issues!**
132132

133133
**Adding tests**
134134

‎docs/source/developers/guide/step_by_step/finding_issues.rst‎

Lines changed: 22 additions & 75 deletions
Original file line numberDiff line numberDiff line change
@@ -18,11 +18,11 @@
1818
1919
.. SCOPE OF THIS SECTION
2020
.. This section should include additional information
21-
.. about JIRA, how to find issues or how to create one.
21+
.. about GitHub, how to find issues or how to create one.
2222
.. Should not duplicate with Report bugs and propose features
2323
.. section:
2424
25-
.. https://arrow.apache.org/docs/developers/contributing.html#tips-for-using-jira
25+
.. https://arrow.apache.org/docs/developers/bug_reports.html#bug-reports
2626
2727
2828
.. _finding-issues:
@@ -38,103 +38,50 @@ you might already have a bug to fix in mind, or a new feature that
3838
you want to implement. Or you still need an issue to work on and
3939
you need some help with finding one.
4040

41-
For both cases, JIRA is the issue tracker that we use.
41+
For both cases, GitHub is the issue tracker that we use.
4242

43-
First we will explain how to use JIRA if you have a fix or a feature
44-
to work on that doesn't yet have a JIRA ticket open, in which case you
45-
will need to create a JIRA ticket yourself.
43+
- If you do not have a GitHub account yet, navigate to the
44+
`GitHub login page <https://github.com/join>`_ to create one.
45+
- If you need help with creating a new GitHub issue see the
46+
`GitHub documentation <https://docs.github.com/en/issues/tracking-your-work-with-issues/creating-an-issue>`_.
4647

47-
Secondly, we will show you a way to find good first issues to work on.
48+
When the ticket is created you can start a discussion about it in the GitHub comments.
4849

49-
50-
Creating a JIRA account
51-
==========================
52-
53-
First thing you need to do is to make an account on the ASF JIRA following
54-
`this link <https://issues.apache.org/jira/secure/Signup!default.jspa>`_.
55-
You will be asked to select a language and choose an avatar if you wish. If
56-
the registration is successful you will see:
57-
58-
.. figure:: /developers/images/jira_new_account.jpeg
59-
:scale: 70 %
60-
:alt: creating an ASF JIRA account
61-
62-
The window you get after creating an account on the ASF JIRA.
63-
64-
65-
.. _create_jira:
66-
67-
How to create a JIRA issue
68-
==========================
69-
70-
After creating an account you can click **Create an issue** and select
71-
**Apache Arrow project** and **Type** of the issue (Bug, Feature, …).
72-
73-
.. figure:: /developers/images/jira_create_issue.jpeg
74-
:scale: 70 %
75-
:alt: creating JIRA issue
76-
77-
The window to create a JIRA issue.
78-
79-
If you are already in JIRA dashboard click the red ``create`` button in
80-
the top to do the same.
81-
82-
You are ready to create the issue! Add a title and a description following
83-
the guidance in :ref:`creating issues <creating-issues>` and you are ready to go!
84-
85-
.. seealso::
86-
:ref:`Creating issues <creating-issues>`
87-
88-
You don’t need any special permissions on JIRA to be able to create
89-
or self-assign issues.
90-
To get this role, ask on the :ref:`dev mailing list <mailing_list>`.
91-
92-
When the ticket is created you can start a discussion about it in the
93-
JIRA comments section.
94-
95-
How we use JIRA to find an issue
96-
================================
50+
GitHub labels
51+
=============
9752

9853
To make it easier for you to find issues that are well-suited for new
99-
contributors, we have added labels like “good-first-issue” or “beginner”
100-
to some JIRA tickets.
54+
contributors, we have added a label **“good-first-issue”** to some
55+
GitHub issues.
10156

10257
.. seealso::
103-
Search for good first/second issues with labels like in the `link here
104-
<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>`_
58+
Search for good first issues `good-first-issue label listing
59+
<https://github.com/apache/arrow/labels/good-first-issue>`_
10560

10661
The issues labeled as good first issues should take no more than two days or
10762
a weekend to fix them. Once you dig into the code you may find that the issue
10863
is not easy at all - this can happen as the problem could be harder than the
10964
person who triaged the ticket expected it to be. Don't hesitate to write that
11065
in the comments.
11166

112-
.. figure:: /developers/images/jira_good_first_issue.jpeg
113-
:scale: 45 %
114-
:alt: finding good first JIRA issue
115-
116-
Example of the list of good first issues.
117-
11867
.. note::
11968

120-
When you find a JIRA issue you would like to work on, please mention your
121-
interest in the comment section of that issue; that way we will know you
122-
are working on it.
69+
When you find a GitHub issue you would like to work on, please mention
70+
your interest in the comment section of that issue; that way we will know
71+
you are working on it.
12372

124-
Also, do not hesitate to ask questions in the comment section of the issue.
125-
You can get some pointers about where to start and similar issues already solved.
73+
Also, do not hesitate to ask questions in the comment. You can get some
74+
pointers about where to start and similar issues already solved.
12675

12776
**What if an issue is already asigned?**
128-
Anything that’s not in the “In Progress” state is fair game, even if it is
129-
“Assigned” to someone, particularly if it has not been recently updated.
13077
When in doubt, comment on the issue asking if they mind if you try to put
13178
together a pull request; interpret no response to mean that you’re free to
13279
proceed.
13380

13481
**Ask questions**
135-
Please do ask questions, either on the JIRA itself or on the dev mailing list,
136-
if you have doubts about where to begin or what approach to take.
137-
This is particularly a good idea if this is your first code contribution,
82+
Please do ask questions, either on the GitHub issue itself or on the dev
83+
mailing list, if you have doubts about where to begin or what approach to
84+
take. This is particularly a good idea if this is your first code contribution,
13885
so you can get some sense of what the core developers in this part of the
13986
project think a good solution looks like. For best results, ask specific,
14087
direct questions, such as:

‎docs/source/developers/guide/step_by_step/pr_lifecycle.rst‎

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,7 @@ the official Arrow repository which is saved in your set up as
3838
``upstream``.
3939

4040
You should have Git set up by now, have cloned the repository,
41-
have successfully built Arrow and have a JIRA issue to work on.
41+
have successfully built Arrow and have a GitHub issue to work on.
4242

4343
**Before making changes to the code, you should create a new
4444
branch in Git.**
@@ -189,16 +189,15 @@ that supports quality and with it you can learn a lot.
189189

190190
If it still takes too long to get merged, do not hesitate to remind
191191
maintainers in the comment section of the pull request and post
192-
reminders on the JIRA ticket also.
192+
reminders on the GitHub issue also.
193193

194194
How to get your pull request to be reviewed?
195195
--------------------------------------------
196196

197197
Arrow maintainers will be notified when a pull request is created and
198198
they will get to it as soon as possible. If days pass and it still had
199-
not been reviewed go ahead and mention the reporter of the JIRA issue
200-
or a developer that you communicated with via JIRA comments, mailing
201-
list or GitHub.
199+
not been reviewed go ahead and mention the reporter of the GitHub issue
200+
or a developer that you communicated with via mailing list or GitHub.
202201

203202
To put a **mention** in GitHub insert @ in the comment and select the
204203
username from the list.

0 commit comments

Comments
 (0)