This is an automated email from the ASF dual-hosted git repository.
potiuk pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/airflow-site.git
The following commit(s) were added to refs/heads/main by this push:
new a4381791e5 Add AGENTS.md with AI agent instructions for airflow-site
(#1468)
a4381791e5 is described below
commit a4381791e5a893d46138dcfaf22021121a4c8959
Author: Jarek Potiuk <[email protected]>
AuthorDate: Tue Mar 17 01:52:57 2026 +0100
Add AGENTS.md with AI agent instructions for airflow-site (#1468)
Co-authored-by: Claude Opus 4.6 (1M context) <[email protected]>
---
AGENTS.md | 107 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 107 insertions(+)
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000000..1a35719d7b
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,107 @@
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+# AGENTS instructions
+
+## Environment Setup
+
+- Install prek: `uv tool install prek`
+- Enable commit hooks: `prek install`
+
+## Commands
+
+- **Run static checks:** `prek run --from-ref <target_branch> --stage
pre-commit`
+- **Run manual (slower) checks:** `prek run --from-ref <target_branch> --stage
manual`
+- **Run all checks on all files:** `prek run --all-files`
+- **Build the site:** `./site.sh build-site`
+- **Prepare theme:** `./site.sh prepare-theme`
+- **Install node dependencies:** `./site.sh install-node-deps`
+
+## Repository Structure
+
+- `landing-pages/` — Hugo-based landing pages (HTML, SCSS, JS)
+ - `site/themes/docsy/` — Docsy theme (npm dependencies)
+- `sphinx_airflow_theme/` — Sphinx theme package for Airflow documentation
+ - `demo/` — theme demo site
+- `.github/workflows/` — CI workflows (build, dependabot)
+- `site.sh` — main build script for the website
+- `license-templates/` — Apache License templates for prek hooks
+
+## Coding Standards
+
+- Apache License header on all new files (prek enforces this).
+
+## Commits and PRs
+
+Write commit messages focused on user impact, not implementation details.
+
+- NEVER add Co-Authored-By with yourself as co-author of the commit. Agents
cannot be authors, humans can be, Agents are assistants.
+
+### Creating Pull Requests
+
+**Always push to the user's fork**, not to the upstream `apache/airflow-site`
repo. Never push
+directly to `main`.
+
+Before pushing, determine the fork remote. Check `git remote -v` — if `origin`
does **not**
+point to `apache/airflow-site`, use `origin` (it's the user's fork). If
`origin` points to
+`apache/airflow-site`, look for another remote that points to the user's fork.
If no fork remote
+exists, create one:
+
+```bash
+gh repo fork apache/airflow-site --remote --remote-name fork
+```
+
+Before pushing, perform a self-review of your changes:
+
+1. Review the full diff (`git diff main...HEAD`) and verify every change is
intentional and
+ related to the task — remove any unrelated changes.
+2. Run static checks (`prek run --from-ref <target_branch> --stage
pre-commit`) and fix any failures.
+3. Check for security issues — no secrets, no injection vulnerabilities, no
unsafe patterns.
+
+Before pushing, always rebase your branch onto the latest target branch
(usually `main`)
+to avoid merge conflicts and ensure CI runs against up-to-date code:
+
+```bash
+git fetch <upstream-remote> <target_branch>
+git rebase <upstream-remote>/<target_branch>
+```
+
+If there are conflicts, resolve them and continue the rebase. If the rebase is
too complex,
+ask the user for guidance.
+
+Then push the branch to the fork remote and open the PR:
+
+```bash
+git push -u <fork-remote> <branch-name>
+gh pr create --web --title "Short title (under 70 chars)" --body "$(cat <<'EOF'
+Brief description of the changes.
+
+closes: #ISSUE (if applicable)
+
+---
+
+##### Was generative AI tooling used to co-author this PR?
+
+- [X] Yes — <Agent Name and Version>
+
+Generated-by: <Agent Name and Version>
+
+EOF
+)"
+```
+
+Remind the user to:
+
+1. Review the PR title — keep it short (under 70 chars) and focused on user
impact.
+2. Add a brief description of the changes at the top of the body.
+3. Reference related issues when applicable (`closes: #ISSUE` or `related:
#ISSUE`).
+
+## Boundaries
+
+- **Ask first**
+ - Large refactors.
+ - New dependencies with broad impact.
+- **Never**
+ - Commit secrets, credentials, or tokens.
+ - Edit generated files by hand when a generation workflow exists.
+ - Use destructive git operations unless explicitly requested.
