From dc34f61b5f303520f525a493fa40781e19d1a8cf Mon Sep 17 00:00:00 2001 From: Justin-ZS Date: Thu, 16 Apr 2026 17:29:30 +0800 Subject: [PATCH 1/4] docs: add agents guide for contributors --- AGENTS.md | 61 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 61 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000000..c56a174874 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,61 @@ +# AGENTS.md + +## Overview + +Apache ECharts is a TypeScript-first charting library. Most runtime code lives in `src/`, while build scripts, test utilities, and packaging logic live alongside it in dedicated top-level folders. + +One thing worth knowing early is that this repo is assembled through explicit registration and curated entry files. New runtime code often needs to be connected not only in its local module, but also through public exports or bundle entry files before it becomes part of a user-facing build. + +## Project Layout + +- `src/`: built-in charts, components, coordinate systems, models, renderers, features, themes, and i18n source +- `src/export/*.ts`: public modular export surfaces +- `src/echarts.all.ts`, `src/echarts.common.ts`, `src/echarts.simple.ts`, `src/echarts.ts`: main bundle entry files +- `extension-src/`: separately packaged extensions +- `ssr/client/src/`: SSR client source +- `build/`: build, packaging, prepublish, and generation scripts +- `test/ut/spec/`: Jest unit tests +- `test/*.html`: browser-based rendering and interaction cases + +## Source And Generated Files + +In general, `src/` is the main source of truth for built-in library behavior. + +Some top-level files and folders are generated or packaging-oriented: + +- `i18n/*.js` and `i18n/*-obj.js` are generated from `src/i18n/*.ts` +- `lib/`, `types/`, `extension/`, `ssr/client/lib/`, `ssr/client/types/`, and root `index*.js` are produced by the build/prepublish flow +- `dist/` contains build output + +The top-level `theme/*.js` files are packaged theme sources rather than normal `src/theme/` runtime modules, so they are best treated separately from the generated locale/build artifacts above. + +## Exports And Entry Files + +This repo exposes functionality at a few different layers: + +- local runtime modules under `src/` +- modular public exports under `src/export/*.ts` +- bundled entry files under `src/echarts*.ts` + +Because of that structure, changes to charts, components, renderers, or features sometimes need corresponding updates in exports or entry files to show up in the expected public build. + +## Testing + +The repository uses two main testing styles: + +- Jest tests in `test/ut/spec/` for logic-heavy behavior such as models, utilities, data transforms, and API behavior +- HTML cases in `test/` for rendering, layout, interaction, and visual regressions + +For local development, `npm run dev` starts the watch build and opens the `test/` directory. New HTML cases can be scaffolded with `npm run mktest`. + +## Common Checks + +- `npm run checktype` +- `npm run lint` +- `npm test` +- `npm run test:dts:fast` +- `npm run dev` + +## Style Notes + +This repository consistently keeps ASF license headers in source and test files, and the codebase style is stable: single quotes, semicolons, and 4-space indentation are the norm. Small changes that follow nearby patterns tend to fit best here. From fdf18d113b4a32fccb98be6084084f0579f4cae5 Mon Sep 17 00:00:00 2001 From: Justin-ZS Date: Thu, 16 Apr 2026 17:37:08 +0800 Subject: [PATCH 2/4] docs: refine agents guide with contributor docs --- AGENTS.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index c56a174874..1e48351011 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,6 +6,16 @@ Apache ECharts is a TypeScript-first charting library. Most runtime code lives i One thing worth knowing early is that this repo is assembled through explicit registration and curated entry files. New runtime code often needs to be connected not only in its local module, but also through public exports or bundle entry files before it becomes part of a user-facing build. +## Contributor Docs + +When a task touches contribution workflow, prefer the repo's own contributor-facing documents over this summary: + +- `CONTRIBUTING.md` for general contribution guidance +- `.github/pull_request_template.md` for PR structure +- `.github/workflows/` for CI expectations + +This file is only a short orientation note. If there is any conflict, the repo's dedicated contributor docs should win. + ## Project Layout - `src/`: built-in charts, components, coordinate systems, models, renderers, features, themes, and i18n source From 6225ce0d03cb4d481712171df079f7866d615d98 Mon Sep 17 00:00:00 2001 From: Justin-ZS Date: Thu, 16 Apr 2026 17:41:18 +0800 Subject: [PATCH 3/4] docs: add pull request wiki guidance --- AGENTS.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 1e48351011..0ce45c303e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -11,11 +11,18 @@ One thing worth knowing early is that this repo is assembled through explicit re When a task touches contribution workflow, prefer the repo's own contributor-facing documents over this summary: - `CONTRIBUTING.md` for general contribution guidance +- `https://github.com/apache/echarts/wiki/How-to-make-a-pull-request` for PR workflow, test expectations, and git message conventions - `.github/pull_request_template.md` for PR structure - `.github/workflows/` for CI expectations This file is only a short orientation note. If there is any conflict, the repo's dedicated contributor docs should win. +A few stable rules from the PR wiki are especially worth keeping in mind: + +- In non-release PRs, avoid committing `dist/`, `i18n/`, and `ssr/client/dist/`. +- Follow the repo's PR template when opening or updating a pull request. +- Git messages follow the repo convention: `(): . close #`, with the issue-closing suffix omitted when there is no related issue. + ## Project Layout - `src/`: built-in charts, components, coordinate systems, models, renderers, features, themes, and i18n source From f64ba6b671600cf3242cf18e19931e81f3f0dfa3 Mon Sep 17 00:00:00 2001 From: Justin-ZS Date: Thu, 16 Apr 2026 17:47:39 +0800 Subject: [PATCH 4/4] docs: add wiki guidance to agents guide --- AGENTS.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 0ce45c303e..6d9ece6465 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -12,6 +12,8 @@ When a task touches contribution workflow, prefer the repo's own contributor-fac - `CONTRIBUTING.md` for general contribution guidance - `https://github.com/apache/echarts/wiki/How-to-make-a-pull-request` for PR workflow, test expectations, and git message conventions +- `https://github.com/apache/echarts/wiki/How-to-setup-the-dev-environment` for local setup and zrender-linked development +- `https://github.com/apache/echarts/wiki/Security-Checklist-for-Code-Contributors` for security-sensitive API and API-design checks - `.github/pull_request_template.md` for PR structure - `.github/workflows/` for CI expectations @@ -22,6 +24,8 @@ A few stable rules from the PR wiki are especially worth keeping in mind: - In non-release PRs, avoid committing `dist/`, `i18n/`, and `ssr/client/dist/`. - Follow the repo's PR template when opening or updating a pull request. - Git messages follow the repo convention: `(): . close #`, with the issue-closing suffix omitted when there is no related issue. +- If you need to work on linked `zrender` code, the dev-environment wiki recommends using an absolute symlink at `node_modules/zrender` instead of `npm link`, because the watch flow depends on that setup. +- Be cautious with security-sensitive web APIs such as `innerHTML`, arbitrary DOM selectors, `eval`-like execution, raw style injection, and navigation-related APIs. If a feature must allow that kind of behavior, the security checklist expects clear documentation warnings. ## Project Layout