Clean up inconsistencies in project documentation

Open Beginner friendly
  • Is something wrong?
#118 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
markdown, shell
Domain
documentation, tooling

Research direction

Each checklist item names a file and line: README.md line 1371, CONTRIBUTING.md lines 89 and 101, tsc/project_intake.md line 7, and GOVERNANCE.md line 59 against RELEASE.md line 9. Check the scripts in scripts/ (check-format.sh, fix-format.sh, check-lint.sh) to confirm which tools they run before editing CONTRIBUTING.md. Done when the four fixes are made and the optional just recipe item is either implemented or left unticked.

Written by the indexing model from the issue text.

Description

documentation

A read through the project Markdown files turned up a few small inconsistencies. None affect the library itself.

Tasks

  • Fix generator example in README.md. Line 1371 shows
    just setup `Unix Makefiles` with backticks, which the shell runs as a
    command substitution. It should be just setup 'Unix Makefiles'.
  • Update Python tooling in CONTRIBUTING.md. Lines 89 and 101 mention
    Black and Flake8, but scripts/check-format.sh, scripts/fix-format.sh and
    scripts/check-lint.sh use ruff and ty.
  • Fix missing link in tsc/project_intake.md. Line 7 links to
    THIRD_PARTY.md, which doesn't exist. Either add the file (dependencies are
    listed under Dependencies in README.md) or update the link.
  • Align release cadence wording. GOVERNANCE.md line 59 says releases
    occur "on a scheduled basis", while RELEASE.md line 9 says they're "not
    based on a regular time period". GOVERNANCE.md could point to RELEASE.md.
  • Optional: add just recipes for checks. Recipes such as just format
    and just lint would wrap the scripts in scripts/, so every common command
    goes through just. If added, update README.md and AGENTS.md to match.
Dominant language
C++
Stars
106
Forks
7
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 AcademySoftwareFoundation/openqmc

All issues in AcademySoftwareFoundation/openqmc

Similar issues

More C++ issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.