This is an automated email from the ASF dual-hosted git repository.
klesh pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/incubator-devlake.git
The following commit(s) were added to refs/heads/main by this push:
new 5e82fcccf Add AI coding agent instructions to AGENTS.md (#8656)
5e82fcccf is described below
commit 5e82fcccfcc2d9459ad406740c572abe87441d7a
Author: Eldrick Wega <[email protected]>
AuthorDate: Thu Dec 25 07:27:23 2025 -0500
Add AI coding agent instructions to AGENTS.md (#8656)
* add AI coding agent instructions to AGENTS.md
* chore: add license information to AGENTS.md
---------
Co-authored-by: Eldrick Wega <[email protected]>
---
AGENTS.md | 132 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 132 insertions(+)
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 000000000..b896b7af6
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,132 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+# Apache DevLake - AI Coding Agent Instructions
+
+## Project Overview
+Apache DevLake is a dev data platform that ingests data from DevOps tools
(GitHub, GitLab, Jira, Jenkins, etc.), transforms it into standardized domain
models, and enables metrics/dashboards via Grafana.
+
+## Architecture
+
+### Three-Layer Data Model
+1. **Raw Layer** (`_raw_*` tables): JSON data collected from APIs, stored for
replay/debugging
+2. **Tool Layer** (`_tool_*` tables): Plugin-specific models extracted from
raw data
+3. **Domain Layer** (standardized tables): Normalized models in
[backend/core/models/domainlayer/](backend/core/models/domainlayer/) - CODE,
TICKET, CICD, CODEREVIEW, CODEQUALITY, CROSS
+
+### Key Components
+- **backend/**: Go server + plugins (main codebase)
+- **backend/python/**: Python plugin framework via RPC
+- **config-ui/**: React frontend (TypeScript, Vite, Ant Design)
+- **grafana/**: Dashboard definitions
+
+## Plugin Development (Go)
+
+### Plugin Structure
+Each plugin in `backend/plugins/<name>/` follows this layout:
+```
+api/ # REST endpoints (connections, scopes, scope-configs)
+impl/ # Plugin implementation (implements core interfaces)
+models/ # Tool layer models + migrationscripts/
+tasks/ # Collectors, Extractors, Converters
+e2e/ # Integration tests with CSV fixtures
+```
+
+### Required Interfaces
+See [backend/plugins/gitlab/impl/impl.go](backend/plugins/gitlab/impl/impl.go)
for reference:
+- `PluginMeta`: Name, Description, RootPkgPath
+- `PluginTask`: SubTaskMetas(), PrepareTaskData()
+- `PluginModel`: GetTablesInfo() - **must list all models or CI fails**
+- `PluginMigration`: MigrationScripts() for DB schema evolution
+- `PluginSource`: Connection(), Scope(), ScopeConfig()
+
+### Subtask Pattern (Collector → Extractor → Converter)
+```go
+// 1. Register subtask in tasks/register.go via init()
+func init() {
+ RegisterSubtaskMeta(&CollectIssuesMeta)
+}
+
+// 2. Define dependencies for execution order
+var CollectIssuesMeta = plugin.SubTaskMeta{
+ Name: "Collect Issues",
+ Dependencies: []*plugin.SubTaskMeta{}, // or reference other metas
+}
+```
+
+### API Collectors
+- Use `helper.NewStatefulApiCollector` for incremental collection with
time-based bookmarking
+- See
[backend/plugins/gitlab/tasks/issue_collector.go](backend/plugins/gitlab/tasks/issue_collector.go)
+
+### Migration Scripts
+- Located in `models/migrationscripts/`
+- Register all scripts in `register.go`'s `All()` function
+- Version format: `YYYYMMDD_description.go`
+
+## Build & Development Commands
+
+```bash
+# From repo root
+make dep # Install Go + Python dependencies
+make build # Build plugins + server
+make dev # Build + run server
+make godev # Go-only dev (no Python plugins)
+make unit-test # Run all unit tests
+make e2e-test # Run E2E tests
+
+# From backend/
+make swag # Regenerate Swagger docs (required after API changes)
+make lint # Run golangci-lint
+```
+
+### Running Locally
+```bash
+docker-compose -f docker-compose-dev.yml up mysql grafana # Start deps
+make dev # Run server on
:8080
+cd config-ui && yarn && yarn start # UI on :4000
+```
+
+## Testing
+
+### Unit Tests
+Place `*_test.go` files alongside source. Use mocks from `backend/mocks/`.
+
+### E2E Tests for Plugins
+Use CSV fixtures in `e2e/` directory. See
[backend/test/helper/](backend/test/helper/) for the Go test client that can
spin up an in-memory DevLake instance.
+
+### Integration Testing
+```go
+helper.ConnectLocalServer(t, &helper.LocalClientConfig{
+ ServerPort: 8080,
+ DbURL: "mysql://merico:[email protected]:3306/lake",
+ CreateServer: true,
+ Plugins: []plugin.PluginMeta{gitlab.Gitlab{}},
+})
+```
+
+## Python Plugins
+Located in `backend/python/plugins/`. Use Poetry for dependencies. See
[backend/python/README.md](backend/python/README.md).
+
+## Code Conventions
+- Tool model table names: `_tool_<plugin>_<entity>` (e.g.,
`_tool_gitlab_issues`)
+- Domain model IDs: Use `didgen.NewDomainIdGenerator` for consistent
cross-plugin IDs
+- All plugins must be independent - no cross-plugin imports
+- Apache 2.0 license header required on all source files
+
+## Common Pitfalls
+- Forgetting to add models to `GetTablesInfo()` fails
`plugins/table_info_test.go`
+- Migration scripts must be added to `All()` in `register.go`
+- API changes require running `make swag` to update Swagger docs
+- Python plugins require `libgit2` for gitextractor functionality
