blob: c1e86d5c1636062958532aa6cab441e33a48c87a [file] [log] [blame]
<!DOCTYPE html>
<html lang="en" data-content_root="" >
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />
<title>Reviewing contributions &#8212; Apache Arrow v17.0.0.dev52</title>
<script data-cfasync="false">
document.documentElement.dataset.mode = localStorage.getItem("mode") || "";
document.documentElement.dataset.theme = localStorage.getItem("theme") || "light";
</script>
<!-- Loaded before other Sphinx assets -->
<link href="../_static/styles/theme.css?digest=8d27b9dea8ad943066ae" rel="stylesheet" />
<link href="../_static/styles/bootstrap.css?digest=8d27b9dea8ad943066ae" rel="stylesheet" />
<link href="../_static/styles/pydata-sphinx-theme.css?digest=8d27b9dea8ad943066ae" rel="stylesheet" />
<link href="../_static/vendor/fontawesome/6.5.1/css/all.min.css?digest=8d27b9dea8ad943066ae" rel="stylesheet" />
<link rel="preload" as="font" type="font/woff2" crossorigin href="../_static/vendor/fontawesome/6.5.1/webfonts/fa-solid-900.woff2" />
<link rel="preload" as="font" type="font/woff2" crossorigin href="../_static/vendor/fontawesome/6.5.1/webfonts/fa-brands-400.woff2" />
<link rel="preload" as="font" type="font/woff2" crossorigin href="../_static/vendor/fontawesome/6.5.1/webfonts/fa-regular-400.woff2" />
<link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="../_static/copybutton.css" />
<link rel="stylesheet" type="text/css" href="../_static/design-style.1e8bd061cd6da7fc9cf755528e8ffc24.min.css" />
<link rel="stylesheet" type="text/css" href="../_static/theme_overrides.css" />
<!-- Pre-loaded scripts that we'll load fully later -->
<link rel="preload" as="script" href="../_static/scripts/bootstrap.js?digest=8d27b9dea8ad943066ae" />
<link rel="preload" as="script" href="../_static/scripts/pydata-sphinx-theme.js?digest=8d27b9dea8ad943066ae" />
<script src="../_static/vendor/fontawesome/6.5.1/js/all.min.js?digest=8d27b9dea8ad943066ae"></script>
<script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>
<script src="../_static/doctools.js"></script>
<script src="../_static/sphinx_highlight.js"></script>
<script src="../_static/clipboard.min.js"></script>
<script src="../_static/copybutton.js"></script>
<script src="../_static/design-tabs.js"></script>
<script>DOCUMENTATION_OPTIONS.pagename = 'developers/reviewing';</script>
<script>
DOCUMENTATION_OPTIONS.theme_version = '0.15.2';
DOCUMENTATION_OPTIONS.theme_switcher_json_url = '/docs/_static/versions.json';
DOCUMENTATION_OPTIONS.theme_switcher_version_match = 'dev/';
DOCUMENTATION_OPTIONS.show_version_warning_banner = true;
</script>
<link rel="canonical" href="https://arrow.apache.org/docs/developers/reviewing.html" />
<link rel="icon" href="../_static/favicon.ico"/>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="C++ Development" href="cpp/index.html" />
<link rel="prev" title="Contributing Overview" href="overview.html" />
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<meta name="docsearch:language" content="en"/>
<!-- Matomo -->
<script>
var _paq = window._paq = window._paq || [];
/* tracker methods like "setCustomDimension" should be called before "trackPageView" */
/* We explicitly disable cookie tracking to avoid privacy issues */
_paq.push(['disableCookies']);
_paq.push(['trackPageView']);
_paq.push(['enableLinkTracking']);
(function() {
var u="https://analytics.apache.org/";
_paq.push(['setTrackerUrl', u+'matomo.php']);
_paq.push(['setSiteId', '20']);
var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0];
g.async=true; g.src=u+'matomo.js'; s.parentNode.insertBefore(g,s);
})();
</script>
<!-- End Matomo Code -->
</head>
<body data-bs-spy="scroll" data-bs-target=".bd-toc-nav" data-offset="180" data-bs-root-margin="0px 0px -60%" data-default-mode="">
<a id="pst-skip-link" class="skip-link" href="#main-content">Skip to main content</a>
<div id="pst-scroll-pixel-helper"></div>
<button type="button" class="btn rounded-pill" id="pst-back-to-top">
<i class="fa-solid fa-arrow-up"></i>
Back to top
</button>
<input type="checkbox"
class="sidebar-toggle"
name="__primary"
id="__primary"/>
<label class="overlay overlay-primary" for="__primary"></label>
<input type="checkbox"
class="sidebar-toggle"
name="__secondary"
id="__secondary"/>
<label class="overlay overlay-secondary" for="__secondary"></label>
<div class="search-button__wrapper">
<div class="search-button__overlay"></div>
<div class="search-button__search-container">
<form class="bd-search d-flex align-items-center"
action="../search.html"
method="get">
<i class="fa-solid fa-magnifying-glass"></i>
<input type="search"
class="form-control"
name="q"
id="search-input"
placeholder="Search the docs ..."
aria-label="Search the docs ..."
autocomplete="off"
autocorrect="off"
autocapitalize="off"
spellcheck="false"/>
<span class="search-button__kbd-shortcut"><kbd class="kbd-shortcut__modifier">Ctrl</kbd>+<kbd>K</kbd></span>
</form></div>
</div>
<header class="bd-header navbar navbar-expand-lg bd-navbar">
<div class="bd-header__inner bd-page-width">
<label class="sidebar-toggle primary-toggle" for="__primary">
<span class="fa-solid fa-bars"></span>
</label>
<div class="col-lg-3 navbar-header-items__start">
<div class="navbar-item">
<a class="navbar-brand logo" href="../index.html">
<img src="../_static/arrow.png" class="logo__image only-light" alt="Apache Arrow v17.0.0.dev52 - Home"/>
<script>document.write(`<img src="../_static/arrow-dark.png" class="logo__image only-dark" alt="Apache Arrow v17.0.0.dev52 - Home"/>`);</script>
</a></div>
</div>
<div class="col-lg-9 navbar-header-items">
<div class="me-auto navbar-header-items__center">
<div class="navbar-item">
<nav class="navbar-nav">
<ul class="bd-navbar-elements navbar-nav">
<li class="nav-item">
<a class="nav-link nav-internal" href="../format/index.html">
Specifications
</a>
</li>
<li class="nav-item current active">
<a class="nav-link nav-internal" href="index.html">
Development
</a>
</li>
<li class="nav-item dropdown">
<button class="btn dropdown-toggle nav-item" type="button" data-bs-toggle="dropdown" aria-expanded="false" aria-controls="pst-nav-more-links">
Implementations
</button>
<ul id="pst-nav-more-links" class="dropdown-menu">
<li class="nav-item">
<a class="nav-link dropdown-item nav-internal" href="../c_glib/index.html">
C/GLib
</a>
</li>
<li class="nav-item">
<a class="nav-link dropdown-item nav-internal" href="../cpp/index.html">
C++
</a>
</li>
<li class="nav-item">
<a class="nav-link dropdown-item nav-external" href="https://github.com/apache/arrow/blob/main/csharp/README.md">
C#
</a>
</li>
<li class="nav-item">
<a class="nav-link dropdown-item nav-external" href="https://pkg.go.dev/github.com/apache/arrow/go/v17">
Go
</a>
</li>
<li class="nav-item">
<a class="nav-link dropdown-item nav-internal" href="../java/index.html">
Java
</a>
</li>
<li class="nav-item">
<a class="nav-link dropdown-item nav-internal" href="../js/index.html">
JavaScript
</a>
</li>
<li class="nav-item">
<a class="nav-link dropdown-item nav-external" href="https://arrow.apache.org/julia/">
Julia
</a>
</li>
<li class="nav-item">
<a class="nav-link dropdown-item nav-external" href="https://github.com/apache/arrow/blob/main/matlab/README.md">
MATLAB
</a>
</li>
<li class="nav-item">
<a class="nav-link dropdown-item nav-external" href="https://arrow.apache.org/nanoarrow/">
nanoarrow
</a>
</li>
<li class="nav-item">
<a class="nav-link dropdown-item nav-internal" href="../python/index.html">
Python
</a>
</li>
<li class="nav-item">
<a class="nav-link dropdown-item nav-internal" href="../r/index.html">
R
</a>
</li>
<li class="nav-item">
<a class="nav-link dropdown-item nav-external" href="https://github.com/apache/arrow/blob/main/ruby/README.md">
Ruby
</a>
</li>
<li class="nav-item">
<a class="nav-link dropdown-item nav-external" href="https://docs.rs/crate/arrow/">
Rust
</a>
</li>
<li class="nav-item">
<a class="nav-link dropdown-item nav-internal" href="../status.html">
Implementation Status
</a>
</li>
<li class="nav-item">
<a class="nav-link dropdown-item nav-external" href="https://arrow.apache.org/cookbook/cpp/">
C++ cookbook
</a>
</li>
<li class="nav-item">
<a class="nav-link dropdown-item nav-external" href="https://arrow.apache.org/cookbook/java/">
Java cookbook
</a>
</li>
<li class="nav-item">
<a class="nav-link dropdown-item nav-external" href="https://arrow.apache.org/cookbook/py/">
Python cookbook
</a>
</li>
<li class="nav-item">
<a class="nav-link dropdown-item nav-external" href="https://arrow.apache.org/cookbook/r/">
R cookbook
</a>
</li>
</ul>
</li>
</ul>
</nav></div>
</div>
<div class="navbar-header-items__end">
<div class="navbar-item navbar-persistent--container">
<script>
document.write(`
<button class="btn navbar-btn search-button-field search-button__button" title="Search" aria-label="Search" data-bs-placement="bottom" data-bs-toggle="tooltip">
<i class="fa-solid fa-magnifying-glass"></i>
<span class="search-button__default-text">Search</span>
<span class="search-button__kbd-shortcut"><kbd class="kbd-shortcut__modifier">Ctrl</kbd>+<kbd class="kbd-shortcut__modifier">K</kbd></span>
</button>
`);
</script>
</div>
<div class="navbar-item">
<script>
document.write(`
<div class="version-switcher__container dropdown">
<button id="pst-version-switcher-button-2"
type="button"
class="version-switcher__button btn btn-sm navbar-btn dropdown-toggle"
data-bs-toggle="dropdown"
aria-haspopup="listbox"
aria-controls="pst-version-switcher-list-2"
aria-label="Version switcher list"
>
Choose version <!-- this text may get changed later by javascript -->
<span class="caret"></span>
</button>
<div id="pst-version-switcher-list-2"
class="version-switcher__menu dropdown-menu list-group-flush py-0"
role="listbox" aria-labelledby="pst-version-switcher-button-2">
<!-- dropdown will be populated by javascript on page load -->
</div>
</div>
`);
</script></div>
<div class="navbar-item">
<script>
document.write(`
<button class="btn btn-sm navbar-btn theme-switch-button" title="light/dark" aria-label="light/dark" data-bs-placement="bottom" data-bs-toggle="tooltip">
<span class="theme-switch nav-link" data-mode="light"><i class="fa-solid fa-sun fa-lg"></i></span>
<span class="theme-switch nav-link" data-mode="dark"><i class="fa-solid fa-moon fa-lg"></i></span>
<span class="theme-switch nav-link" data-mode="auto"><i class="fa-solid fa-circle-half-stroke fa-lg"></i></span>
</button>
`);
</script></div>
<div class="navbar-item"><ul class="navbar-icon-links navbar-nav"
aria-label="Icon Links">
<li class="nav-item">
<a href="https://github.com/apache/arrow" title="GitHub" class="nav-link" rel="noopener" target="_blank" data-bs-toggle="tooltip" data-bs-placement="bottom"><span><i class="fa-brands fa-square-github fa-lg" aria-hidden="true"></i></span>
<span class="sr-only">GitHub</span></a>
</li>
<li class="nav-item">
<a href="https://twitter.com/ApacheArrow" title="X" class="nav-link" rel="noopener" target="_blank" data-bs-toggle="tooltip" data-bs-placement="bottom"><span><i class="fa-brands fa-square-x-twitter fa-lg" aria-hidden="true"></i></span>
<span class="sr-only">X</span></a>
</li>
</ul></div>
</div>
</div>
<div class="navbar-persistent--mobile">
<script>
document.write(`
<button class="btn navbar-btn search-button-field search-button__button" title="Search" aria-label="Search" data-bs-placement="bottom" data-bs-toggle="tooltip">
<i class="fa-solid fa-magnifying-glass"></i>
<span class="search-button__default-text">Search</span>
<span class="search-button__kbd-shortcut"><kbd class="kbd-shortcut__modifier">Ctrl</kbd>+<kbd class="kbd-shortcut__modifier">K</kbd></span>
</button>
`);
</script>
</div>
<label class="sidebar-toggle secondary-toggle" for="__secondary" tabindex="0">
<span class="fa-solid fa-outdent"></span>
</label>
</div>
</header>
<div class="bd-container">
<div class="bd-container__inner bd-page-width">
<div class="bd-sidebar-primary bd-sidebar">
<div class="sidebar-header-items sidebar-primary__section">
<div class="sidebar-header-items__center">
<div class="navbar-item">
<nav class="navbar-nav">
<ul class="bd-navbar-elements navbar-nav">
<li class="nav-item">
<a class="nav-link nav-internal" href="../format/index.html">
Specifications
</a>
</li>
<li class="nav-item current active">
<a class="nav-link nav-internal" href="index.html">
Development
</a>
</li>
<li class="nav-item dropdown">
<button class="btn dropdown-toggle nav-item" type="button" data-bs-toggle="dropdown" aria-expanded="false" aria-controls="pst-nav-more-links-2">
Implementations
</button>
<ul id="pst-nav-more-links-2" class="dropdown-menu">
<li class="nav-item">
<a class="nav-link dropdown-item nav-internal" href="../c_glib/index.html">
C/GLib
</a>
</li>
<li class="nav-item">
<a class="nav-link dropdown-item nav-internal" href="../cpp/index.html">
C++
</a>
</li>
<li class="nav-item">
<a class="nav-link dropdown-item nav-external" href="https://github.com/apache/arrow/blob/main/csharp/README.md">
C#
</a>
</li>
<li class="nav-item">
<a class="nav-link dropdown-item nav-external" href="https://pkg.go.dev/github.com/apache/arrow/go/v17">
Go
</a>
</li>
<li class="nav-item">
<a class="nav-link dropdown-item nav-internal" href="../java/index.html">
Java
</a>
</li>
<li class="nav-item">
<a class="nav-link dropdown-item nav-internal" href="../js/index.html">
JavaScript
</a>
</li>
<li class="nav-item">
<a class="nav-link dropdown-item nav-external" href="https://arrow.apache.org/julia/">
Julia
</a>
</li>
<li class="nav-item">
<a class="nav-link dropdown-item nav-external" href="https://github.com/apache/arrow/blob/main/matlab/README.md">
MATLAB
</a>
</li>
<li class="nav-item">
<a class="nav-link dropdown-item nav-external" href="https://arrow.apache.org/nanoarrow/">
nanoarrow
</a>
</li>
<li class="nav-item">
<a class="nav-link dropdown-item nav-internal" href="../python/index.html">
Python
</a>
</li>
<li class="nav-item">
<a class="nav-link dropdown-item nav-internal" href="../r/index.html">
R
</a>
</li>
<li class="nav-item">
<a class="nav-link dropdown-item nav-external" href="https://github.com/apache/arrow/blob/main/ruby/README.md">
Ruby
</a>
</li>
<li class="nav-item">
<a class="nav-link dropdown-item nav-external" href="https://docs.rs/crate/arrow/">
Rust
</a>
</li>
<li class="nav-item">
<a class="nav-link dropdown-item nav-internal" href="../status.html">
Implementation Status
</a>
</li>
<li class="nav-item">
<a class="nav-link dropdown-item nav-external" href="https://arrow.apache.org/cookbook/cpp/">
C++ cookbook
</a>
</li>
<li class="nav-item">
<a class="nav-link dropdown-item nav-external" href="https://arrow.apache.org/cookbook/java/">
Java cookbook
</a>
</li>
<li class="nav-item">
<a class="nav-link dropdown-item nav-external" href="https://arrow.apache.org/cookbook/py/">
Python cookbook
</a>
</li>
<li class="nav-item">
<a class="nav-link dropdown-item nav-external" href="https://arrow.apache.org/cookbook/r/">
R cookbook
</a>
</li>
</ul>
</li>
</ul>
</nav></div>
</div>
<div class="sidebar-header-items__end">
<div class="navbar-item">
<script>
document.write(`
<div class="version-switcher__container dropdown">
<button id="pst-version-switcher-button-3"
type="button"
class="version-switcher__button btn btn-sm navbar-btn dropdown-toggle"
data-bs-toggle="dropdown"
aria-haspopup="listbox"
aria-controls="pst-version-switcher-list-3"
aria-label="Version switcher list"
>
Choose version <!-- this text may get changed later by javascript -->
<span class="caret"></span>
</button>
<div id="pst-version-switcher-list-3"
class="version-switcher__menu dropdown-menu list-group-flush py-0"
role="listbox" aria-labelledby="pst-version-switcher-button-3">
<!-- dropdown will be populated by javascript on page load -->
</div>
</div>
`);
</script></div>
<div class="navbar-item">
<script>
document.write(`
<button class="btn btn-sm navbar-btn theme-switch-button" title="light/dark" aria-label="light/dark" data-bs-placement="bottom" data-bs-toggle="tooltip">
<span class="theme-switch nav-link" data-mode="light"><i class="fa-solid fa-sun fa-lg"></i></span>
<span class="theme-switch nav-link" data-mode="dark"><i class="fa-solid fa-moon fa-lg"></i></span>
<span class="theme-switch nav-link" data-mode="auto"><i class="fa-solid fa-circle-half-stroke fa-lg"></i></span>
</button>
`);
</script></div>
<div class="navbar-item"><ul class="navbar-icon-links navbar-nav"
aria-label="Icon Links">
<li class="nav-item">
<a href="https://github.com/apache/arrow" title="GitHub" class="nav-link" rel="noopener" target="_blank" data-bs-toggle="tooltip" data-bs-placement="bottom"><span><i class="fa-brands fa-square-github fa-lg" aria-hidden="true"></i></span>
<span class="sr-only">GitHub</span></a>
</li>
<li class="nav-item">
<a href="https://twitter.com/ApacheArrow" title="X" class="nav-link" rel="noopener" target="_blank" data-bs-toggle="tooltip" data-bs-placement="bottom"><span><i class="fa-brands fa-square-x-twitter fa-lg" aria-hidden="true"></i></span>
<span class="sr-only">X</span></a>
</li>
</ul></div>
</div>
</div>
<div class="sidebar-primary-items__start sidebar-primary__section">
<div class="sidebar-primary-item">
<nav class="bd-docs-nav bd-links"
aria-label="Section Navigation">
<p class="bd-links__title" role="heading" aria-level="1">Section Navigation</p>
<div class="bd-toc-item navbar-nav"><ul class="current nav bd-sidenav">
<li class="toctree-l1"><a class="reference internal" href="bug_reports.html">Bug reports and feature requests</a></li>
<li class="toctree-l1 has-children"><a class="reference internal" href="guide/index.html">New Contributor’s Guide</a><input class="toctree-checkbox" id="toctree-checkbox-1" name="toctree-checkbox-1" type="checkbox"/><label class="toctree-toggle" for="toctree-checkbox-1"><i class="fa-solid fa-chevron-down"></i></label><ul>
<li class="toctree-l2"><a class="reference internal" href="guide/architectural_overview.html">Architectural Overview</a></li>
<li class="toctree-l2"><a class="reference internal" href="guide/communication.html">Communication</a></li>
<li class="toctree-l2 has-children"><a class="reference internal" href="guide/step_by_step/index.html">Steps in making your first PR</a><input class="toctree-checkbox" id="toctree-checkbox-2" name="toctree-checkbox-2" type="checkbox"/><label class="toctree-toggle" for="toctree-checkbox-2"><i class="fa-solid fa-chevron-down"></i></label><ul>
<li class="toctree-l3"><a class="reference internal" href="guide/step_by_step/set_up.html">Set up</a></li>
<li class="toctree-l3"><a class="reference internal" href="guide/step_by_step/building.html">Building the Arrow libraries 🏋🏿‍♀️</a></li>
<li class="toctree-l3"><a class="reference internal" href="guide/step_by_step/finding_issues.html">Finding good first issues 🔎</a></li>
<li class="toctree-l3"><a class="reference internal" href="guide/step_by_step/arrow_codebase.html">Working on the Arrow codebase 🧐</a></li>
<li class="toctree-l3"><a class="reference internal" href="guide/step_by_step/testing.html">Testing 🧪</a></li>
<li class="toctree-l3"><a class="reference internal" href="guide/step_by_step/styling.html">Styling 😎</a></li>
<li class="toctree-l3"><a class="reference internal" href="guide/step_by_step/pr_lifecycle.html">Lifecycle of a pull request</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="guide/documentation.html">Helping with documentation</a></li>
<li class="toctree-l2 has-children"><a class="reference internal" href="guide/tutorials/index.html">Tutorials</a><input class="toctree-checkbox" id="toctree-checkbox-3" name="toctree-checkbox-3" type="checkbox"/><label class="toctree-toggle" for="toctree-checkbox-3"><i class="fa-solid fa-chevron-down"></i></label><ul>
<li class="toctree-l3"><a class="reference internal" href="guide/tutorials/python_tutorial.html">Python tutorial</a></li>
<li class="toctree-l3"><a class="reference internal" href="guide/tutorials/r_tutorial.html">R tutorials</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="guide/resources.html">Additional information and resources</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="overview.html">Contributing Overview</a></li>
<li class="toctree-l1 current active"><a class="current reference internal" href="#">Reviewing contributions</a></li>
<li class="toctree-l1 has-children"><a class="reference internal" href="cpp/index.html">C++ Development</a><input class="toctree-checkbox" id="toctree-checkbox-4" name="toctree-checkbox-4" type="checkbox"/><label class="toctree-toggle" for="toctree-checkbox-4"><i class="fa-solid fa-chevron-down"></i></label><ul>
<li class="toctree-l2"><a class="reference internal" href="cpp/building.html">Building Arrow C++</a></li>
<li class="toctree-l2"><a class="reference internal" href="cpp/development.html">Development Guidelines</a></li>
<li class="toctree-l2"><a class="reference internal" href="cpp/windows.html">Developing on Windows</a></li>
<li class="toctree-l2"><a class="reference internal" href="cpp/emscripten.html">Cross compiling for WebAssembly with Emscripten</a></li>
<li class="toctree-l2"><a class="reference internal" href="cpp/conventions.html">Conventions</a></li>
<li class="toctree-l2"><a class="reference internal" href="cpp/fuzzing.html">Fuzzing Arrow C++</a></li>
</ul>
</li>
<li class="toctree-l1 has-children"><a class="reference internal" href="java/index.html">Java Development</a><input class="toctree-checkbox" id="toctree-checkbox-5" name="toctree-checkbox-5" type="checkbox"/><label class="toctree-toggle" for="toctree-checkbox-5"><i class="fa-solid fa-chevron-down"></i></label><ul>
<li class="toctree-l2"><a class="reference internal" href="java/building.html">Building Arrow Java</a></li>
<li class="toctree-l2"><a class="reference internal" href="java/development.html">Development Guidelines</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="python.html">Python Development</a></li>
<li class="toctree-l1 has-children"><a class="reference internal" href="continuous_integration/index.html">Continuous Integration</a><input class="toctree-checkbox" id="toctree-checkbox-6" name="toctree-checkbox-6" type="checkbox"/><label class="toctree-toggle" for="toctree-checkbox-6"><i class="fa-solid fa-chevron-down"></i></label><ul>
<li class="toctree-l2"><a class="reference internal" href="continuous_integration/overview.html">Continuous Integration</a></li>
<li class="toctree-l2"><a class="reference internal" href="continuous_integration/docker.html">Running Docker Builds</a></li>
<li class="toctree-l2"><a class="reference internal" href="continuous_integration/archery.html">Daily Development using Archery</a></li>
<li class="toctree-l2"><a class="reference internal" href="continuous_integration/crossbow.html">Packaging and Testing with Crossbow</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="benchmarks.html">Benchmarks</a></li>
<li class="toctree-l1"><a class="reference internal" href="documentation.html">Building the Documentation</a></li>
<li class="toctree-l1"><a class="reference internal" href="release.html">Release Management Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="release_verification.html">Release Verification Process</a></li>
</ul>
</div>
</nav></div>
</div>
<div class="sidebar-primary-items__end sidebar-primary__section">
</div>
<div id="rtd-footer-container"></div>
</div>
<main id="main-content" class="bd-main">
<div class="bd-content">
<div class="bd-article-container">
<div class="bd-header-article">
<div class="header-article-items header-article__inner">
<div class="header-article-items__start">
<div class="header-article-item">
<nav aria-label="Breadcrumb">
<ul class="bd-breadcrumbs">
<li class="breadcrumb-item breadcrumb-home">
<a href="../index.html" class="nav-link" aria-label="Home">
<i class="fa-solid fa-home"></i>
</a>
</li>
<li class="breadcrumb-item"><a href="index.html" class="nav-link">Development</a></li>
<li class="breadcrumb-item active" aria-current="page">Reviewing...</li>
</ul>
</nav>
</div>
</div>
</div>
</div>
<div id="searchbox"></div>
<article class="bd-article">
<section id="reviewing-contributions">
<h1>Reviewing contributions<a class="headerlink" href="#reviewing-contributions" title="Permalink to this heading">#</a></h1>
<section id="principles">
<h2>Principles<a class="headerlink" href="#principles" title="Permalink to this heading">#</a></h2>
<p>Arrow is a foundational project that will need to evolve over many years
or even decades, while serving potentially millions of users. We believe
that being meticulous when reviewing brings greater rewards to the project
than being lenient and aiming for quick merges.</p>
<p>Code reviews like this lead to better quality code, more people who are
engaged with and understand the code being changed, and a generally
healthier project with more room to grow and accommodate emerging needs.</p>
</section>
<section id="guidelines">
<h2>Guidelines<a class="headerlink" href="#guidelines" title="Permalink to this heading">#</a></h2>
<section id="meta">
<h3>Meta<a class="headerlink" href="#meta" title="Permalink to this heading">#</a></h3>
<p><strong>Use your own judgement</strong>. These guidelines are not hard rules.
Committers are expected to have sufficient expertise on their work
areas to be able to adjust their approach based on any concerns they have.</p>
<p>These guidelines are not listed in a particular order and are not intended
to be used as a checklist.</p>
<p>Finally, these guidelines are not exhaustive.</p>
</section>
<section id="scope-and-completeness">
<h3>Scope and completeness<a class="headerlink" href="#scope-and-completeness" title="Permalink to this heading">#</a></h3>
<ul class="simple">
<li><p>Our general policy is to not introduce regressions or merge PRs that require
follow-ons to function correctly (though exceptions to this can be made).
Making necessary changes after a merge is more costly both for the
contributor and the reviewer, but also for other developers who may be
confused if they hit problems introduced by a merged PR.</p></li>
<li><p>What changes are in-scope for a PR and what changes might/could/should be
pushed out of scope and have a follow-up issue created should be determined
in collaboration between the authors and the reviewers.</p></li>
<li><p>When a large piece of functionality is being contributed and it seems
desirable to integrate it piecewise, favour functional cohesion when
deciding how to divide changes (for example, if a filesystem implementation
is being contributed, a first PR may contribute directory metadata
operations, a second PR file reading facilities and a third PR file writing
facilities).</p></li>
</ul>
</section>
<section id="public-api-design">
<h3>Public API design<a class="headerlink" href="#public-api-design" title="Permalink to this heading">#</a></h3>
<ul class="simple">
<li><p>Public APIs should nudge users towards the most desirable constructs.
In other words, if there is a “best” way to do something, it should
ideally also be the most easily discoverable and the most concise to type.
For example, safe APIs should be featured more prominently than
unsafe APIs that may crash or silently produce erroneous results on
invalid input.</p></li>
<li><p>Public APIs should ideally tend to produce readable code. One example
is when multiple options are expected to be added over time: it is better
to try to organize options logically rather than juxtapose them all in
a function’s signature (see for example the CSV reading APIs in
<a class="reference internal" href="../cpp/api/formats.html#cpp-api-csv"><span class="std std-ref">C++</span></a> and <a class="reference internal" href="../python/api/formats.html#py-api-csv"><span class="std std-ref">Python</span></a>).</p></li>
<li><p>Naming is important. Try to ask yourself if code calling the new API
would be understandable without having to read the API docs.
Vague naming should be avoided; inaccurate naming is even worse as it
can mislead the reader and lead to buggy user code.</p></li>
<li><p>Be mindful of terminology. Every project has (explicitly or tacitly) set
conventions about how to name important concepts; steering away from those
conventions increases the cognitive workload both for contributors and
users of the project. Conversely, reusing a well-known term for a different
purpose than usual can also increase the cognitive workload and make
developers’ lives more difficult.</p></li>
<li><p>If you are unsure whether an API is the right one for the task at hand,
it is advisable to mark it experimental, such that users know that it
may be changed over time, while contributors are less wary of bringing
code-breaking improvements. However, experimental APIs should not be
used as an excuse for eschewing basic API design principles.</p></li>
</ul>
</section>
<section id="robustness">
<h3>Robustness<a class="headerlink" href="#robustness" title="Permalink to this heading">#</a></h3>
<ul class="simple">
<li><p>Arrow is a set of open source libraries that will be used in a very wide
array of contexts (including fiddling with deliberately artificial data
at a Jupyter interpreter prompt). If you are writing a public API, make
sure that it won’t crash or produce undefined behaviour on unusual (but
valid) inputs.</p></li>
<li><p>When a non-trivial algorithm is implemented, defensive coding can
be useful to catch potential problems (such as debug-only assertions, if
the language allows them).</p></li>
<li><p>APIs ingesting potentially untrusted data, such as on-disk file formats,
should try to avoid crashing or produce silent bugs when invalid or
corrupt data is fed to them. This can require a lot of care that is
out of the scope of regular code reviews (such as setting up
<a class="reference internal" href="cpp/fuzzing.html#cpp-fuzzing"><span class="std std-ref">fuzz testing</span></a>), but basic checks can still be
suggested at the code review stage.</p></li>
<li><p>When calling foreign APIs, especially system functions or APIs dealing with
input / output, do check for errors and propagate them (if the language
does not propagate errors automatically, such as C++).</p></li>
</ul>
</section>
<section id="performance">
<h3>Performance<a class="headerlink" href="#performance" title="Permalink to this heading">#</a></h3>
<ul>
<li><p>Think about performance, but do not obsess over it. Algorithmic complexity
is important if input size may be “large” (the meaning of large depends
on the context: use your own expertise to decide!). Micro-optimizations
improving performance by 20% or more on performance-sensitive functionality
may be useful as well; lesser micro-optimizations may not be worth the
time spent on them, especially if they lead to more complicated code.</p></li>
<li><p>If performance is important, measure it. Do not satisfy yourself with
guesses and intuitions (which may be founded on incorrect assumptions
about the compiler or the hardware).</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="benchmarks.html#benchmarks"><span class="std std-ref">Benchmarking Arrow</span></a></p>
</div>
</li>
<li><p>Try to avoid trying to trick the compiler/interpreter/runtime by writing
the code in a certain way, unless it’s really important. These tricks
are generally brittle and dependent on platform details that may become
obsolete, and they can make code harder to maintain (a common question
that can block contributors is “what should I do about this weird hack
that my changes would like to remove”?).</p></li>
<li><p>Avoiding rough edges or degenerate behaviour (such as memory blowups when
a size estimate is inaccurately large) may be more important than trying to
improve the common case by a small amount.</p></li>
</ul>
</section>
<section id="documentation">
<h3>Documentation<a class="headerlink" href="#documentation" title="Permalink to this heading">#</a></h3>
<p>These guidelines should ideally apply to both prose documentation and
in-code docstrings.</p>
<ul class="simple">
<li><p>Look for ambiguous / poorly informative wording. For example, <em>“it is an
error if …”</em> is less informative than either <em>“An error is raised if … “</em>
or <em>“Behaviour is undefined if …”</em> (the first phrasing doesn’t tell the
reader what actually <em>happens</em> on such an error).</p></li>
<li><p>When reviewing documentation changes (or prose snippets, in general),
be mindful about spelling, grammar, expression, and concision. Clear
communication is essential for effective collaboration with people
from a wide range of backgrounds, and contributes to better documentation.</p></li>
<li><p>Some contributors do not have English as a native language (and perhaps
neither do you). It is advised to help them and/or ask for external help
if needed.</p></li>
<li><p>Cross-linking increases the global value of documentation. Sphinx especially
has great cross-linking capabilities (including topic references, glossary
terms, API references), so be sure to make use of them!</p></li>
</ul>
</section>
<section id="testing">
<h3>Testing<a class="headerlink" href="#testing" title="Permalink to this heading">#</a></h3>
<ul class="simple">
<li><p>When adding an API, all nominal cases should have test cases. Does a function
allow null values? Then null values should be tested (alongside non-null
values, of course). Does a function allow different input types? etc.</p></li>
<li><p>If some aspect of a functionality is delicate (either by definition or
as an implementation detail), it should be tested.</p></li>
<li><p>Corner cases should be exercised, especially in low-level implementation
languages such as C++. Examples: empty arrays, zero-chunk arrays, arrays
with only nulls, etc.</p></li>
<li><p>Stress tests can be useful, for example to uncover synchronizations bugs
if non-trivial parallelization is being added, or to validate a computational
argument against a slow and straightforward reference implementation.</p></li>
<li><p>A mitigating concern, however, is the overall cost of running the test
suite. Continuous Integration (CI) runtimes can be painfully long and
we should be wary of increasing them too much. Sometimes it is
worthwhile to fine-tune testing parameters to balance the usefulness
of tests against the cost of running them (especially where stress tests
are involved, since they tend to imply execution over large datasets).</p></li>
</ul>
</section>
</section>
<section id="social-aspects">
<h2>Social aspects<a class="headerlink" href="#social-aspects" title="Permalink to this heading">#</a></h2>
<ul class="simple">
<li><p>Reviewing is a communication between the contributor and the reviewer.
Avoid letting questions or comments remain unanswered for too long
(“too long” is of course very subjective, but two weeks can be a reasonable
heuristic). If you cannot allocate time soon, do say it explicitly.
If you don’t have the answer to a question, do say it explicitly.
Saying <em>“I don’t have time immediately but I will come back later,
feel free to ping if I seem to have forgotten”</em> or <em>“Sorry, I am out of
my depth here”</em> is always better than saying nothing and leaving the
other person wondering.</p></li>
<li><p>If you know someone who has the competence to help on a blocking issue
and past experience suggests they may be willing to do so, feel free to
add them to the discussion (for example by gently pinging their GitHub
handle).</p></li>
<li><p>If the contributor has stopped giving feedback or updating their PR,
perhaps they’re not interested anymore, but perhaps also they’re stuck
on some issue and feel unable to push their contribution any further.
Don’t hesitate to ask (<em>“I see this PR hasn’t seen any updates recently,
are you stuck on something? Do you need any help?”</em>).</p></li>
<li><p>If the contribution is genuinely desirable and the contributor is not making
any progress, it is also possible to take it up. Out of politeness,
it is however better to ask the contributor first.</p></li>
<li><p>Some contributors are looking for a quick fix to a specific problem and
don’t want to spend too much time on it. Others on the contrary are eager
to learn and improve their contribution to make it conform to the
project’s standards. The latter kind of contributors are especially
valuable as they may become long-term contributors or even committers
to the project.</p></li>
<li><p>Some contributors may respond <em>“I will fix it later, can we merge anyway?”</em>
when a problem is pointed out to them. Unfortunately, whether the fix will
really be contributed soon in a later PR is difficult to predict or enforce.
If the contributor has previously demonstrated that they are reliable,
it may be acceptable to do as suggested. Otherwise, it is better to
decline the suggestion.</p></li>
<li><p>If a PR is generally ready for merge apart from trivial or uncontroversial
concerns, the reviewer may decide to push changes themselves to the
PR instead of asking the contributor to make the changes.</p></li>
<li><p>Ideally, contributing code should be a rewarding process. Of course,
it will not always be, but we should strive to reduce contributor
frustration while keeping the above issues in mind.</p></li>
<li><p>Like any communication, code reviews are governed by the Apache
<a class="reference external" href="https://www.apache.org/foundation/policies/conduct.html">Code of Conduct</a>.
This applies to both reviewers and contributors.</p></li>
</ul>
</section>
<section id="labelling">
<h2>Labelling<a class="headerlink" href="#labelling" title="Permalink to this heading">#</a></h2>
<p>While reviewing PRs, we should try to identify whether the corresponding issue
needs to be marked with one or both of the following issue labels:</p>
<ul class="simple">
<li><p><strong>Critical Fix</strong>: The change fixes either: (a) a security vulnerability;
(b) a bug that causes incorrect or invalid data to be produced;
or (c) a bug that causes a crash (while the API contract is upheld).
This is intended to mark fixes to issues that may affect users without their
knowledge. For this reason, fixing bugs that cause errors don’t count, since
those bugs are usually obvious. Bugs that cause crashes are considered critical
because they are a possible vector of Denial-of-Service attacks.</p></li>
<li><p><strong>Breaking Change</strong>: The change breaks backwards compatibility in a public API.
For changes in C++, this does not include changes that simply break ABI
compatibility, except for the few places where we do guarantee ABI
compatibility (such as C Data Interface). Experimental APIs are <em>not</em>
exempt from this; they are just more likely to be associated with this tag.</p></li>
</ul>
<p>Breaking changes and critical fixes are separate: breaking changes alter the
API contract, while critical fixes make the implementation align with the
existing API contract. For example, fixing a bug that caused a Parquet reader
to skip rows containing the number 42 is a critical fix but not a breaking change,
since the row skipping wasn’t behavior a reasonable user would rely on.</p>
<p>These labels are used in the release to highlight changes that users ought to be
aware of when they consider upgrading library versions. Breaking changes help
identify reasons when users may wish to wait to upgrade until they have time to
adapt their code, while critical fixes highlight the risk in <em>not</em> upgrading.</p>
<p>In addition, we use the following labels to indicate priority:</p>
<ul class="simple">
<li><p><strong>Priority: Blocker</strong>: Indicates the changes <strong>must</strong> be merged before the next
release can happen. This includes fixes to test or packaging failures that
would prevent the release from succeeding final packaging or verification.</p></li>
<li><p><strong>Priority: Critical</strong>: Indicates issues that are high priority. This is a
superset of issues marked “Critical Fix”, as it also contains certain fixes
to issues causing errors and crashes.</p></li>
</ul>
</section>
<section id="collaborators">
<h2>Collaborators<a class="headerlink" href="#collaborators" title="Permalink to this heading">#</a></h2>
<p>The collaborator role allows users to be given triage role to be able to help triaging
issues. The role allows users to label and assign issues.</p>
<p>A user can ask to become a collaborator or can be proposed by another community member
when they have been collaborating in the project for a period of time. Collaborations
can be but are not limited to: creating PRs, answering questions, creating
issues, reviewing PRs, etcetera.</p>
<p>In order to propose someone as a collaborator you must create a PR adding the user to
the collaborators list on <a class="reference external" href="https://github.com/apache/arrow/blob/main/.asf.yaml">.asf.yaml</a>.
Committers can review the past collaborations for the user and approve.</p>
<p>Collaborators that have been inactive for a period of time can be removed from the
list of collaborators.</p>
</section>
</section>
</article>
<footer class="prev-next-footer">
<div class="prev-next-area">
<a class="left-prev"
href="overview.html"
title="previous page">
<i class="fa-solid fa-angle-left"></i>
<div class="prev-next-info">
<p class="prev-next-subtitle">previous</p>
<p class="prev-next-title">Contributing Overview</p>
</div>
</a>
<a class="right-next"
href="cpp/index.html"
title="next page">
<div class="prev-next-info">
<p class="prev-next-subtitle">next</p>
<p class="prev-next-title">C++ Development</p>
</div>
<i class="fa-solid fa-angle-right"></i>
</a>
</div>
</footer>
</div>
<div class="bd-sidebar-secondary bd-toc"><div class="sidebar-secondary-items sidebar-secondary__inner">
<div class="sidebar-secondary-item">
<div
id="pst-page-navigation-heading-2"
class="page-toc tocsection onthispage">
<i class="fa-solid fa-list"></i> On this page
</div>
<nav class="bd-toc-nav page-toc" aria-labelledby="pst-page-navigation-heading-2">
<ul class="visible nav section-nav flex-column">
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#principles">Principles</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#guidelines">Guidelines</a><ul class="visible nav section-nav flex-column">
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#meta">Meta</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#scope-and-completeness">Scope and completeness</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#public-api-design">Public API design</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#robustness">Robustness</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#performance">Performance</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#documentation">Documentation</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#testing">Testing</a></li>
</ul>
</li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#social-aspects">Social aspects</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#labelling">Labelling</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#collaborators">Collaborators</a></li>
</ul>
</nav></div>
<div class="sidebar-secondary-item">
<div class="tocsection editthispage">
<a href="https://github.com/apache/arrow/edit/main/docs/source/developers/reviewing.rst">
<i class="fa-solid fa-pencil"></i>
Edit on GitHub
</a>
</div>
</div>
</div></div>
</div>
<footer class="bd-footer-content">
</footer>
</main>
</div>
</div>
<!-- Scripts loaded after <body> so the DOM is not blocked -->
<script src="../_static/scripts/bootstrap.js?digest=8d27b9dea8ad943066ae"></script>
<script src="../_static/scripts/pydata-sphinx-theme.js?digest=8d27b9dea8ad943066ae"></script>
<footer class="bd-footer">
<div class="bd-footer__inner bd-page-width">
<div class="footer-items__start">
<div class="footer-item">
<p class="copyright">
© Copyright 2016-2024 Apache Software Foundation.
Apache Arrow, Arrow, Apache, the Apache feather logo, and the Apache Arrow project logo are either registered trademarks or trademarks of The Apache Software Foundation in the United States and other countries.
<br/>
</p>
</div>
<div class="footer-item">
<p class="sphinx-version">
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 6.2.0.
<br/>
</p>
</div>
</div>
<div class="footer-items__end">
<div class="footer-item">
<p class="theme-version">
Built with the <a href="https://pydata-sphinx-theme.readthedocs.io/en/stable/index.html">PyData Sphinx Theme</a> 0.15.2.
</p></div>
</div>
</div>
</footer>
</body>
</html>