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 |