Skip to content

GH-35875: [R] Update Readme#40148

Merged
thisisnic merged 7 commits intoapache:mainfrom
dgreiss:gh-35875
Mar 15, 2024
Merged

GH-35875: [R] Update Readme#40148
thisisnic merged 7 commits intoapache:mainfrom
dgreiss:gh-35875

Conversation

@dgreiss
Copy link
Copy Markdown
Contributor

@dgreiss dgreiss commented Feb 19, 2024

Rationale for this change

#35875 #35082 and #32895 make a number of recommendations to update the the Readme

What changes are included in this PR?

Rewording and reorganizing the Readme and sidebar.

Are these changes tested?

n/a

Are there any user-facing changes?

Yes

@amoeba
Copy link
Copy Markdown
Member

amoeba commented Mar 4, 2024

@github-actions crossbow submit preview-docs

@github-actions
Copy link
Copy Markdown

github-actions bot commented Mar 4, 2024

Revision: 787c130

Submitted crossbow builds: ursacomputing/crossbow @ actions-ae307f872e

Task Status
preview-docs GitHub Actions

@github-actions github-actions bot added awaiting committer review Awaiting committer review and removed awaiting review Awaiting review labels Mar 4, 2024
Copy link
Copy Markdown
Member

@amoeba amoeba left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi @dgreiss, thanks for the follow-up PR. A few high-level points:

  • Is it possible at this point to update your PR without all the whitespace changes? It takes extra work to figure out what text actually changed
  • Could the description of Apache Arrow be kept but just put lower down? I don't feel like the README would be too long with it included

@thisisnic
Copy link
Copy Markdown
Member

Thanks for updating this PR @dgreiss!

@amoeba - as this has been so long-running and we have other folks interested in developing the docs further, I suggest we push your suggested changes to this PR ourselves and then merge it.

@amoeba
Copy link
Copy Markdown
Member

amoeba commented Mar 14, 2024

Sounds good @thisisnic, I'll do that today.

@amoeba
Copy link
Copy Markdown
Member

amoeba commented Mar 14, 2024

@thisisnic are you able to edit the PR? I don't think I can. Here's my patch that addresses my comments. This is also available on https://github.com/amoeba/arrow/tree/gh-35875-dgreiss-update-r-readme.

diff --git a/r/README.md b/r/README.md
index 8b6a050055..1f953a8e6f 100644
--- a/r/README.md
+++ b/r/README.md
@@ -12,7 +12,7 @@
 
 The R `{arrow}` package provides access to many of the features of the [Apache Arrow C++ library](https://arrow.apache.org/docs/cpp/index.html) for R users. The goal of arrow is to provide an Arrow C++ backend to `{dplyr}`, and access to the Arrow C++ library through familiar base R and tidyverse functions, or `{R6}` classes.
 
-To learn more about the Apache Arrow project, see the parent documentation of the [Arrow Project](https://arrow.apache.org/). The Arrow project provides functionality for a wide range of data analysis tasks to store, process and move data fast. See the [read/write article](articles/read_write.html) to learn about reading and writing data files, [data wrangling](article/data_wrangling.html) to learn how to use dplyr syntax with arrow objects, and the [function documentation](reference/acero.html) for a full list of supported functions within dplyr queries.
+To learn more about the Apache Arrow project, see the parent documentation of the [Arrow Project](https://arrow.apache.org/). The Arrow project provides functionality for a wide range of data analysis tasks to store, process and move data fast. See the [read/write article](articles/read_write.html) to learn about reading and writing data files, [data wrangling](articles/data_wrangling.html) to learn how to use dplyr syntax with arrow objects, and the [function documentation](reference/acero.html) for a full list of supported functions within dplyr queries.
 
 ## Installation
 
@@ -65,6 +65,18 @@ Additional features include:
 - Fine control over column types to work seamlessly with databases and data warehouses
 - Toolkit for building connectors to other applications and services that use Arrow
 
+## What is Apache Arrow?
+
+Apache Arrow is a cross-language development platform for in-memory and
+larger-than-memory data. It specifies a standardized language-independent
+columnar memory format for flat and hierarchical data, organized for efficient
+analytic operations on modern hardware. It also provides computational libraries
+and zero-copy streaming, messaging, and interprocess communication.
+
+This package exposes an interface to the Arrow C++ library, enabling access to
+many of its features in R. It provides low-level access to the Arrow C++ library
+API and higher-level access through a dplyr backend and familiar R functions.
+
 ## Arrow resources
 
 There are a few additional resources that you may find useful for getting started with arrow:
@@ -85,7 +97,10 @@ the [Apache Arrow Community](https://arrow.apache.org/community/) page.
 If you encounter a bug, please file an issue with a minimal reproducible
 example on [GitHub issues](https://github.com/apache/arrow/issues).
 Log in to your GitHub account, click on **New issue** and select the type of
-@@ -104,11 +92,8 @@ features\*\* section of the [Contributing to Apache
+issue you want to create. Add a meaningful title prefixed with **`[R]`**
+followed by a space, the issue summary and select component **R** from the
+dropdown list. For more information, see the **Report bugs and propose
+features** section of the [Contributing to Apache
 Arrow](https://arrow.apache.org/docs/developers/#contributing) page
 in the Arrow developer documentation.

Co-authored-by: Bryce Mecum <petridish@gmail.com>
@github-actions github-actions bot added awaiting changes Awaiting changes and removed awaiting committer review Awaiting committer review labels Mar 15, 2024
@github-actions github-actions bot added awaiting change review Awaiting change review and removed awaiting changes Awaiting changes labels Mar 15, 2024
@thisisnic
Copy link
Copy Markdown
Member

Thanks @amoeba!

FYI another alternative route that I take when I have had a long day and don't want to have to remind myself how to push to someone else's branch is also to just apply the changes as "suggestions", and then if you're a committer, you should be able to accept those suggestions on the PR.

@thisisnic
Copy link
Copy Markdown
Member

This is ready for merging once CI passes. Thanks very much @dgreiss, the readme is looking a lot more straightforward now! :)

@github-actions github-actions bot added awaiting merge Awaiting merge and removed awaiting change review Awaiting change review labels Mar 15, 2024
@amoeba
Copy link
Copy Markdown
Member

amoeba commented Mar 15, 2024

Ah, that's a nice trick, thanks @thisisnic. Still working on getting that commit bit :)

@thisisnic thisisnic merged commit 54ff758 into apache:main Mar 15, 2024
@thisisnic thisisnic removed the awaiting merge Awaiting merge label Mar 15, 2024
@conbench-apache-arrow
Copy link
Copy Markdown

After merging your PR, Conbench analyzed the 7 benchmarking runs that have been run so far on merge-commit 54ff758.

There was 1 benchmark result indicating a performance regression:

The full Conbench report has more details. It also includes information about 21 possible false positives for unstable benchmarks that are known to sometimes produce them.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[R][Documentation] Improve text in top-level package README

3 participants