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

nealrichardson · fsaintjacques · commit e806f2f778ae · 2019-07-30T16:03:53.000-04:00
Closes apache#4946 from nealrichardson/install-debug-version and squashes the following commits: d86faf4 <Neal Richardson> Merge branch 'install-debug-version' of github.com:nealrichardson/arrow into install-debug-version 23268fb <Neal Richardson> Update PKGBUILD version too 9779c17 <Neal Richardson> Add installation troubleshooting; update version and NEWS.md from previous changes 07fa4db <Neal Richardson> Add installation troubleshooting; update version and NEWS.md from previous changes Authored-by: Neal Richardson <neal.p.richardson@gmail.com> Signed-off-by: François Saint-Jacques <fsaintjacques@gmail.com>
diff --git a/ci/PKGBUILD b/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")
diff --git a/r/DESCRIPTION b/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")),
diff --git a/r/NEWS.md b/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:
 
diff --git a/r/README.Rmd b/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
diff --git a/r/README.md b/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
 
