Skip to content

docs: update contribution guide, GEMINI.md, and llm.txt #743

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
eliasecchig merged 1 commit into from
Feb 2, 2026
Merged

docs: update contribution guide, GEMINI.md, and llm.txt #743

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
242 changes: 197 additions & 45 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,80 +1,232 @@
# How to Contribute
# Contributing to Agent Starter Pack

We'd love to accept your patches and contributions to this sample. There are
just a few small guidelines you need to follow.
We welcome contributions to the Agent Starter Pack! This guide helps you understand the project and make effective contributions.

## Contributor License Agreement
## Quick Navigation

Contributions to this project must be accompanied by a Contributor License Agreement. You (or your employer) retain the copyright to your contribution; this simply gives us permission to use and redistribute your contributions as part of the project. Head over to [Google Developers CLA](https://cla.developers.google.com/) to see your current agreements on file or to sign a new one.
| What you're changing | Start here |
|---------------------|------------|
| Template files (Jinja templates in base_templates/) | [Template Development Workflow](#template-development-workflow) |
| CLI commands (cli/commands/) | [Code Quality](#code-quality) |
| Documentation | [Pull Request Process](#pull-request-process) |
| **AI coding agents** | See [GEMINI.md](./GEMINI.md) for comprehensive AI agent guidance |

You generally only need to submit a CLA once, so if you've already submitted one (even if it was for a different project), you probably don't need to do it again.
## Understanding ASP Architecture

## Code Reviews
Agent Starter Pack is a **template generator**, not a runtime framework. The CLI generates standalone projects that users then customize and deploy.

All submissions, including submissions by project members, require review. We
use GitHub pull requests for this purpose. Consult
[GitHub Help](https://help.github.com/articles/about-pull-requests/) for more
information on using pull requests.
### 4-Layer Template System

## Community Guidelines
Templates are processed in order, with later layers overriding earlier ones:

This project follows [Google's Open Source Community Guidelines](https://opensource.google/conduct/).
1. **Base Templates** (`agent_starter_pack/base_templates/<language>/`) - Core Jinja scaffolding (Python, Go, more coming)
2. **Deployment Targets** (`agent_starter_pack/deployment_targets/`) - Environment-specific overrides (cloud_run, agent_engine)
3. **Frontend Types** (`agent_starter_pack/frontends/`) - UI-specific files
4. **Agent Templates** (`agent_starter_pack/agents/*/`) - Agent-specific logic and configurations

## Contributor Guide
### Key Directories

If you are new to contributing to open source, you can find helpful information in this contributor guide.
| Directory | Purpose |
|-----------|---------|
| `agent_starter_pack/base_templates/` | Jinja templates by language (see [Language-Specific Notes](#language-specific-notes)) |
| `agent_starter_pack/deployment_targets/` | Files that override/extend base for specific deployments |
| `agent_starter_pack/agents/` | Agent-specific files (adk, adk_live, langgraph, etc.) |
| `agent_starter_pack/cli/commands/` | CLI command implementations (create, setup-cicd, etc.) |
| `agent_starter_pack/cli/utils/` | Shared utilities including template processing |

You may follow these steps to contribute:
## Template Development Workflow

1. **Fork the official repository.** This will create a copy of the official repository in your own account.
2. **Sync the branches.** This will ensure that your copy of the repository is up-to-date with the latest changes from the official repository.
3. **Work on your forked repository's feature branch.** This is where you will make your changes to the code.
4. **Commit your updates on your forked repository's feature branch.** This will save your changes to your copy of the repository.
5. **Submit a pull request to the official repository's main branch.** This will request that your changes be merged into the official repository.
6. **Resolve any linting errors.** This will ensure that your changes are formatted correctly.
- For errors generated by [check-spelling](https://github.com/check-spelling/check-spelling), go to the [Job Summary](https://github.com/GoogleCloudPlatform/generative-ai/actions/workflows/spelling.yaml) to read the errors.
- Fix any spelling errors that are found.
- Forbidden Patterns are defined as regular expressions, you can copy/paste them into many IDEs to find the instances. [Example for Visual Studio Code](https://medium.com/@nikhilbaxi3/visual-studio-code-secrets-of-regular-expression-search-71723c2ecbd2).
- Add false positives to [`.github/actions/spelling/allow.txt`](.github/actions/spelling/allow.txt). Be sure to check that it's actually spelled correctly!
Template changes require a specific workflow because you're modifying Jinja templates.

Here are some additional things to keep in mind during the process:
### Recommended Process

- **Read the [Google's Open Source Community Guidelines](https://opensource.google/conduct/).** The contribution guidelines will provide you with more information about the project and how to contribute.
- **Test your changes.** Before you submit a pull request, make sure that your changes work as expected.
- **Be patient.** It may take some time for your pull request to be reviewed and merged.
1. **Generate a test instance**
```bash
uv run agent-starter-pack create mytest -p -s -y -d cloud_run --output-dir target
```
Flags: `-p` prototype (no CI/CD), `-s` skip checks, `-y` auto-approve

---
2. **Initialize git in the generated project**
```bash
cd target/mytest && git init && git add . && git commit -m "Initial"
```

## For Google Employees
3. **Develop with tight feedback loops**
- Make changes directly in `target/mytest/`
- Test immediately with `make lint` and running the code
- Iterate until the change works

4. **Backport changes to Jinja templates**
- Identify the source template file in `agent_starter_pack/`
- Apply your changes, adding Jinja conditionals if needed
- Use `{%- -%}` whitespace control carefully (see [GEMINI.md](./GEMINI.md#critical-whitespace-control-patterns))

5. **Validate across combinations**
```bash
# Test your target combination
_TEST_AGENT_COMBINATION="adk,cloud_run,--session-type,in_memory" make lint-templated-agents

# Test alternate agent with same deployment
_TEST_AGENT_COMBINATION="adk_live,cloud_run" make lint-templated-agents

If you're a Google employee, as a requirement, please follow the steps outlined in the [Google Cloud Platform Generative AI repository's contributing guide](https://github.com/GoogleCloudPlatform/generative-ai/blob/main/CONTRIBUTING.md#for-google-employees) for processes and requirements.
# Test same agent with alternate deployment
_TEST_AGENT_COMBINATION="adk,agent_engine" make lint-templated-agents
```

## Code Quality Checks
### Why This Workflow?

To ensure code quality, we utilize automated checks. Before submitting a pull request, please run the following commands locally:
- Jinja templates are harder to debug than rendered code
- Generated projects give immediate feedback on syntax errors
- Backporting ensures you understand exactly what changed
- Cross-combination testing catches conditional logic bugs

### Language-Specific Notes

The template development workflow above applies to all languages. Here are language-specific details:

| Language | Agent(s) | Linter | Test Command | Status |
|----------|----------|--------|--------------|--------|
| Python | adk, adk_a2a, adk_live, agentic_rag, langgraph, custom_a2a | `ruff`, `ty` | `make lint` | Production |
| Go | adk_go | `golangci-lint` | `make lint` | Production |
| Java | (coming soon) | - | - | In development |
| TypeScript | (coming soon) | - | - | In development |

**Python example:**
```bash
make install
uv run agent-starter-pack create mytest -a adk -d cloud_run -p -s -y --output-dir target
```

This installs development dependencies, including linting tools.
**Go example:**
```bash
uv run agent-starter-pack create mytest -a adk_go -d cloud_run -p -s -y --output-dir target
```

Then, execute the following Make command:
## Testing Your Changes

### Local Testing

```bash
# Install dependencies (first time)
make install

# Run linters (ruff, ty, codespell)
make lint

# Run test suite
make test
```

This command runs the following linters to check for code style, potential errors, and type hints:
### Template Combination Testing

- **codespell**: Detects common spelling mistakes in code and documentation.
- **ruff**: A fast Python linter and formatter, it checks for errors, coding standards, and enforces style consistency.
- **ty**: Performs static type checking to catch type errors before runtime (Astral's Rust-based type checker).
Template changes can affect multiple agent/deployment combinations. Test the minimum coverage matrix:

```bash
make test
# Format: agent,deployment_target,--flag,value
_TEST_AGENT_COMBINATION="adk,cloud_run,--session-type,in_memory" make lint-templated-agents
_TEST_AGENT_COMBINATION="adk,agent_engine" make lint-templated-agents
_TEST_AGENT_COMBINATION="langgraph,cloud_run" make lint-templated-agents
```

**Minimum coverage before PR:**
- [ ] Your target combination
- [ ] One alternate agent with same deployment target
- [ ] One alternate deployment target with same agent

### Quick Project Generation for Testing

```bash
# Fastest: Agent Engine prototype
uv run agent-starter-pack create test-$(date +%s) -p -s -y -d agent_engine --output-dir target

# Cloud Run with session type
uv run agent-starter-pack create test-$(date +%s) -p -s -y -d cloud_run --session-type in_memory --output-dir target

# Full project with CI/CD
uv run agent-starter-pack create test-$(date +%s) -s -y -d agent_engine --cicd-runner google_cloud_build --output-dir target
```

## Pull Request Process

### Commit Message Format

```
<type>: <concise summary in imperative mood>

<detailed explanation if needed>
- Why the change was needed
- What was the root cause (for fixes)
- How the fix addresses it
```

**Types**: `fix`, `feat`, `refactor`, `docs`, `test`, `chore`

### PR Description Template

```markdown
## Summary
- Key change 1
- Key change 2

## Problem (for fixes)
Description of the issue, including error messages if applicable.

## Solution
How the changes fix the problem.

## Testing
- [ ] Tested combination: agent,deployment
- [ ] Tested alternate: agent2,deployment
- [ ] Tested alternate: agent,deployment2
```

### Required Checks

All PRs must pass:
- `make lint` - Code style and type checking
- `make test` - Unit and integration tests
- Template linting for affected combinations

## Code Quality

### Linting Tools

| Tool | Purpose |
|------|---------|
| `ruff` | Python linting and formatting |
| `ty` | Static type checking (Astral's Rust-based checker) |
| `codespell` | Spelling mistakes in code and docs |

### Template-Specific Linting

For template files, also ensure:
- All Jinja blocks are balanced (`{% if %}` has `{% endif %}`)
- Whitespace control is correct (see [GEMINI.md](./GEMINI.md#critical-whitespace-control-patterns))
- Generated files pass `ruff` in all combinations

### Spelling Errors

For errors from [check-spelling](https://github.com/check-spelling/check-spelling):
1. Check the Job Summary for specific errors
2. Fix actual spelling mistakes
3. Add false positives to `.github/actions/spelling/allow.txt`

## Contributor License Agreement

Contributions must be accompanied by a Contributor License Agreement. You (or your employer) retain copyright; this gives us permission to use and redistribute your contributions.

Sign at [Google Developers CLA](https://cla.developers.google.com/). You generally only need to submit once.

## Community Guidelines

This project follows [Google's Open Source Community Guidelines](https://opensource.google/conduct/).

## For Google Employees

Follow the additional steps in the [Generative AI on Google Cloud repository's contributing guide](https://github.com/GoogleCloudPlatform/generative-ai/blob/main/CONTRIBUTING.md#for-google-employees).

---

This command runs the test suite using pytest, covering both unit and integration tests:
## Additional Resources

Your pull request will also be automatically checked by these tools using GitHub Actions. Ensuring your code passes these checks locally will help expedite the review process.
- **[GEMINI.md](./GEMINI.md)** - Comprehensive guide for AI coding agents, including Jinja patterns and debugging
- **[docs/](./docs/)** - User-facing documentation for generated projects
Loading