Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

Add a CONTRIBUTING guide for tests, docs, and scope — the current one stops at "write tests"

Open Beginner friendly
  • Is something wrong?
#215 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
70/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Active
Tech stack
graphql, nodejs, openapi, typescript
Domain
documentation, testing

Research direction

Start with CONTRIBUTING.md and its table of contents, then check the four test scripts in package.json, test/jest-e2e.json, and the path filter in .github/workflows/build-check.yml so the documented commands match reality. Confirm the generated-file list against the graphql:codegen script and the CI git diff check. Done means the new sections are added, the table of contents is updated, and a maintainer confirms the commands and CI behaviour.

Written by the indexing model from the issue text.

Description

documentation help wanted intermediate refactor

Problem

CONTRIBUTING.md is largely a generic template. The "TypeScript Styleguide" section that exists in its table of contents is thin, and there is no concrete guidance on the things contributors actually get wrong here:

  • Where to put a test. The repo has two conventions in play — 97 colocated *.spec.ts files in src/ (dominant) and 12 spec files under test/ (some of which never run, see the unreachable-specs issue). A new contributor has no way to know which to follow.
  • What actually runs. npm test covers only src/ specs; npm run test:e2e uses test/jest-e2e.json. CI runs a narrower path filter still (.github/workflows/build-check.yml:31-36).
  • How to verify a change. npm run lint uses --fix (package.json:18) and will silently rewrite files.
  • Where generated code goes. src/graphql/client/generated.ts is generated by graphql:codegen and CI asserts it is unchanged with git diff --exit-code — editing it by hand fails the build. docs/openapi.json and sdks/ are likewise generated.
  • When not to open an issue. The README says security issues must go to [email protected]; CONTRIBUTING.md does not mention it, and SECURITY.md does not exist.

Suggested Direction

Add focused sections to CONTRIBUTING.md rather than rewriting it:

  1. Running the tests — the four commands and what each covers, including the e2e suite and the load test at test/portfolio/portfolio-management.loadtest.sh.
  2. Where to put a new test — state colocated-in-src/ as the convention, with test/ reserved for e2e.
  3. Generated files — list src/graphql/client/generated.ts, docs/openapi.json, sdks/**, and say explicitly that CI will fail if they are hand-edited.
  4. Before you open a PR — npx tsc --noEmit, npm run lint (noting --fix), npm test.
  5. Security issues — link to the disclosure channel. Keep it to a link; do not duplicate policy content here.
  6. Module boundaries — point at docs/ARCHITECTURE.md (once it exists) for where new code belongs.

Constraints

  • Match the existing tone and heading structure; the document already has a table of contents that must be updated.
  • Do not invent a contribution agreement, CLA, or DCO requirement — ask a maintainer first.
  • Keep the Code of Conduct reference intact.
  • Do not promise response times or review SLAs unless a maintainer has agreed to them.

Acceptance Criteria

  • CONTRIBUTING.md documents how to run each test suite and what it covers.
  • The generated-files list is present and matches the CI workflow.
  • The security disclosure channel is referenced.
  • The table of contents is updated with the new sections.
  • A maintainer has reviewed the operational claims (commands, CI behaviour).
Dominant language
TypeScript
Stars
7
Forks
55
Avg merge
1d 17h
Merged PRs (30d)
5

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 SourceXXL/alian_structure-api

All issues in SourceXXL/alian_structure-api

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.