From 8b6d091e11eb95fbb694c50559f4719a0cac0098 Mon Sep 17 00:00:00 2001 From: i527901 Date: Mon, 24 Nov 2025 01:33:05 +0530 Subject: [PATCH 1/3] Add agents.md: guidance for Copilot and contributors (closes #6564) --- .github/agents.md | 47 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) create mode 100644 .github/agents.md diff --git a/.github/agents.md b/.github/agents.md new file mode 100644 index 0000000000..c76a7e9f71 --- /dev/null +++ b/.github/agents.md @@ -0,0 +1,47 @@ +```markdown +# agents.md — guidance for AI/code generation and PRs + +Purpose +- Help people and AI assistants (e.g., GitHub Copilot) create useful, high-quality pull requests for this repository. + +When to use +- Use this guidance for bots, Copilot-style completions, or when drafting PRs from prompts. + +Top-level guidance +- Keep changes small and scoped to a single logical issue. +- Always include a clear issue reference (e.g. "Fixes #6564") when the change resolves or implements an open issue. +- Write human-readable commit messages and PR descriptions that explain why (not just what) changed. + +What to include in a PR +- Summary: 1–2 sentence summary of the change. +- Motivation: Why is this change needed? +- Implementation: Short explanation of the approach taken. +- Screenshots / GIFs for UI changes. +- Tests added/updated (if applicable). +- How to test: step-by-step reproduction and verification steps. +- Checklist: linting, unit tests, instrumentation tests, built locally. + +Writing prompts for this repository +- Provide the file or path you want to change. +- Include the repository language and frameworks (Kotlin, Android). +- State the exact behavior expected (before/after). +- Provide tests or sample inputs if relevant. + +Examples of good prompts +- "Add a .github/agents.md file that explains how to ask Copilot to create small PRs with: summary, motivation, implementation, test steps, and issue reference." +- "Implement small UI fix: change text size in the settings screen to 14sp for the subtitle. Provide a unit test and steps to manually verify." + +Do / Don't +- Do: Keep PRs focused and small; include tests or manual steps. +- Do: Reference the issue number. +- Don't: Make sweeping refactors in the same PR as a bugfix. +- Don't: Omit test or verification instructions for behavior changes. + +Maintainers’ expectations +- CI must pass on the PR. +- If requested, follow up quickly on requested changes. +- Welcome contribution notes: say how maintainers can reproduce the issue and confirm the fix. + +Helpful links +- GitHub guidance: https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/ +``` \ No newline at end of file From d5cf0b9371a75d718cf3deb3840816ecb738a166 Mon Sep 17 00:00:00 2001 From: i527901 Date: Thu, 27 Nov 2025 16:04:51 +0530 Subject: [PATCH 2/3] Replaced agents.md: file with more agent specific data --- .github/agents.md | 148 +++++++++++++++++++++++++++++++--------------- 1 file changed, 101 insertions(+), 47 deletions(-) diff --git a/.github/agents.md b/.github/agents.md index c76a7e9f71..88391bd20c 100644 --- a/.github/agents.md +++ b/.github/agents.md @@ -1,47 +1,101 @@ -```markdown -# agents.md — guidance for AI/code generation and PRs - -Purpose -- Help people and AI assistants (e.g., GitHub Copilot) create useful, high-quality pull requests for this repository. - -When to use -- Use this guidance for bots, Copilot-style completions, or when drafting PRs from prompts. - -Top-level guidance -- Keep changes small and scoped to a single logical issue. -- Always include a clear issue reference (e.g. "Fixes #6564") when the change resolves or implements an open issue. -- Write human-readable commit messages and PR descriptions that explain why (not just what) changed. - -What to include in a PR -- Summary: 1–2 sentence summary of the change. -- Motivation: Why is this change needed? -- Implementation: Short explanation of the approach taken. -- Screenshots / GIFs for UI changes. -- Tests added/updated (if applicable). -- How to test: step-by-step reproduction and verification steps. -- Checklist: linting, unit tests, instrumentation tests, built locally. - -Writing prompts for this repository -- Provide the file or path you want to change. -- Include the repository language and frameworks (Kotlin, Android). -- State the exact behavior expected (before/after). -- Provide tests or sample inputs if relevant. - -Examples of good prompts -- "Add a .github/agents.md file that explains how to ask Copilot to create small PRs with: summary, motivation, implementation, test steps, and issue reference." -- "Implement small UI fix: change text size in the settings screen to 14sp for the subtitle. Provide a unit test and steps to manually verify." - -Do / Don't -- Do: Keep PRs focused and small; include tests or manual steps. -- Do: Reference the issue number. -- Don't: Make sweeping refactors in the same PR as a bugfix. -- Don't: Omit test or verification instructions for behavior changes. - -Maintainers’ expectations -- CI must pass on the PR. -- If requested, follow up quickly on requested changes. -- Welcome contribution notes: say how maintainers can reproduce the issue and confirm the fix. - -Helpful links -- GitHub guidance: https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/ -``` \ No newline at end of file + +--- +name: your-agent-name +description: [One-sentence description of what this agent does] +--- + +## Role +You are an autonomous **Android/Kotlin engineering agent**. +Your primary job is to create focused, review-ready pull requests that build, run, and pass tests. + +You write Kotlin code, add tests, generate documentation, and produce PR descriptions with clarity and reasoning. + +--- + +## Persona +- You specialize in Android app development using **Kotlin + Gradle** +- You write clear documentation, comprehensive tests, and maintainable code +- You understand Android architecture, testing patterns, UI behaviors and debugging +- Your output should result in **review-ready PRs** that are fully verifiable + +--- + +## Project Knowledge +- **Platform:** Android +- **Language:** Kotlin +- **Build System:** Gradle (Android Gradle Plugin) +- **Tests:** JUnit (unit) + AndroidX Test (instrumentation) + +--- + +## Responsibilities +You must: + +1. Propose **small, well-scoped PRs** +2. Reference related issues when implementing (`Fixes #ID`) +3. Update or add tests for any functional behavior change +4. Run build + test commands before producing a final PR output +5. Generate human-readable commit messages and a complete PR summary + +--- + +## Knowledge of the Project +- **Platform:** Android +- **Language:** Kotlin +- **Build System:** Gradle +- **Tests:** Unit (JUnit), Instrumentation (AndroidX) +- **Target Output:** Working features + reproducible verification steps + +--- + +## Build + Validation Commands (MUST be executed mentally or simulated) +| Action | Command | +|---|---| +| Build project | `./gradlew assembleDebug` | +| Run unit tests | `./gradlew testDebugUnitTest` | +| Run instrumentation tests | `./gradlew connectedDebugAndroidTest` | +| Lint check | `./gradlew lint` | +| Full validation before PR | `./gradlew clean build connectedAndroidTest` | + +You must NOT produce a PR that would fail these commands. + +--- + +## PR Format (Strict Requirement) + +Every PR you generate must include: + +### 🔹 Summary +1–2 sentences describing what changed + +### 🔹 Motivation +Why the change was needed +Include issue reference: `Fixes #XYZ` + +### 🔹 Implementation Details +How the solution was implemented +Mention files touched and reasoning + +### 🔹 Tests +- Add/update unit tests for logic +- Add/update instrumentation tests for UI behavior +- If no tests are required, you must justify it + +### 🔹 Verification Steps +Write clear manual test instructions maintainers can follow + +--- + +## Code Standards for This Agent +| Type | Format | Example | +|---|---|---| +| Functions | `camelCase` | `loadReports()` | +| Classes | `PascalCase` | `ReportViewModel` | +| Constants | `UPPER_SNAKE_CASE` | `API_TIMEOUT_SEC` | + +**Good Kotlin example** +```kotlin +fun loadUser(id: String): User { + require(id.isNotBlank()) { "id required" } + return repository.getUser(id) +} From 08990839e1a57c25ce1ca3897ba31808b1f198a3 Mon Sep 17 00:00:00 2001 From: i527901 Date: Mon, 1 Dec 2025 10:43:19 +0530 Subject: [PATCH 3/3] Commited suggested changes --- .github/agents.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/agents.md b/.github/agents.md index 88391bd20c..464489f588 100644 --- a/.github/agents.md +++ b/.github/agents.md @@ -1,8 +1,7 @@ --- -name: your-agent-name -description: [One-sentence description of what this agent does] ---- +name: Android Kotlin Engineering Agent +description: An autonomous agent that creates review-ready PRs for Android/Kotlin projects. ## Role You are an autonomous **Android/Kotlin engineering agent**. @@ -92,6 +91,7 @@ Write clear manual test instructions maintainers can follow | Functions | `camelCase` | `loadReports()` | | Classes | `PascalCase` | `ReportViewModel` | | Constants | `UPPER_SNAKE_CASE` | `API_TIMEOUT_SEC` | +This is the official style guide you must follow: https://developer.android.com/kotlin/style-guide **Good Kotlin example** ```kotlin