Clean up in-repo dev docs (HF-65) by sequba · Pull Request #1682 · handsontable/hyperformula

sequba · 2026-05-25T13:12:07Z

Context

The in-repo developer documentation was scattered across several files with significant duplication:

CLAUDE.md duplicated build/test commands (also in docs/guide/building.md), contributing rules (also in CONTRIBUTING.md / docs/guide/contributing.md), and translation sources (also in DEV_DOCS.md).
CONTRIBUTING.md was an almost-verbatim copy of docs/guide/contributing.md.
DEV_DOCS.md contained only a small subset of what a developer needs.
Cursor-specific guidance did not exist.

This PR removes the duplication and gives both humans and AI agents a single, predictable entry point.

New structure

File	Role
`DEV_DOCS.md`	Canonical dev docs. Project overview, architecture, code style, definition of done, how to add a function, translation sources, plus quick links to the build / contributing / test docs.
`docs/guide/building.md`	Full description of build, verify, docs, test, and lint commands, including output formats. Public, for users and devs.
`docs/guide/contributing.md`	Full contributor guide. Public, for users and devs.
`AGENTS.md`	Pointer to `DEV_DOCS.md` plus rules specific to AI agents (attribution, response style).
`CLAUDE.md`	Pointer to `AGENTS.md`.
`.cursor/rules/main.mdc`	Cursor rule that points to `AGENTS.md` (always applied).
`CONTRIBUTING.md`	Pointer to `docs/guide/contributing.md`.

How did you test your changes?

Manual review of the resulting file set:

DEV_DOCS.md contains everything a developer needs and links to docs/guide/building.md, docs/guide/contributing.md, docs/guide/code-of-conduct.md, test/README.md, docs/README.md, CHANGELOG.md, and .github/pull_request_template.md.
AGENTS.md links to DEV_DOCS.md and only adds agent-specific rules.
CLAUDE.md, .cursor/rules/main.mdc, and CONTRIBUTING.md are thin pointers with no duplicated content.
docs/guide/building.md is the only place that lists build/test/lint commands and bundle output formats.
docs/guide/contributing.md is unchanged (it already covered the contributor flow in full).

Types of changes

