CONTRIBUTING lacks dev setup and the test and lint conventions

Open Beginner friendly
  • Is something wrong?
#47 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
78/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Active
Tech stack
eslint, github, javascript, node.js
Domain
developer-experience, documentation

Research direction

Start with .github/CONTRIBUTING.md, then check README.md, eslint.config.js, tests/unit/pieces.test.js, and package.json against the conventions listed in the issue. Document Node 20, installation and the three scripts, CommonJS exports, test wiring, and per-file ESLint globals; add the community document links to the README. Done when a newcomer can follow the documented steps to add a cross-file function and run lint and tests.

Written by the indexing model from the issue text.

Description

documentation severity: medium

Summary

.github/CONTRIBUTING.md is 14 lines and only says to run lint and tests. It leaves out the conventions a contributor needs in order to add or move a function without lint and test failures.

Where

  • .github/CONTRIBUTING.md:1-14
  • README.md:137-144, README.md:214-217, README.md:304-313
  • eslint.config.js:35-80, tests/unit/pieces.test.js:9-20, package.json:8-10

Details

  • How source files become testable. Each js/*.js ends with a CommonJS footer, and each test rebuilds the globals by hand in dependency order. A new function needs the footer export and the wiring in every suite that loads it.
  • ESLint globals are listed per file. Calling a function from another file fails lint with no-undef until eslint.config.js is edited.
  • Node version. CI uses Node 20; there is no engines field, .nvmrc or mention in the docs.
  • npm run format. The script exists but is not documented.
  • Two ESLint configs. Nothing says that eslint.config.js is live and .eslintrc.cjs is ignored.
  • README links. The README does not link CONTRIBUTING, SECURITY or the Code of Conduct, and its tree omits them.

Impact

A first-time contributor who adds a helper in one file and calls it from another gets a lint failure and a ReferenceError in tests, with nothing explaining either.

Suggested fix

Add a "Development" section: Node version, npm install, the three scripts, the export-footer and test-wiring pattern, and the per-file globals rule. Link the community files from the README.

Acceptance criteria

  • A new contributor can add a cross-file function using only the documented steps

Getting started

  • Relevant files: .github/CONTRIBUTING.md, README.md
  • How to run tests: npm install, then npm test and npm run lint
  • Related docs: docs/ARCHITECTURE.md, .github/CONTRIBUTING.md

Filed by repo-audit/full-audit at 8a2c86c. Severity: medium. Effort: S. audit-key: documentation|.github/CONTRIBUTING.md|dev-setup

Dominant language
JavaScript
Stars
4
Forks
2
No merged PRs in 30d

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from TMHSDigital/Static_Chess

All issues in TMHSDigital/Static_Chess

Similar issues

More JavaScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.