docs: Add agent docs - #7983
Merged
Merged
Conversation
camdecoster
added
the
no-draftlog
emilykl
reviewed
Aug 24, 2026
|
|
||
| The methods you touch most: | ||
|
|
||
| - `attributes` - the JSON-serializable attribute declarations that feed the schema |
Contributor
There was a problem hiding this comment.
nit: attributes isn't a function/method but rather an object.
emilykl
reviewed
Aug 24, 2026
|
|
||
| ## The schema | ||
|
|
||
| `test/plot-schema.json` is generated output that records the proposed API. Any change to an attribute or an attribute description changes this file. |
Contributor
There was a problem hiding this comment.
Suggested change
| `test/plot-schema.json` is generated output that records the proposed API. Any change to an attribute or an attribute description changes this file. | |
| `test/plot-schema.json` is generated output that captures the full plotly.js API. Any change to an attribute or an attribute description changes this file. |
emilykl
reviewed
Aug 24, 2026
|
|
||
| Format only files you created. Never pass a directory, and never format a file that already existed. The CLI formats a whole file at a time, and this repository is not formatted from end to end, so either one rewrites lines your change never touched and buries the real diff. | ||
|
|
||
| In an existing file, write the lines you add by hand, to the settings above. That means single quotes, a four-space indent, no trailing comma, and no line past 120 columns. The settings are the house style, so follow them even when the lines around yours predate them. If you formatted such a file by accident, undo your changes and redo the edit. |
Contributor
There was a problem hiding this comment.
Suggested change
| In an existing file, write the lines you add by hand, to the settings above. That means single quotes, a four-space indent, no trailing comma, and no line past 120 columns. The settings are the house style, so follow them even when the lines around yours predate them. If you formatted such a file by accident, undo your changes and redo the edit. | |
| In an existing file, write the lines you add by hand, to follow the rules outlined in `biome.json`. The settings are the house style, so follow them even when the lines around yours predate them. If you formatted such a file by accident, undo your changes and redo the edit. |
IMO it's better not to list specific rules here, to avoid confusion if we change formatting rules in the future. Just point to the rules file.
emilykl
reviewed
Aug 24, 2026
|
|
||
| ## Formatting | ||
|
|
||
| Biome owns formatting. The JavaScript rules live in `biome.json`: single quotes, a four-space indent, no trailing commas, and a 120 column line width. |
Contributor
There was a problem hiding this comment.
Suggested change
| Biome owns formatting. The JavaScript rules live in `biome.json`: single quotes, a four-space indent, no trailing commas, and a 120 column line width. | |
| Biome owns formatting. The JavaScript rules live in `biome.json`. |
emilykl
reviewed
Aug 24, 2026
| - [ ] A human asked for the pull request. If nobody asked, you open the issue and stop. | ||
| - [ ] A human reviewed the code | ||
| - [ ] You saw the rendered plot, for any change that moves pixels | ||
| - [ ] You read the last few merged pull requests and matched their shape |
Contributor
There was a problem hiding this comment.
Suggested change
| - [ ] You read the last few merged pull requests and matched their shape | |
| - [ ] You read the last few merged pull requests by library maintainers and matched their shape |
emilykl
reviewed
Aug 24, 2026
| ## Generated output | ||
|
|
||
| - [ ] `npm run schema` ran after any attribute or description edit | ||
| - [ ] `test/plot-schema.json` and `src/types/generated/schema.d.ts` are staged |
Contributor
There was a problem hiding this comment.
Suggested change
| - [ ] `test/plot-schema.json` and `src/types/generated/schema.d.ts` are staged | |
| - [ ] `test/plot-schema.json` and `src/types/generated/schema.d.ts` are committed if needed |
emilykl
reviewed
Aug 24, 2026
|
|
||
| ## Image tests | ||
|
|
||
| An image test is a mock plus a baseline PNG. |
Contributor
There was a problem hiding this comment.
Suggested change
| An image test is a mock plus a baseline PNG. | |
| An image test is a JSON mock file plus a baseline PNG image. |
emilykl
reviewed
Aug 24, 2026
|
|
||
| `--nowatch` turns off the watch mode, so the run exits after one pass instead of waiting for the next file change. Pass the exact file basename without the `_test.js` suffix, which the karma config appends for you. The name is not a substring: `-- bar` runs `bar_test.js` alone, and a partial name such as `hover_lab` matches no file, so the run finds nothing to do. Several names in one command run several suites. | ||
|
|
||
| Write a test for every behavior change. A bug fix needs a test that fails before the fix. |
Contributor
There was a problem hiding this comment.
Suggested change
| Write a test for every behavior change. A bug fix needs a test that fails before the fix. | |
| Write or modify a test for every behavior change. A bug fix needs a test that fails before the fix. |
emilykl
previously approved these changes
Aug 24, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Add agent docs to the repo.
Closes #7982.
Changes
Testing
Read through the instructions.