summaryrefslogtreecommitdiff
path: root/AGENT.md
diff options
context:
space:
mode:
authorPaul Buetow <paul@buetow.org>2025-12-31 17:28:34 +0200
committerPaul Buetow <paul@buetow.org>2025-12-31 17:28:46 +0200
commit545e65fe16c761822f0999b8f4ab05f1cd325975 (patch)
treea4afdab1acfa8114219c831fed3f02de8dab4a64 /AGENT.md
parentc04911dfa213b7d3009436e0365d17ed49001759 (diff)
feat: implement logarithmic scoring system for showcase rankingv0.11.0
- Remove vibe-coded and AI-assisted detection from showcase - Add project rank numbers to showcase headers - Implement logarithmic score: log10(LOC) * 1000 / (avgCommitAge + 1) - Replace 'Recent Activity' display with 'Score' - Update sorting to use score (highest first) - Score balances project size and recent activity - Bump version to 0.11.0 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Diffstat (limited to 'AGENT.md')
-rw-r--r--AGENT.md39
1 files changed, 39 insertions, 0 deletions
diff --git a/AGENT.md b/AGENT.md
new file mode 100644
index 0000000..354820a
--- /dev/null
+++ b/AGENT.md
@@ -0,0 +1,39 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+- `cmd/gitsyncer/`: CLI entrypoint (`main.go`).
+- `internal/`: private packages — `cli/` (flags/handlers), `sync/` (core git ops), `config/`, `github/`, `codeberg/`, `release/`, `showcase/`, `state/`, `version/`, `cmd/` (cobra wiring).
+- `test/`: integration tests (`run_integration_tests.sh`, `test_*.sh`) and local configs.
+- `doc/`: architecture, API, and development docs. `dist/`: build artifacts.
+
+## Build, Test, and Development Commands
+- Build (current platform): `mage build` or `go build -o gitsyncer ./cmd/gitsyncer`.
+- Cross-compile: `mage buildAll` (linux/darwin/windows variants also available).
+- Run binary: `./gitsyncer --help` or `mage run`.
+- Unit tests (when present): `mage test` or `go test ./...`.
+- Integration tests: `cd test && ./run_integration_tests.sh`.
+- Format/lint: `mage fmt`, `mage vet`, `mage lint` (golangci-lint).
+- Tidy modules: `mage modTidy`.
+
+## Coding Style & Naming Conventions
+- Go formatting: enforce `gofmt`/`go fmt`; prefer `goimports` in your editor.
+- Naming: exported identifiers in CamelCase; acronyms ALLCAPS (ID, URL, API).
+- Errors: wrap with context using `%w` (`fmt.Errorf("context: %w", err)`).
+- Interfaces: accept interfaces, return concrete types where practical.
+
+## Testing Guidelines
+- Frameworks: standard `testing` for unit tests; integration via `test/*.sh`.
+- Add unit tests alongside packages (e.g., `internal/sync/sync_test.go`).
+- Run full suite locally: `go test ./...` then `cd test && ./run_integration_tests.sh`.
+- Prefer meaningful test names: `TestFeature_Behavior` and `test_*.sh` for scripts.
+
+## Commit & Pull Request Guidelines
+- Commits: Conventional Commits format — `type(scope): summary`.
+ - Examples: `feat(sync): add bidirectional mode`, `fix(config): validate organizations`.
+- PRs: clear description, linked issues, testing notes (unit + integration), and updated docs (`doc/` or `README.md`) when user-visible.
+- Keep changes focused; run `mage fmt vet lint` before submitting.
+
+## Security & Configuration Tips
+- Configuration lives at `~/.config/gitsyncer/config.json` (see `gitsyncer.example.json`). Do not commit secrets.
+- Use `--config` and `--work-dir` to target isolated test setups.
+- Debugging: set `GITSYNCER_DEBUG=1` to enable extra logs where supported.