Copilot commented on code in PR #76: URL: https://github.com/apache/zeppelin-site/pull/76#discussion_r3511300616
########## AGENTS.md: ########## @@ -0,0 +1,86 @@ +# AGENTS.md + +Guidance for coding agents working in this checkout of `apache/zeppelin-site`. + +## Repository Shape + +- This is the Apache Zeppelin project website, built with Jekyll/GitHub Pages. +- Root pages, `_includes/`, `_layouts/`, `_plugins/`, `assets/`, `download.md`, and `security.md` are live site sources. +- `docs/<version>/` contains versioned documentation snapshots. Scope edits to the exact version or page requested. +- `output/` and `_site/` are generated or build output. Do not edit them unless the user explicitly asks for generated artifacts. +- `.asf.yaml` declares the ASF website flow: `master` builds to `asf-staging`, and `asf-site` is the publish branch. + +## Start Every Task + +- Run `git status --short --branch` first and preserve unrelated user changes. +- Start all work from the latest `origin/master`. Fetch it before editing: + ```bash + git fetch origin master + git switch master + git pull --ff-only origin master Review Comment: The `git switch master` step will fail on fresh/partial clones where a local `master` branch hasn’t been created yet (even if `origin/master` exists). Consider making the snippet robust by falling back to creating a tracking branch from `origin/master` so agents don’t get stuck at the very first step. ########## AGENTS.md: ########## @@ -0,0 +1,86 @@ +# AGENTS.md + +Guidance for coding agents working in this checkout of `apache/zeppelin-site`. + +## Repository Shape + +- This is the Apache Zeppelin project website, built with Jekyll/GitHub Pages. +- Root pages, `_includes/`, `_layouts/`, `_plugins/`, `assets/`, `download.md`, and `security.md` are live site sources. +- `docs/<version>/` contains versioned documentation snapshots. Scope edits to the exact version or page requested. +- `output/` and `_site/` are generated or build output. Do not edit them unless the user explicitly asks for generated artifacts. +- `.asf.yaml` declares the ASF website flow: `master` builds to `asf-staging`, and `asf-site` is the publish branch. + +## Start Every Task + +- Run `git status --short --branch` first and preserve unrelated user changes. +- Start all work from the latest `origin/master`. Fetch it before editing: + ```bash + git fetch origin master + git switch master + git pull --ff-only origin master + ``` +- If uncommitted work prevents switching to `master`, stop and ask before moving, stashing, or resetting anything. +- Do not begin content or code edits from `asf-site`, `asf-staging`, or an old feature branch. +- Use `rg` or `rg --files` for searches. +- In zsh, quote pathspecs that contain globs. +- Keep changes tightly scoped. Avoid broad formatting changes across historical docs. + +## Build And Preview + +- Build the Docker image and start the dev server: + ```bash + ./zeppelin-site.sh --build-image + ``` +- Start the dev server after the image exists: + ```bash + ./zeppelin-site.sh + ``` +- Preview at `http://localhost:4000`. +- Build the production site: + ```bash + ./zeppelin-site.sh --build-dist + ``` +- `zeppelin-site.sh` removes `_site/` before serving or building. +- If dependency troubleshooting is needed, use the repo's Docker path: + ```bash + docker run --rm -it -v "$(pwd):/app" zeppelin-site-dev:latest /bin/bash + bundle install + ``` Review Comment: In the Docker troubleshooting snippet, `bundle install` will run on the host if someone copy/pastes the whole block. Adding an explicit note that it should be executed inside the container (or converting to a single `bash -lc` one-liner) makes the guidance unambiguous. ########## AGENTS.md: ########## @@ -0,0 +1,86 @@ +# AGENTS.md + +Guidance for coding agents working in this checkout of `apache/zeppelin-site`. + +## Repository Shape + +- This is the Apache Zeppelin project website, built with Jekyll/GitHub Pages. +- Root pages, `_includes/`, `_layouts/`, `_plugins/`, `assets/`, `download.md`, and `security.md` are live site sources. +- `docs/<version>/` contains versioned documentation snapshots. Scope edits to the exact version or page requested. +- `output/` and `_site/` are generated or build output. Do not edit them unless the user explicitly asks for generated artifacts. +- `.asf.yaml` declares the ASF website flow: `master` builds to `asf-staging`, and `asf-site` is the publish branch. + +## Start Every Task + +- Run `git status --short --branch` first and preserve unrelated user changes. +- Start all work from the latest `origin/master`. Fetch it before editing: + ```bash + git fetch origin master + git switch master + git pull --ff-only origin master + ``` +- If uncommitted work prevents switching to `master`, stop and ask before moving, stashing, or resetting anything. +- Do not begin content or code edits from `asf-site`, `asf-staging`, or an old feature branch. +- Use `rg` or `rg --files` for searches. +- In zsh, quote pathspecs that contain globs. +- Keep changes tightly scoped. Avoid broad formatting changes across historical docs. + +## Build And Preview + +- Build the Docker image and start the dev server: + ```bash + ./zeppelin-site.sh --build-image + ``` +- Start the dev server after the image exists: + ```bash + ./zeppelin-site.sh + ``` +- Preview at `http://localhost:4000`. +- Build the production site: + ```bash + ./zeppelin-site.sh --build-dist + ``` +- `zeppelin-site.sh` removes `_site/` before serving or building. +- If dependency troubleshooting is needed, use the repo's Docker path: + ```bash + docker run --rm -it -v "$(pwd):/app" zeppelin-site-dev:latest /bin/bash + bundle install + ``` + +## Branch Synchronization Rules + +Be extra careful with `asf-site` and `asf-staging`. The user cares about proof of which ref moved. + +- Do not assume `asf-staging` exists as a local branch. Refresh remote-tracking refs directly: + ```bash + git fetch origin refs/heads/asf-site:refs/remotes/origin/asf-site refs/heads/asf-staging:refs/remotes/origin/asf-staging + ``` +- Compare before any destructive branch move: + ```bash + git status --short --branch + git remote -v + git rev-parse asf-site origin/asf-site origin/asf-staging + git log --oneline -1 asf-site + git log --oneline -1 origin/asf-site + git log --oneline -1 origin/asf-staging Review Comment: The comparison commands use the local `asf-site` branch (`git rev-parse asf-site` / `git log ... asf-site`), but earlier guidance says not to assume these branches exist locally. Using the remote-tracking refs (`origin/asf-site`, `origin/asf-staging`) avoids a hard failure and still provides the proof this section is aiming for. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
