apache · raulcd · Jun 19, 2025 · Jun 12, 2025 · Jun 19, 2025 · Jun 19, 2025
diff --git a/.github/workflows/rc.yaml b/.github/workflows/rc.yaml
@@ -87,6 +87,75 @@ jobs:
         run: |
           dev/release/run_rat.sh "${TAR_GZ}"
 
+  docs:
+    name: Documentation
+    needs: target
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: write
+    env:
+      RC: ${{ needs.target.outputs.rc }}
+      VERSION: ${{ needs.target.outputs.version }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          cache: yarn
+          node-version: 20
+      - name: Install dependencies
+        run: |
+          yarn install
+      - name: Build
+        run: |
+          yarn doc
+      - name: Package
+        run: |
+          id="apache-arrow-js-docs-${VERSION}"
+          tar_gz="${id}.tar.gz"
+          mv doc "${id}"
+          tar czf "${tar_gz}" "${id}"
+          sha256sum "${tar_gz}" > "${tar_gz}.sha256"
+          sha512sum "${tar_gz}" > "${tar_gz}.sha512"
+      - name: Upload
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: release-docs
+          path: |
+            apache-arrow-js-docs-*.tar.gz*
+      - name: Prepare for publish
+        run: |
+          need_publish=no
+          branch=
+          if [ "${GITHUB_EVENT_NAME}" = "push" ]; then
+            if [ "${GITHUB_REPOSITORY}" = "apache/arrow-js" ]; then
+              branch=asf-site
+              if [ "${GITHUB_REF_NAME}" = "main" ]; then
+                need_publish=yes
+              fi
+            else
+              branch=gh-pages
+              need_publish=yes
+            fi
+          fi
+          if [ "${need_publish}" = "yes" ]; then
+            ci/scripts/update_docs.sh "${VERSION}" "${branch}"
+          fi
+          echo "NEED_PUBLISH=${need_publish}" >> "${GITHUB_ENV}"
+      - name: Publish
+        if: env.NEED_PUBLISH == 'yes'
+        run: |
+          cd site
+          cp -a ../.asf.yaml ./
+          git add .asf.yaml
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          if [ "$(git diff --cached)" != "" ]; then
+            git commit -m "Update ${GITHUB_SHA}"
+            git push origin "$(git branch --show-current)"
+          fi
+
   packages:
     name: Packages
     runs-on: ubuntu-latest
@@ -153,6 +222,7 @@ jobs:
   upload:
     name: Upload
     needs:
+      - docs
       - target
       - verify
     runs-on: ubuntu-latest

diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml
@@ -56,3 +56,31 @@ jobs:
             --title "Apache Arrow JS ${version}" \
             --verify-tag \
             dists/*
+      - name: Checkout asf-site
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          ref: asf-site
+          path: site
+      - name: Update documentation
+        run: |
+          version=${GITHUB_REF_NAME#v}
+          tar_gz=${PWD}/dists/apache-arrow-js-docs-${version}.tar.gz
+
+          pushd site
+
+          rm -rf current
+          mkdir -p current
+          pushd current
+          tar xf "${tar_gz}" --strip-components=1
+          popd
+          git add current
+
+          rm -rf "${version}"
+          cp -a current "${version}"
+          git add "${version}"
+
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+          git commit -m "Update docs for ${version}"
+          git push origin "$(git branch --show-current)"
diff --git a/DEVELOP.md b/DEVELOP.md
@@ -17,7 +17,9 @@
   under the License.
 -->
 
-# Getting Involved
+# How to develop
+
+## Getting Involved
 
 Even if you do not plan to contribute to Apache Arrow itself or Arrow
 integrations in other projects, we'd be happy to have you involved:
@@ -40,7 +42,7 @@ If you’d like to report a bug but don’t have time to fix it, you can still p
 it on GitHub issues, or email the mailing list
 [dev@arrow.apache.org](http://mail-archives.apache.org/mod_mbox/arrow-dev/)
 
-# The package.json scripts
+## The package.json scripts
 
 We use [yarn](https://yarnpkg.com/) to install dependencies and run scrips.
 
@@ -70,19 +72,19 @@ To run tests directly on the sources without bundling, use the `src` target (e.g
 
 Compiles the documentation with [Typedoc](https://typedoc.org/). Use `yarn doc --watch` to automatically rebuild when the docs change.
 
-# Running the Performance Benchmarks
+## Running the Performance Benchmarks
 
 You can run the benchmarks with `yarn perf`. To print the results to stderr as JSON, add the `--json` flag (e.g. `yarn perf --json 2> perf.json`).
 
 You can change the target you want to test by changing the imports in `perf/index.ts`. Note that you need to compile the bundles with `yarn build` before you can import them.
 
-# Testing Bundling
+## Testing Bundling
 
 The bundles use `apache-arrow` so make sure to build it with `yarn build -t apache-arrow`. To bundle with a variety of bundlers, run `yarn test:bundle` or `yarn gulp bundle`.
 
 Run `yarn gulp bundle:webpack:analyze` to open [Webpack Bundle Analyzer](https://github.com/webpack-contrib/webpack-bundle-analyzer).
 
-# Updating the Arrow format flatbuffers generated code
+## Updating the Arrow format flatbuffers generated code
 
 1. Once generated, the flatbuffers format code needs to be adjusted for our build scripts (assumes `gnu-sed`):
 
@@ -110,6 +112,25 @@ Run `yarn gulp bundle:webpack:analyze` to open [Webpack Bundle Analyzer](https:/
 
 4. Execute `yarn lint` from the `js` directory to fix the linting errors
 
+## How to preview documentation on your fork repository
+
+Our GitHub Actions workflows will create the `gh-pages` branch on your
+fork repository automatically. It's for previewing documentation with
+your changes in a branch.
+
+You need to enable GitHub Pages on your fork repository at
+`https://github.com/${YOUR_GITHUB_ID}/arrow-js/settings/pages`
+manually. Choose the `gh-pages` branch in the "Build and deploy" ->
+"Branch" configuration item and press the "Save" button. We can
+preview documentation by GitHub Pages for your fork repository:
+`https://${YOUR_GITHUB_ID}.github.io/arrow-js/`
+
+Example: https://kou.github.io/arrow-js/
+
+The `gh-pages` branch keeps previews of all branches. We recommend
+that you delete needless branches and merged branches from your fork.
+
+
 [1]: mailto:dev-subscribe@arrow.apache.org
 [2]: https://github.com/apache/arrow/tree/main/format
 [3]: https://github.com/apache/arrow-js/issues

diff --git a/ci/scripts/update_docs.sh b/ci/scripts/update_docs.sh
@@ -0,0 +1,101 @@
+#!/usr/bin/env bash
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+set -exu
+
+version="${1}"
+target_branch="${2}"
+
+html_escape() {
+  # & -> &amp; must be the first substitution
+  sed -e "s/&/&amp;/g" \
+    -e "s/</&lt;/g" \
+    -e "s/>/&gt;/g" \
+    -e "s/\"/&quot;/g" \
+    -e "s/'/&apos;/g"
+}
+
+if ! git fetch origin "${target_branch}"; then
+  git worktree add --orphan -b "${target_branch}" site
+else
+  git worktree add site "origin/${target_branch}"
+fi
+
+tar_gz="${PWD}/apache-arrow-js-docs-${version}.tar.gz"
+
+extract_docs() {
+  local destination="${1}"
+
+  rm -rf "${destination}"
+  mkdir -p "${destination}"
+  pushd "${destination}"
+  tar xf "${tar_gz}" --strip-components=1
+  popd
+  git add "${destination}"
+}
+
+pushd site
+if [ "${target_branch}" = "asf-site" ]; then
+  # Update https://arrow.apache.org/js/main/
+  extract_docs main
+
+  # Create .htaccess
+  cat >.htaccess <<HTACCESS
+RedirectMatch "^/js/$" "/js/current/"
+HTACCESS
+  git add .htaccess
+else
+  # Remove data for nonexistent branches
+  for branch in *; do
+    if [ ! -d "${branch}" ]; then
+      continue
+    fi
+    if ! git fetch origin "${branch}"; then
+      git rm "${branch}"
+    fi
+  done
+
+  # Update the pushed branch
+  extract_docs "${GITHUB_REF_NAME}"
+
+  # Create index.html
+  {
+    echo "<!DOCTYPE html>"
+    echo "<html>"
+    echo "  <head>"
+    echo "    <title>Apache Arrow JS documents</title>"
+    echo "  </head>"
+    echo "  <body>"
+    echo "    <ul>"
+    for branch in *; do
+      if [ ! -d "${branch}" ]; then
+        continue
+      fi
+      escaped_branch="$(echo "${branch}" | html_escape)"
+      echo "      <li>"
+      echo "        <a href=\"${escaped_branch}/\">${escaped_branch}</a>"
+      echo "      </li>"
+    done
+    echo "    </ul>"
+    echo "  </body>"
+    echo "</html>"
+  } >index.html
+  git add index.html
+fi
+popd
diff --git a/dev/release/README.md b/dev/release/README.md
@@ -1,4 +1,4 @@
-<!---
+<!--
   Licensed to the Apache Software Foundation (ASF) under one
   or more contributor license agreements.  See the NOTICE file
   distributed with this work for additional information
@@ -28,7 +28,7 @@
 5. Announce the new release on the mailing list (detailed later)
 6. Announce the new release on social media (detailed later)
 
-### Prepare release environment
+## Prepare release environment
 
 This step is needed only when you act as a release manager the first time.
 
@@ -79,15 +79,15 @@ $ head KEYS
 $ svn ci KEYS
 ```
 
-### Bump version for new release
+## Bump version for new release
 
 Open a PR that bumps version for new release. We must follow [Semantic
 Versioning](https://semver.org/). For example, we must bump major
 version when we have any incompatible changes.
 
 You can proceed to the next step once we merge the opened PR.
 
-### Prepare RC and vote
+## Prepare RC and vote
 
 You can use `dev/release/release_rc.sh`.
 
@@ -116,7 +116,7 @@ $ dev/release/release_rc.sh 1
 The argument of `release_rc.sh` is the RC number. If RC1 has a
 problem, we'll increment the RC number such as RC2, RC3 and so on.
 
-### Publish
+## Publish
 
 We need to do the followings to publish a new release:
 
@@ -140,7 +140,7 @@ $ dev/release/release.sh 1
 Add the release to ASF's report database via [Apache Committee Report
 Helper](https://reporter.apache.org/addrelease.html?arrow).
 
-### Announce the new release on the mailing list
+## Announce the new release on the mailing list
 
 Send an email to "announce@apache.org" from your Apache email, CC'ing
 dev@arrow.apache.org/user@arrow.apache.org.  See an [example
@@ -185,7 +185,7 @@ Regards,
 The Apache Arrow community.
 ```
 
-### Announce the new release on social media
+## Announce the new release on social media
 
 Make a post on our [BlueSky](https://bsky.app/profile/arrow.apache.org) and
 [LinkedIn](https://www.linkedin.com/company/apache-arrow/) accounts. (Ask