ARROW-6029: [R] Improve R docs on how to fix library version mismatch

ci/PKGBUILD

@@ -18,7 +18,7 @@
 _realname=arrow
 pkgbase=mingw-w64-${_realname}
 pkgname="${MINGW_PACKAGE_PREFIX}-${_realname}"
-pkgver=0.14.0.9000
+pkgver=0.14.1.9000
 pkgrel=8000
 pkgdesc="Apache Arrow is a cross-language development platform for in-memory data (mingw-w64)"
 arch=("any")

r/DESCRIPTION

@@ -1,6 +1,6 @@
 Package: arrow
 Title: Integration to 'Apache' 'Arrow'
-Version: 0.14.0.9000
+Version: 0.14.1.9000
 Authors@R: c(
     person("Romain", "Fran\u00e7ois", email = "romain@rstudio.com", role = c("aut", "cre"), comment = c(ORCID = "0000-0002-2444-4226")),
     person("Jeroen", "Ooms", email = "jeroen@berkeley.edu", role = c("aut")),

r/NEWS.md

@@ -17,9 +17,11 @@
   under the License.
 -->
 
-# arrow 0.14.0.9000
+# arrow 0.14.1.9000
 
-# arrow 0.14.0
+* `read_csv_arrow()` supports more parsing options, including `col_names` and `skip`
+
+# arrow 0.14.1
 
 Initial CRAN release of the `arrow` package. Key features include:
 

r/README.Rmd

@@ -40,6 +40,8 @@ arrow::install_arrow()
 
 for version- and platform-specific guidance on installing the Arrow C++ library.
 
+When installing from source, if the R and C++ library versions do not match, installation may fail. If you've previously installed the libraries and want to upgrade the R package, you'll need to update the Arrow C++ library first.  
+
 ## Example
 
 ```{r}
@@ -80,7 +82,7 @@ or if you prefer to stay at the command line,
 R -e 'remotes::install_github("apache/arrow/r")'
 ```
 
-You can specify a particular commit, branch, or [release](https://github.com/apache/arrow/releases) to install by including a `ref` argument to `install_github()`.
+You can specify a particular commit, branch, or [release](https://github.com/apache/arrow/releases) to install by including a `ref` argument to `install_github()`. This is particularly useful to match the R package version to the C++ library version you've installed.
 
 ## Developing
 
@@ -92,8 +94,8 @@ First, install the C++ library. See the [C++ developer
 guide](https://arrow.apache.org/docs/developers/cpp.html) for details.
 
 Note that after any change to the C++ library, you must reinstall it and run
-`make clean` or `git clean -fdx .` to remove any cached object code in the `r/`
-directory.
+`make clean` or `git clean -fdx .` to remove any cached object code in the `r/src/`
+directory before reinstalling the R package. This is only necessary if you make changes to the C++ library source; you do not need to manually purge object files if you are only editing R or Rcpp code inside `r/`.
 
 Once you've built the C++ library, you can install the R package and its
 dependencies, along with additional dev dependencies, from the git checkout:
@@ -130,7 +132,7 @@ your`~/.Renviron` file to persist across sessions) so that the
 
 The codegen.R script has these dependencies:
 
-```
+```r
 remotes::install_github("romainfrancois/decor")
 install.packages(c("dplyr", "purrr", "glue"))
 ```
@@ -159,4 +161,4 @@ R CMD build --keep-empty-dirs .
 R CMD check arrow_*.tar.gz --as-cran --no-manual
 ```
 
-[1]: https://github.com/apache/arrow/blob/master/docs/source/developers/cpp.rst
+[1]: https://github.com/apache/arrow/blob/master/docs/source/developers/cpp.rst

r/README.md

@@ -44,6 +44,11 @@ arrow::install_arrow()
 for version- and platform-specific guidance on installing the Arrow C++
 library.
 
+When installing from source, if the R and C++ library versions do not
+match, installation may fail. If you’ve previously installed the
+libraries and want to upgrade the R package, you’ll need to update the
+Arrow C++ library first.
+
 ## Example
 
 ``` r
@@ -117,7 +122,9 @@ R -e 'remotes::install_github("apache/arrow/r")'
 
 You can specify a particular commit, branch, or
 [release](https://github.com/apache/arrow/releases) to install by
-including a `ref` argument to `install_github()`.
+including a `ref` argument to `install_github()`. This is particularly
+useful to match the R package version to the C++ library version you’ve
+installed.
 
 ## Developing
 
@@ -130,7 +137,10 @@ guide](https://arrow.apache.org/docs/developers/cpp.html) for details.
 
 Note that after any change to the C++ library, you must reinstall it and
 run `make clean` or `git clean -fdx .` to remove any cached object code
-in the `r/` directory.
+in the `r/src/` directory before reinstalling the R package. This is
+only necessary if you make changes to the C++ library source; you do not
+need to manually purge object files if you are only editing R or Rcpp
+code inside `r/`.
 
 Once you’ve built the C++ library, you can install the R package and its
 dependencies, along with additional dev dependencies, from the git
@@ -168,8 +178,10 @@ generation.
 
 The codegen.R script has these dependencies:
 
-    remotes::install_github("romainfrancois/decor")
-    install.packages(c("dplyr", "purrr", "glue"))
+``` r
+remotes::install_github("romainfrancois/decor")
+install.packages(c("dplyr", "purrr", "glue"))
+```
 
 ### Useful functions