You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@texera.apache.org by gi...@apache.org on 2026/06/29 02:07:47 UTC

(texera) branch main updated: docs(agents): document the local dev stack and worktree workflow (#6015)

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

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


The following commit(s) were added to refs/heads/main by this push:
     new 16a3ddfe58 docs(agents): document the local dev stack and worktree workflow (#6015)
16a3ddfe58 is described below

commit 16a3ddfe58fd7540d8ab5c9da88f0901cb804f4d
Author: Yicong Huang <17...@users.noreply.github.com>
AuthorDate: Sun Jun 28 18:56:21 2026 -0700

    docs(agents): document the local dev stack and worktree workflow (#6015)
    
    ### What changes were proposed in this PR?
    
    `AGENTS.md` documents the single-node and k8s deploy paths but never
    tells an agent how to run the local dev stack. This PR:
    
    - adds a "Where Things Live" row routing to `bin/local-dev.sh` — the
    single entry point (infra in Docker; backend, frontend, and
    agent-service run natively);
    - expands the "Develop in a worktree" section to:
      - prefer `bin/local-dev.sh` while developing;
    - bounce the stack across worktree switches (`down` in the old worktree,
    `up` in the new one), since the native services bind fixed ports and
    share one PID/state dir, so only one worktree's stack runs at a time;
    - use the non-interactive CLI subcommands — the interactive TUI (`-i`)
    is for humans, not agents.
    - drops "Local" from the single-node / k8s deploy row — both can deploy
    anywhere, not only locally.
    
    Only the wrapper is surfaced, never the internal
    `bin/local-dev/main.sh`.
    
    ### Any related issues, documentation, discussions?
    
    Closes #6014
    
    ### How was this PR tested?
    
    Docs-only change; no tests. Verified the linked
    `bin/local-dev/README.md` path resolves and that the described
    subcommands (`up` / `down` / `status` / `logs` / `-i`) match
    `bin/local-dev.sh --help`.
    
    ### Was this PR authored or co-authored using generative AI tooling?
    
    Generated-by: Claude Code (Claude Opus 4.8)
---
 AGENTS.md | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/AGENTS.md b/AGENTS.md
index eef0aea460..d537ffcbd8 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -34,7 +34,8 @@ engine, an Angular UI, and the agent service. JVM modules wired in
 | PR template | [.github/PULL_REQUEST_TEMPLATE](.github/PULL_REQUEST_TEMPLATE) |
 | Issue templates | [bug](.github/ISSUE_TEMPLATE/bug-template.yaml) / [task](.github/ISSUE_TEMPLATE/task-template.yaml) / [feature](.github/ISSUE_TEMPLATE/feature-template.yaml) |
 | License-header coverage; vendored `workflow-operator` | [.licenserc.yaml](.licenserc.yaml); [project/AddMetaInfLicenseFiles.scala](project/AddMetaInfLicenseFiles.scala) |
-| Local single-node / k8s deploy | [single-node](bin/single-node/README.md), [k8s](bin/k8s/README.md) |
+| Run the local dev stack (infra in Docker; backend/frontend/agent-service native) | [bin/local-dev.sh](bin/local-dev/README.md) |
+| Single-node / k8s deploy | [single-node](bin/single-node/README.md), [k8s](bin/k8s/README.md) |
 
 If a topic is above, **read that file** instead of asking here.
 
@@ -62,6 +63,13 @@ Reset to `upstream/main` at start; `git log upstream/main..HEAD` should
 contain only this PR's commits before pushing; remove the worktree after
 merge.
 
+Prefer [`bin/local-dev.sh`](bin/local-dev/README.md) to run the stack while
+developing. Its native services bind fixed ports and share one PID/state dir,
+so only one worktree's stack runs at a time: `bin/local-dev.sh down` in the
+old worktree before switching, then `up` in the new one. Use the
+non-interactive CLI subcommands (`up` / `down` / `status` / `logs`); the
+interactive TUI (`-i`) is for humans, not agents.
+
 ### Environment
 
 | Component | Version |