(texera) 01/01: docs(bin): document scripts and subdirectories in README (#6013)

[gi...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

github-merge-queue[bot] pushed a commit to branch gh-readonly-queue/main/pr-6013-e5b928f73b5f59b3bf0b25bcbb4b2bb90448d1b1
in repository https://gitbox.apache.org/repos/asf/texera.git

commit 7de1803ff806cf4f3d9a49598daec7833994a9e8
Author: Yicong Huang <17...@users.noreply.github.com>
AuthorDate: Sun Jun 28 18:29:15 2026 -0700

    docs(bin): document scripts and subdirectories in README (#6013)
    
    ### What changes were proposed in this PR?
    
    `bin/README.md` previously only documented the Dockerfiles and
    image-based deployment, leaving most of the directory undocumented. This
    PR expands it into a map of the whole `bin/` directory, grouped by
    purpose:
    
    - **Local development** — `local-dev.sh`
    - **Deployment** — `single-node.sh`, `k8s/`
    - **Docker images** — `dockerfiles/`, `build-images.sh`,
    `merge-image-tags.sh`
    - **Code generation & formatting** — `frontend-proto-gen.sh`,
    `python-proto-gen.sh`, `fix-format.sh`, `protoc-version.txt`
    - **Benchmarks** — `run-benchmarks.sh`
    - **Licensing** — `licensing/`
    - **Other components & configuration** — `bootstrap-lakekeeper.sh`,
    `utils/`, `pylsp/`, `y-websocket-server/`, `forum/`,
    `config.php`/`.htaccess`, `litellm-config.yaml`
    
    Entry points link out to the existing per-subdir READMEs. Docs-only
    change; reflects the recent move of Dockerfiles into `bin/dockerfiles/`
    (#6006).
    
    ### Any related issues, documentation, discussions?
    
    Closes #6012
    
    ### How was this PR tested?
    
    Docs-only change; no tests. Verified the described scripts and
    subdirectories exist under `bin/` and that the relative README links
    resolve.
    
    ### Was this PR authored or co-authored using generative AI tooling?
    
    Generated-by: Claude Code (Claude Opus 4.8)
---
 bin/README.md | 68 +++++++++++++++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 59 insertions(+), 9 deletions(-)

diff --git a/bin/README.md b/bin/README.md
index 620794ad89..7ffcf0b782 100644
--- a/bin/README.md
+++ b/bin/README.md
@@ -1,21 +1,71 @@
-# Texera Deployment
+# `bin/`
 
-This directory contains Dockerfiles and configuration files for building and deploying Texera's microservices.
+This directory holds the scripts, Dockerfiles, and configuration used to
+develop, build, and deploy Texera. Most scripts expect to be run **from the
+`texera` project root** (the parent of this directory).
 
-## Dockerfiles
+## Local development
 
-`bin/dockerfiles/` collects the per-service Dockerfiles, e.g. `file-service.dockerfile` and `computing-unit-master.dockerfile`. Each Dockerfile builds a specific Texera microservice. All Dockerfiles must be built from the `texera` project root as the Docker build context.
+| Entry point | Purpose |
+| --- | --- |
+| `local-dev.sh` | Single entry point for the local dev stack — brings infra up/down in Docker while backend, frontend, and agent-service run natively. Run `bin/local-dev.sh --help`. Implementation lives in [`local-dev/`](local-dev/README.md). |
 
-For example, to build the image using `texera-web-application.dockerfile`, run the following command **from the project root**:
+## Deployment
+
+| Entry point | Purpose |
+| --- | --- |
+| `single-node.sh` | Single entry point for the single-node Docker Compose stack. Run `bin/single-node.sh --help`. Implementation and setup docs live in [`single-node/`](single-node/README.md). |
+| `k8s/` | Helm chart and values for the Kubernetes deployment. See [`k8s/README.md`](k8s/README.md). |
+
+## Docker images
+
+`dockerfiles/` collects the per-service Dockerfiles, e.g.
+`texera-web-application.dockerfile`, `file-service.dockerfile`, and
+`computing-unit-master.dockerfile`. Each builds one Texera microservice and
+must be built with the project root as the Docker build context:
 
 ```bash
 docker build -f bin/dockerfiles/texera-web-application.dockerfile -t your-repo/texera-web-application:test .
 ```
 
-`build-images.sh` is included for building platform-dependent images conveniently.
+| Script | Purpose |
+| --- | --- |
+| `build-images.sh` | Convenience wrapper to build (and push) platform-dependent images. Run `bin/build-images.sh --help`. |
+| `merge-image-tags.sh` | Merge per-platform image tags into a single multi-arch manifest. |
+
+Prebuilt images published by the Texera team are on the
+[Texera DockerHub repository](https://hub.docker.com/repositories/texera).
+
+## Code generation & formatting
+
+| Script | Purpose |
+| --- | --- |
+| `frontend-proto-gen.sh` | Generate the frontend (TypeScript) code from protobuf definitions. |
+| `python-proto-gen.sh` | Generate the Python code from protobuf definitions. |
+| `fix-format.sh` | Run the repository's code formatters. |
+| `protoc-version.txt` | Pins the `protoc` version used by the proto-gen scripts. |
+
+## Benchmarks
+
+| Script | Purpose |
+| --- | --- |
+| `run-benchmarks.sh` | Single entry point for all Texera benchmarks; CI calls this script verbatim. |
+
+## Licensing
 
-You can also find prebuilt images published by the Texera team on the [Texera DockerHub Repository](https://hub.docker.com/repositories/texera).
+`licensing/` contains the scripts that audit JAR licenses and generate the
+binary `NOTICE`/`LICENSE` files (`audit_jar_licenses.py`,
+`check_binary_deps.py`, `concat_license_binary.py`,
+`generate_notice_binary.py`) plus their unit tests.
 
-## Deployment using images
+## Other components & configuration
 
-Subdirectories `single-node` and `k8s` contain configuration files for deploying Texera using the above Docker images.
\ No newline at end of file
+| Path | Purpose |
+| --- | --- |
+| `bootstrap-lakekeeper.sh` | Set up a local Lakekeeper (Iceberg REST catalog) instance for Texera. |
+| `utils/` | Shared shell helpers (`resolve-texera-home.sh`, `texera-logging.sh`) sourced by other scripts. |
+| `pylsp/` | Dockerized Python language server used by the UDF editor. |
+| `y-websocket-server/` | Dockerized Yjs websocket server backing collaborative editing. |
+| `forum/` | Flarum-based community forum setup (install scripts and seed SQL). |
+| `config.php`, `.htaccess` | Flarum runtime config and Apache rewrite rules for the forum. |
+| `litellm-config.yaml` | LiteLLM proxy configuration for AI features. |