[arrow] branch master updated: ARROW-16373: [Docs][CI] Small improvements to CI documentation

[jo...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

jonkeane 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 e0061bbb8c ARROW-16373: [Docs][CI] Small improvements to CI documentation
e0061bbb8c is described below

commit e0061bbb8cd269f4e8b880d1a4ba181312cbc07f
Author: Dragoș Moldovan-Grünfeld <dr...@gmail.com>
AuthorDate: Wed Apr 27 17:24:47 2022 -0500

    ARROW-16373: [Docs][CI] Small improvements to CI documentation
    
    Closes #12989 from dragosmg/patch-1
    
    Authored-by: Dragoș Moldovan-Grünfeld <dr...@gmail.com>
    Signed-off-by: Jonathan Keane <jk...@gmail.com>
---
 .../developers/continuous_integration/overview.rst     | 14 +++++++-------
 .../developers/guide/step_by_step/arrow_codebase.rst   | 12 ++++++------
 .../developers/guide/step_by_step/pr_lifecycle.rst     | 18 +++++++++---------
 r/vignettes/developers/workflow.Rmd                    |  4 ++--
 4 files changed, 24 insertions(+), 24 deletions(-)

diff --git a/docs/source/developers/continuous_integration/overview.rst b/docs/source/developers/continuous_integration/overview.rst
index 73aef370cd..3c21c17063 100644
--- a/docs/source/developers/continuous_integration/overview.rst
+++ b/docs/source/developers/continuous_integration/overview.rst
@@ -31,18 +31,18 @@ Some files central to Arrow CI are:
 
 We use :ref:`Docker<docker-builds>` in order to have portable and reproducible Linux builds, as well as running Windows builds in Windows containers.  We use :ref:`Archery<Archery>` and :ref:`Crossbow<Crossbow>` to help co-ordinate the various CI tasks.
 
-One thing to note is the some of the services defined in ``docker-compose.yml`` are interdependent.  When running services locally, you must either manually build its dependencies first, or build it via the use of ``archery run ...`` which automatically finds and builds dependencies. 
+One thing to note is the some of the services defined in ``docker-compose.yml`` are interdependent.  When running services locally, you must either manually build its dependencies first, or build it via the use of ``archery run ...`` which automatically finds and builds dependencies.
 
 There are numerous important directories in the Arrow project which relate to CI:
 
 - ``.github/worflows`` - workflows that are run via GitHub actions and are triggered by things like pull requests being submitted or merged
-- ``dev/tasks`` - containing on-demand jobs triggered/submitted via ``archery crossbow submit ...``, typically nightly builds or relating to the release process
+- ``dev/tasks`` - containing extended jobs triggered/submitted via ``archery crossbow submit ...``, typically nightly builds or relating to the release process
 - ``ci/`` - containing scripts, dockerfiles, and any supplemental files, e.g. patch files, conda environment files, vcpkg triplet files.
 
 Instead of thinking about Arrow CI in terms of files and folders, it may be conceptually simpler to instead divide it into 2 main categories:
 
-- CI jobs which are triggered based on specific actions on GitHub (pull requests opened, pull requests merged, etc)
-- On-demand builds which are manually triggered on a nightly basis or via Archery
+- **action-triggered builds**: CI jobs which are triggered based on specific actions on GitHub (pull requests opened, pull requests merged, etc)
+- **extended builds**: manually triggered with many being run on a nightly basis
 
 Action-triggered builds
 -----------------------
@@ -61,9 +61,9 @@ The ``.yml`` files in ``.github/worflows`` are workflows which are run on GitHub
 There are two other files which define action-triggered builds:
 
 - ``.travis.yml`` - runs on all commits and is used to test on architectures such as ARM and S390x
-- ``appveyor.yml`` - runs on commits related to Python or C++ 
+- ``appveyor.yml`` - runs on commits related to Python or C++
 
-On-demand builds
+Extended builds
 -----------------------
 
 Crossbow is a subcomponent of Archery and can be used to manually trigger builds.  The tasks which can be run on Crossbow can be found in the ``dev/tasks`` directory.  This directory contains:
@@ -73,4 +73,4 @@ Crossbow is a subcomponent of Archery and can be used to manually trigger builds
 
 Most of these tasks are run as part of the nightly builds, though also can be triggered manually by add a comment to a PR which begins with ``@github-actions crossbow submit`` followed by the name of the task to be run.
 
-For convenience purpose, the tasks in ``dev/tasks/tasks.yml`` are defined in groups, which makes it simpler for multiple tasks to be submitted to Crossbow at once.  The task definitions here contain information about which service defined in ``docker-compose.yml`` to run, the CI service to run the task on, and which template file to use as the basis for that task.
\ No newline at end of file
+For convenience purpose, the tasks in ``dev/tasks/tasks.yml`` are defined in groups, which makes it simpler for multiple tasks to be submitted to Crossbow at once.  The task definitions here contain information about which service defined in ``docker-compose.yml`` to run, the CI service to run the task on, and which template file to use as the basis for that task.
diff --git a/docs/source/developers/guide/step_by_step/arrow_codebase.rst b/docs/source/developers/guide/step_by_step/arrow_codebase.rst
index 82e5c87eb7..0250434ffe 100644
--- a/docs/source/developers/guide/step_by_step/arrow_codebase.rst
+++ b/docs/source/developers/guide/step_by_step/arrow_codebase.rst
@@ -62,7 +62,7 @@ Other subdirectories included in the arrow repository are:
   integration (CI) jobs.
 - ``dev/`` contains scripts useful to developers when packaging,
   testing, or committing to Arrow, as well as definitions for
-  on-demand continuous integration (CI) tasks.
+  extended continuous integration (CI) tasks.
 - ``.github/`` contains workflows run on GitHub continuous
   integration (CI), triggered by certain actions such as opening a PR.
 - ``docs/`` contains most of the documentation. Read more on
@@ -80,7 +80,7 @@ to work around the library on the issue you have.
 
 Depending on the problem you want to solve (adding a simple
 binding, adding a feature, writing a test, …) there are
-different ways to get the necessary information. 
+different ways to get the necessary information.
 
 **For all the cases** you can help yourself with
 searching for functions via some kind of search tool.
@@ -94,13 +94,13 @@ In our experience there are two good ways:
 
 **Bindings**
 
-The term "binding" is used to refer to a function in the C++ implementation which 
+The term "binding" is used to refer to a function in the C++ implementation which
 can be called from a function in another language.  After a function is defined in
 C++ we must create the binding manually to use it in that implementation.
 
 .. note::
 	There is much you can learn by checking **Pull Requests**
-	and **unit tests** for similar issues.  
+	and **unit tests** for similar issues.
 
 .. tab-set::
 
@@ -120,9 +120,9 @@ C++ we must create the binding manually to use it in that implementation.
       likely point you towards the file you need to take a look at.
 
       **Python - Cython - C++**
-       
+
       It is quite likely that you will bump into Cython code when
-      working on Python issues. It's less likely is that the C++ code 
+      working on Python issues. It's less likely is that the C++ code
       needs updating, though it can happen.
 
       As mentioned before, the underlying code is written in C++.
diff --git a/docs/source/developers/guide/step_by_step/pr_lifecycle.rst b/docs/source/developers/guide/step_by_step/pr_lifecycle.rst
index d450966132..fa1e1a47f3 100644
--- a/docs/source/developers/guide/step_by_step/pr_lifecycle.rst
+++ b/docs/source/developers/guide/step_by_step/pr_lifecycle.rst
@@ -62,7 +62,7 @@ branch in Git.**
       $ git checkout -b <branch-name>
 
    or (does the same thing)
-   
+
    .. code:: console
 
       $ git switch --create <branch-name>
@@ -77,7 +77,7 @@ made in the library use this two commands:
 
 .. _create_pr:
 
-Creating a pull request 
+Creating a pull request
 ==========================
 
 Once you are satisfied with the changes, run the :ref:`tests <testing>`
@@ -86,14 +86,14 @@ and :ref:`linters<styling>` and then go ahead and commit the changes.
 3. Add and commit the changes
 
    .. code:: console
-         
+
       $ git add <filenames>
       $ git commit -m "<message>"
 
    Alternatively, you can add and commit in one step, if all the files changed
    are to be committed (-a to add all, -m for message)
-   
-   .. code:: console      
+
+   .. code:: console
 
       $ git commit -am "<message>"
 
@@ -123,7 +123,7 @@ If all is set, you can make the pull request!
    once again the changes you have made.
 
    .. seealso::
-      
+
       Get more details on naming the pull request in Arrow repository
       and other additional information :ref:`pull-request-and-review`
       section.
@@ -170,7 +170,7 @@ Besides the CI jobs that check the changes in GitHub repository
 (opening or merging of a pull request) we also use CI for nightly
 builds and releases of the Apache Arrow library.
 
-Also, on-demand triggering jobs can be used in your pull request for
+Also, extended triggering jobs can be used in your pull request for
 example adding a comment with ``@github-actions crossbow submit python``
 will run PyArrow tests via GitHub actions. These are mostly used to run
 tests on environments that are less common and are normally
@@ -196,7 +196,7 @@ How to get your pull request to be reviewed?
 
 Arrow maintainers will be notified when a pull request is created and
 they will get to it as soon as possible. If days pass and it still had
-not been reviewed go ahead and mention the reporter of the JIRA issue 
+not been reviewed go ahead and mention the reporter of the JIRA issue
 or a developer that you communicated with via JIRA comments, mailing
 list or GitHub.
 
@@ -277,7 +277,7 @@ The steps for updating the pull request would then be as follows:
 .. seealso::
 
    See more about updating the branch (we use ``rebase``, not ``merge``)
-   and squashing local commits in :ref:`git-conventions`. 
+   and squashing local commits in :ref:`git-conventions`.
 
 If the review process is successful your pull request will get merged.
 
diff --git a/r/vignettes/developers/workflow.Rmd b/r/vignettes/developers/workflow.Rmd
index 90b70838c8..b98e82e7b4 100644
--- a/r/vignettes/developers/workflow.Rmd
+++ b/r/vignettes/developers/workflow.Rmd
@@ -184,10 +184,10 @@ R CMD check arrow_*.tar.gz --as-cran
 ```
 
 
-## Running additional CI checks
+## Running extended CI checks
 
 On a pull request, there are some actions you can trigger by commenting on the
-PR. We have additional CI checks that run nightly and can be requested on demand
+PR. These extended CI checks are run nightly and can also be requested on-demand
 using an internal tool called
 [crossbow](https://arrow.apache.org/docs/developers/crossbow.html).
 A few important GitHub comment commands are shown below.