Breaking change (a fix or a feature because of which an existing functionality doesn't work as expected anymore)
New feature or improvement (a non-breaking change that adds functionality)
Bug fix (a non-breaking change that fixes an issue)
Additional language file, or a change to an existing language file (translations)
Change to the documentation

Related issues

HF-65

Checklist

I have reviewed the guidelines about Contributing to HyperFormula and I confirm that my code follows the code style of this project.
I have signed the Contributor License Agreement.
My change is compliant with the OpenDocument standard.
My change is compatible with Microsoft Excel.
My change is compatible with Google Sheets.
I described my changes in the CHANGELOG.md file.
My changes require a documentation update.
My changes require a migration guide.

netlify · 2026-05-25T13:12:14Z

✅ Deploy Preview for hyperformula-dev-docs ready!

Name	Link
🔨 Latest commit	`df801c8`
🔍 Latest deploy log	https://app.netlify.com/projects/hyperformula-dev-docs/deploys/6a181da8731fbf000912d295
😎 Deploy Preview	https://deploy-preview-1682--hyperformula-dev-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

qunabu · 2026-05-25T13:12:14Z

Task linked: HF-65 Clean up the dev docs in the repo

github-actions · 2026-05-25T13:27:10Z

Performance comparison of head (`df801c8`) vs base (`c7cfc9d`)

                                     testName |   base |   head | change
------------------------------------------------------------------------
                                      Sheet A | 468.19 | 466.05 | -0.46%
                                      Sheet B | 148.01 | 149.28 | +0.86%
                                      Sheet T | 135.27 |    134 | -0.94%
                                Column ranges | 531.85 |  532.9 | +0.20%
Sheet A:  change value, add/remove row/column |  13.84 |  14.55 | +5.13%
 Sheet B: change value, add/remove row/column | 124.14 | 124.49 | +0.28%
                   Column ranges - add column | 152.04 | 153.08 | +0.68%
                Column ranges - without batch | 473.67 | 476.74 | +0.65%
                        Column ranges - batch | 122.31 | 117.15 | -4.22%

sequba

@cursoragent fix these issues

cursor · 2026-05-25T13:36:35Z

All review comments addressed. Pushed 3 new commits to PR #1682.

Changes made:

Comment	Change
AGENTS.md: "Remove this rule" (Communication and attribution)	Section removed
AGENTS.md: mention README + docs page	Added "For additional context, also consult…" block linking to `README.md` and `https://hyperformula.handsontable.com/docs`
AGENTS.md: section about common agent failures	Added `## Common ways agents fail` section with hidden HTML-comment template for new items, currently `_No items yet._`
CLAUDE.md: make it a unix link	Replaced with symlink → `AGENTS.md` (git mode 120000)
CONTRIBUTING.md: make it a unix link	Replaced with symlink → `docs/guide/contributing.md` (git mode 120000)
DEV_DOCS.md: add directory tree	Added `## Repository layout` with full annotated tree
DEV_DOCS.md: contributing guide is for external contributors only	Removed from Quick links; reframed audience as "maintainers, the internal team, and AI agents triggered by them"
DEV_DOCS.md: docs URL → `/docs`	Updated
DEV_DOCS.md: remove Project overview	Section removed
DEV_DOCS.md: merge i18n with translation sources	Architecture's `### i18n` subsection removed; `## Sources of the function translations` renamed to `## Internationalization and function translations` and absorbed the i18n details

New commits:

docs(agents): drop attribution rule, point to README/docs, add failure log
docs(dev): add repo tree, scope to internal team, fold i18n notes
docs: replace CLAUDE.md and CONTRIBUTING.md pointer files with symlinks

sequba

fix issues

sequba · 2026-05-25T13:51:26Z

@cursoragent fix issues

cursor · 2026-05-25T13:51:33Z

All requested fixes applied in commit 9639e3b96.

Changes:

Comment	Change
DEV_DOCS.md: remove Code of conduct link	Removed from Quick links
DEV_DOCS.md: "end-user documentation" → "main documentation"	Applied
AGENTS.md: "full end-user documentation" → "main documentation"	Applied
DEV_DOCS.md: hide test/ subitems	`test/` line collapsed to just `# Test suite`
DEV_DOCS.md: remove `examples/`	Removed
DEV_DOCS.md: remove `.cursor/rules/`	Removed
DEV_DOCS.md: remove `CLAUDE.md`	Removed
DEV_DOCS.md: README description → "Project overview"	Applied
DEV_DOCS.md: remove `CODE_OF_CONDUCT.md`	Removed

sequba

@cursoragent fix

cursor · 2026-05-25T14:09:25Z

All review comments addressed in 2 new commits.

Changes:

Comment	Change
DEV_DOCS.md: collapse `i18n/` and `languages/` tree lines	Combined into `│ └── i18n/ # Function-name translations per language`
DEV_DOCS.md: CONTRIBUTING.md description suggestion	Changed to `# Guide for external contributors`
AGENTS.md: replace http link with markdown sources in `docs/api`/`docs/guide`	"For additional context" block now lists `docs/guide/` (user-facing guides) and `docs/api/` (API reference, generated from JSDoc — `npm run docs:build` if missing), with explicit "Prefer reading these local files over fetching the rendered documentation from the web."

New commits:

docs(dev): collapse i18n tree and clarify CONTRIBUTING.md role
docs(agents): point agents at local docs/guide and docs/api markdown

sequba

@cursoragent

sequba · 2026-05-25T14:18:42Z

@cursoragent fix issues from my last review

cursor · 2026-05-25T14:18:49Z

All four review comments addressed in 2 new commits.

Changes:

Comment	Change
AGENTS.md "Start here" paragraph	Replaced with the suggested one-liner: `Whatever you do, start by reading entire DEV_DOCS.md. Only then proceed to your task.`
AGENTS.md "For additional context, also consult:"	Promoted to heading `## Other important resources`
DEV_DOCS.md "Public docs source" link	Renamed to `Docs README`
DEV_DOCS.md "How to add a new function"	Added link to `docs/guide/custom-functions.md` with a brief note explaining the overlap with custom functions

New commits:

docs(agents): tighten 'Start here' and rename resources section
docs(dev): rename Docs README link and reference custom-functions guide

sequba

@cursoragent fix

cursor · 2026-05-26T09:57:30Z

The remaining new comment is addressed.

Change in commit 9163d9035:

Comment	Change
AGENTS.md: "Add section about skills, MCPs and other tools for agents (No items yet)"	Added a new `## Skills, MCPs, and other agent tools` section mirroring the `## Common ways agents fail` pattern (intro sentence, HTML-comment template for new items, `_No items yet._` placeholder)

The earlier "fix" comments (suggestions for README.md # Project overview, i18n/, CONTRIBUTING.md # Guide for external contributors, Whatever you do, start by reading…, ## Other important resources, Docs README, link to docs/guide/custom-functions.md, and the docs/api/docs/guide markdown instruction) were already resolved in earlier commits — this commit only adds the one new requested section.

sequba · 2026-05-26T09:59:31Z

@marcin-kordas-hoc please, review these changes

marcin-kordas-hoc

Reviewed. Good cleanup — DEV_DOCS.md becoming the canonical entry point is the right call and the expanded content is well-structured.

Fixes applied in my commit (0de2c7a73):

DEV_DOCS.md Quick links was missing docs/guide/contributing.md and docs/guide/code-of-conduct.md, which the PR description claimed were linked — added both
Repository tree diagram used ```text (unsupported fence in VuePress 1) — changed to ```
AGENTS.md Response style was missing the LLM no-mention rule that existed in the old CLAUDE.md — carried it over

Still needs attention before merge:

PR template checkboxes — 11 items unchecked. For a docs-only PR most are N/A (CLA, Excel/GSheets compat, migration guide, changelog). Please tick them off or mark N/A so the template is complete.
Symlinks on Windows (informational) — CLAUDE.md and CONTRIBUTING.md are now git symlinks (mode 120000). On Windows without developer mode enabled, these materialise as plain text files containing the link target path. Not a blocker since the internal team works on Linux/Mac, but worth knowing if we ever want external Windows contributors to get the full content in-editor.
DEV_DOCS.md repo tree shows script/ — the repo also has a scripts/ directory now (maintenance tooling), so the tree is slightly out of date. Minor.

Overall: approve pending checkbox cleanup.

Co-authored-by: Kuba Sekowski <sequba@users.noreply.github.com>

Make DEV_DOCS.md the canonical reference for everyone working on the source code. It now contains: - quick links to building, contributing, code of conduct, tests, etc. - project overview - architecture (core modules, function plugins, i18n) - how to add a new function - code style - definition of done - sources of function translations Existing content (definition of done, translation sources) is preserved and grouped with the new sections so that information is no longer duplicated across CLAUDE.md and other files. Co-authored-by: Kuba Sekowski <sequba@users.noreply.github.com>

- AGENTS.md links to DEV_DOCS.md and adds rules that are specific to AI agents (attribution, response style). - CLAUDE.md is reduced to a pointer to AGENTS.md. - .cursor/rules/main.mdc is added so Cursor agents are routed to AGENTS.md as well. This removes the duplication that previously existed between CLAUDE.md and DEV_DOCS.md / docs/guide/building.md / docs/guide/contributing.md. Co-authored-by: Kuba Sekowski <sequba@users.noreply.github.com>

CONTRIBUTING.md duplicated docs/guide/contributing.md almost verbatim. Reduce it to a single link so that the docs portal version is the canonical source. Co-authored-by: Kuba Sekowski <sequba@users.noreply.github.com>

…e log Address PR review: - Remove the 'Communication and attribution' rule. - Update 'Start here' to point readers at the repository README and the public documentation portal in addition to DEV_DOCS.md. - Add a 'Common ways agents fail' section. The team will append items to it whenever an agent makes a mistake worth flagging, so future agents read it before starting non-trivial tasks. Co-authored-by: Kuba Sekowski <sequba@users.noreply.github.com>

Address PR review: - Reframe the audience: maintainers, internal team, and AI agents triggered by them. Drop the contributing-guide link from the quick links since that document targets external contributors. - Update the public docs portal URL to the canonical /docs path. - Add a repository directory tree so people can navigate the repository quickly. - Drop the redundant 'Project overview' section. - Fold the architecture i18n subsection into the function-translations section so all i18n information lives in one place. Co-authored-by: Kuba Sekowski <sequba@users.noreply.github.com>

Address PR review: instead of one-line pointer files, make them filesystem symlinks so any tool that opens them sees the target content directly: - CLAUDE.md -> AGENTS.md - CONTRIBUTING.md -> docs/guide/contributing.md Co-authored-by: Kuba Sekowski <sequba@users.noreply.github.com>

Address PR review: - DEV_DOCS.md and AGENTS.md: describe the public portal as 'main documentation' (per reviewer suggestion). - DEV_DOCS.md: drop the Code of conduct link from quick links. - DEV_DOCS.md: collapse the test/ subtree, and remove tree entries for examples/, .cursor/rules/, CLAUDE.md, and CODE_OF_CONDUCT.md so the layout focuses on navigation-relevant directories. - DEV_DOCS.md: simplify the README.md description to 'Project overview'. Co-authored-by: Kuba Sekowski <sequba@users.noreply.github.com>

The previous run failed only on the build (24, windows-latest, ci) matrix slot in 19s with no npm output captured. All other 17 matrix combinations passed, the same slot passed on the previous commit of this branch (f922598), and this branch only touches markdown files, so the failure is unrelated to the changes. Co-authored-by: Kuba Sekowski <sequba@users.noreply.github.com>

Address PR review: - Collapse src/i18n/ and src/i18n/languages/ into a single tree entry per reviewer suggestion. - Describe CONTRIBUTING.md as 'Guide for external contributors' instead of leaking the symlink target. Co-authored-by: Kuba Sekowski <sequba@users.noreply.github.com>

Address PR review: replace the link to the rendered documentation portal with pointers to the markdown sources in docs/guide/ and docs/api/, so agents read local files rather than fetching from the web. Note that docs/api/ is generated from JSDoc and requires running npm run docs:build if it is missing. Co-authored-by: Kuba Sekowski <sequba@users.noreply.github.com>

Per reviewer suggestions: - Replace the long 'Start here' paragraph with a direct one-sentence instruction to read DEV_DOCS.md first. - Promote 'For additional context, also consult:' to a proper 'Other important resources' heading. Co-authored-by: Kuba Sekowski <sequba@users.noreply.github.com>

Per reviewer suggestions: - Rename the 'Public docs source' quick link to 'Docs README'. - In 'How to add a new function', point readers at docs/guide/custom-functions.md because adding a built-in function follows the same function-implementation patterns as adding a custom function. Co-authored-by: Kuba Sekowski <sequba@users.noreply.github.com>

Add an empty 'Skills, MCPs, and other agent tools' section that mirrors the 'Common ways agents fail' section so the team can list any skills, MCP servers, or other tools vetted as useful for agents working on this codebase. Co-authored-by: Kuba Sekowski <sequba@users.noreply.github.com>

- DEV_DOCS.md: add contributing guide and code of conduct to Quick links (PR description claimed they were linked; they weren't) - DEV_DOCS.md: change unsupported \`\`\`text fence to \`\`\` (VuePress 1) - AGENTS.md: add LLM no-mention rule carried over from old CLAUDE.md ("do not mention AI tool names in commits, PRs, comments, docs")

codecov · 2026-05-28T11:06:24Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.16%. Comparing base (c7cfc9d) to head (df801c8).

Additional details and impacted files

@@           Coverage Diff            @@
##           develop    #1682   +/-   ##
========================================
  Coverage    97.16%   97.16%           
========================================
  Files          176      176           
  Lines        15322    15322           
  Branches      3356     3356           
========================================
  Hits         14887    14887           
  Misses         427      427           
  Partials         8        8

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

sequba marked this pull request as ready for review May 25, 2026 13:35

sequba commented May 25, 2026

View reviewed changes

Comment thread DEV_DOCS.md Outdated

Comment thread AGENTS.md Outdated

Comment thread DEV_DOCS.md Outdated

sequba commented May 25, 2026

View reviewed changes

Comment thread AGENTS.md Outdated

Comment thread AGENTS.md Outdated

Comment thread DEV_DOCS.md Outdated

Comment thread DEV_DOCS.md

sequba commented May 26, 2026

View reviewed changes

Comment thread AGENTS.md

sequba self-assigned this May 26, 2026

sequba requested a review from marcin-kordas-hoc May 26, 2026 09:59

marcin-kordas-hoc reviewed May 28, 2026

View reviewed changes

cursoragent and others added 10 commits May 28, 2026 10:39

docs(building): document output formats and reorder intro

116fafb

Co-authored-by: Kuba Sekowski <sequba@users.noreply.github.com>

docs(contributing): replace duplicate file with pointer

d66c507

CONTRIBUTING.md duplicated docs/guide/contributing.md almost verbatim. Reduce it to a single link so that the docs portal version is the canonical source. Co-authored-by: Kuba Sekowski <sequba@users.noreply.github.com>

cursoragent and others added 4 commits May 28, 2026 10:39

marcin-kordas-hoc force-pushed the feature/cleanup-dev-docs-9526 branch from 0de2c7a to a4506ff Compare May 28, 2026 10:39

marcin-kordas-hoc force-pushed the feature/cleanup-dev-docs-9526 branch from a4506ff to df801c8 Compare May 28, 2026 10:49

Conversation

sequba commented May 25, 2026

Context

New structure

How did you test your changes?

Types of changes

Related issues

Checklist

Uh oh!

netlify Bot commented May 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for hyperformula-dev-docs ready!

Uh oh!

qunabu commented May 25, 2026

Uh oh!

github-actions Bot commented May 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Performance comparison of head (df801c8) vs base (c7cfc9d)

Uh oh!

sequba left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cursor Bot commented May 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sequba left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sequba commented May 25, 2026

Uh oh!

cursor Bot commented May 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sequba left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cursor Bot commented May 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sequba left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sequba commented May 25, 2026

Uh oh!

cursor Bot commented May 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sequba left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cursor Bot commented May 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

netlify Bot commented May 25, 2026 •

edited

Loading

github-actions Bot commented May 25, 2026 •

edited

Loading

Performance comparison of head (`df801c8`) vs base (`c7cfc9d`)

cursor Bot commented May 25, 2026 •

edited

Loading

cursor Bot commented May 25, 2026 •

edited

Loading

cursor Bot commented May 25, 2026 •

edited

Loading

cursor Bot commented May 25, 2026 •

edited

Loading

cursor Bot commented May 26, 2026 •

edited

Loading