diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..954697ae0 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,359 @@ +# Guidelines for AI Contributions to Amaze File Manager + +This file provides guidance to AI coding assistants for contributing +to the codebase. These guidelines are designed to produce +contributions that meet the same high standards we expect from human +contributors. The original reference for this file is the Zulip +CLAUDE.md file, we thank the Zulip team for their work. + +## Philosophy + +### No detail is too small + +Amaze holds itself to a high bar for polish because users depend on +this software daily, and because the project is built to last for +decades. There is no category of "minor issue" that is acceptable +to ship, if something is broken in any context where a user would +encounter it, it must be fixed before merging. The project's +extensive investment in testing, tooling, and review processes exists +precisely so that these issues get caught and fixed, not so that they +can be classified as low-priority and deferred. + +The right attitude is: "What could go wrong, and how do I verify that +it doesn't?" not "It looks fine to me." **What isn't tested probably +doesn't work** - this applies to visual changes just as much as to +backend logic. + +### Understand before coding + +Before writing any code, you must understand: + +1. What the existing code does and why, including the relevant help center or + developer-facing documentation. +2. What problem you're solving, in its full scope. +3. Why your approach is the right solution, and available alternatives. +4. How you will verify that your work is correct, and avoid regressions + that are plausible for the type of work you're doing. + +The answer to "Why is X an improvement?" should never be "I'm not sure." + +## Workflow + +Follow this workflow for every task: **understand → propose → implement → verify**. + +### 1. Understand Before Coding + +Before making any changes: + +```bash +# Look at existing code patterns +git grep "similar_function_name" +git log --oneline -20 -- path/to/file.py + +# Check for related issues on GitHub +``` + +Always show existing similar code and explain how it works before proposing +changes. + +### 2. Propose an Approach + +Before writing code, explain the plan: + +- Explain your understanding of the problem and all relevant design decisions +- What changes are needed and why +- How the changes fit with existing patterns +- What could break and how to prevent regressions + +### 3. Implement in Minimal, Coherent Commits + +Each commit should be self-contained, highly readable and reviewable +using `git show --color-moved`, and pass lint/tests independently. If +extracting new files or moving code, always do that in a separate +commit from other changes. + +### 4. Verify Before Finalizing + +Run tests before making a commit. Always manage your time by running +specific test collections, not the entire test suite. + +## Before You Start + +### Read the Relevant Documentation + +Before working on any area: + +- Read the @CONTRIBUTING.md guidelines. +- Read existing code in the area you're modifying. +- Use `git grep` to find similar patterns in the codebase and read those. + +### Understand the Code Style + +- **Be consistent with existing code.** Look at surrounding code and follow + the same patterns, as this is a thoughtfully crafted codebase. +- **Use clear, greppable names** for functions, arguments, variables, and + tests. Future developers will `git grep` for relevant terms when + researching a problem, so names should communicate purpose clearly. +- Keep everything well factored for maintainability. Avoid duplicating + code, especially where access control or subtle correctness is involved. +- Prefer writing code that is readable without explanation over heavily + commented code using clever tricks. Comments should explain "why" when + the reason isn't obvious, not narrate "what" the code does. +- Comments generally should have a line to themselves. + +## Commit Discipline + +### Each Commit Must: + +1. **Be coherent**: Implement one logical change completely and atomically. +2. **Pass tests**: Include test updates in the same commit as code changes. +3. **Not make Amaze worse**: Work is ordered so no commit has regressions. +4. **Be safe to deploy individually**: Or explain in detail why not. +5. **Be minimal** and **reviewable**: Don't combine moving code with changing + it in the same commit; make liberal use of small prep commits for + no-op refactoring that are easy to verify. + +### Never: + +- Mix multiple separable changes in a single commit. +- Create a commit that "fixes" a mistake from an earlier commit in the same PR; + always edit Git to fix the original commit. +- Add content in one commit only to remove or move it in the next; + plan upfront what belongs where and do it right the first time. +- Include debugging code, commented-out code, or temporary TODOs. +- Leave commits that break if a later commit in the PR is dropped. + When a commit is flagged as potentially droppable, verify all + earlier commits work correctly without it. + +### Commit Message Format + +``` +subsystem: Summary in 72 characters or less. + +The body explains why and how. Include context that helps reviewers +and future developers understand your reasoning, analysis, and +verification of the work above and beyond CI, without repeating +details already well presented in the commit metadata (filenames, +etc.). Explain what the change accomplishes and why it won't break +things one might worry about. + +Line-wrap at 68-70 characters, except URLs and verbatim content +(error messages, etc.). + +Fixes #123. +``` + +**Commit summary format:** + +- Example: `Fix cursor position after emoji insertion` +- Example: `Refactor immutable cache headers` +- Bad examples: `Fix bug`, `Update code`, `gather_subscriptions was broken` + +**Linking issues:** + +- `Fixes #123` automatically closes the issue +- `Addresses #123` does not close (for partial fixes) +- In a multi-commit PR, use `Addresses #123` in earlier commits + and `Fixes #123` in the final commit. + +### Rebasing Commits (Non-Interactive) + +Since `git rebase -i` requires an interactive editor, use +`GIT_SEQUENCE_EDITOR` to supply the todo list via a script: + +1. **Updating the HEAD commit:** If the commit you need to modify is + already at HEAD, just use `git commit --amend` directly. The + fixup+rebase workflow below is only needed for non-HEAD commits. + +2. **Squashing fixups into existing commits:** Create fixup commits with + `git commit --fixup=`, then write a shell script that + outputs the desired todo (with `pick` and `fixup` lines in order) + and run: + + ```bash + GIT_SEQUENCE_EDITOR=/path/to/todo-script.sh git rebase -i + ``` + + Note: `--autosquash` alone without `-i` does **not** reorder or + squash anything. + +3. **Rewording commit messages:** Use `git format-patch` to export + commits as patch files, edit the message headers in the patch + files, then reapply: + + ```bash + git format-patch -o /tmp/patches/ + # Edit the commit message in each /tmp/patches/000N-*.patch file + # (the message is between the Subject: line and the --- line) + git reset --hard + git am /tmp/patches/*.patch + ``` + +## Testing Requirements + +Automated code generation must include tests for all components +to prevent regressions. + +There are three kinds of tests: +- Unit tests: Test single functions, simple functionality, very + easy to run, if at all possible, these should be used to test + functionality. +- Headless tests: Robolectric is used for testing anything that + doesn't require a phone, it allows for extensive mocking and + UI interaction simulation without the full UI overhead. +- Emulator tests: Using Espresso and other tools, very heavy to + run, create these tests as a last resort. + +### Before Submitting: + +Check that the new features, or fixed bugs are being properly tested +for regressions. + +### Testing Philosophy: + +- Write end-to-end tests when possible verifying what's important. +- A good failing test before implementing is good practice so your + test and code can jointly verify each other. +- Remember to always assert state is correctly updated, not just "success". + +## Self-Review Checklist + +Before finalizing, verify: + +- [ ] The PR addresses all points described in the issue +- [ ] All relevant tests pass locally +- [ ] Code follows existing patterns in the codebase +- [ ] Names (functions, variables, tests) are clear and greppable +- [ ] Commit messages, comments, and PR description are well done +- [ ] Each commit is a minimal coherent idea +- [ ] No debugging code or unnecessary comments remain +- [ ] Type annotations are complete and correct +- [ ] User-facing strings are in strings.xml +- [ ] User-facing error messages are clear and actionable +- [ ] No secrets or credentials are hardcoded +- [ ] Documentation is updated if behavior changes +- [ ] Refactoring is complete (`git grep` for remaining occurrences) +- [ ] Security audit of changes + +Always output a recommend pull request summary+description that +follow's Amaze's guidelines once you finish preparing a series of +commits. + +## Common Pitfalls + +### Treating Known Issues as Acceptable + +A common failure mode is discovering a problem during verification +and then noting it as a known limitation rather than fixing it. + +**Mitigation:** When you find any issue during verification, fix it +before presenting the work. If a fix would require a design decision, +raise it as a question rather than shipping the broken state. + +### Missing Test Updates + +Tests must be in the same commit as the code they test. + +**Mitigation:** Include test updates in each commit. Show what tests need to +change. + +### Verbose Commit Messages + +Commits are concise, say everything that's important for a reviewer to +understand about the motivation for the work and changes, and nothing more. +Avoid wordiness and details obvious to someone who is looking at the +commit and its metadata (lists of filenames, etc). + +**Mitigation:** Keep summary under 72 characters. Body should explain why, +not what. + +### Mixing Concerns + +Multiple changes in one commit makes review difficult. + +**Mitigation:** Each commit should do exactly one thing. Plan +necessary refactoring and preparatory commits in advance of functional +changes. You can split into good commits after the fact, but it's much +faster and easier to just plan and write them well the first time. + +## Pull Request Guidelines + +### PR Description Should: + +When opening a pull request, prefix the PR title with `[ai]` (e.g., +`[ai] compose: Fix cursor position after emoji insertion.`). Use +`upstream/main` as the base branch. + +Output the PR description in a markdown code block so that formatting +(bold, headers, checkboxes, etc.) copy-pastes correctly into GitHub. + +1. Start with a `Fixes: #...` line linking the issue being addressed. +2. Explain **why** the change is needed, not just what changed. +3. Describe how you tested the change, using checkbox format for the + test plan (e.g., `- [x] ./tools/test-backend ...`). +4. Include screenshots for UI changes. +5. Link to relevant issues or discussions. +6. Call out any open questions, concerns, or decisions you are uncertain + about, so they can be resolved during review. +7. Include the self-review checklist from + `.github/pull_request_template.md` using checkbox format (`- [x]` / + `- [ ]`), checking off all applicable items. + +### PR Description Should Not: + +- Regurgitate information visible from the diff +- Make claims you haven't double-checked +- Express more certainty than is justified given the evidence + +## When to Pause and Discuss + +Recommend pausing for discussion when: + +- The approach involves security-sensitive code +- Database migrations are needed +- The change affects many files (>10) +- Performance implications are unclear +- The feature design isn't fully specified +- The API or data model design isn't fully specified +- Existing tests are failing for unclear reasons + +## Task-Specific Approaches + +### For Bug Fixes + +1. Show the relevant code and explain what's happening +2. Brainstorm theories for how the bug might be possible +3. Analyze and propose a fix with a clear explanation +4. Write tests that would have caught this bug if possible +5. Format as a single commit following commit guidelines +6. Audit for whether the bug may exist elsewhere or might be + re-introduced and propose appropriate changes to address if so. + +### For New Features + +1. Show similar existing features in the codebase +2. Propose an implementation approach before coding +3. Implement in minimal, coherent commits +4. Each commit must pass tests independently + +### For Refactoring + +1. Show the current implementation +2. Explain what makes it problematic +3. Propose the refactoring approach +4. Implement in commits that each leave the codebase working +5. No behavior changes unless explicitly discussed +6. Verify completeness: use `git grep` to find all occurrences and + confirm nothing was missed + +## Repository Structure Quick Reference + +- `app` contains the main app +- `commons_compress_7z` is the 7z compression and decompression library +- `file_operations` is a rust library which contain some of the low level + operations needed by Amaze +- `portscanner` is a network library used by various systems in Amaze +- `scripts` is a directory that contains general tools for maintaining the + app +- `fastlane` is a directory that maintains the resources for FDroid and other + open source app repositories diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 000000000..eef4bd20c --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md \ No newline at end of file