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

docs: README examples no longer match v0.21.0's output

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

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
77/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Active
Tech stack
go
Domain
documentation

Research direction

Start with the cited sections in README.md: the examples around lines 1472–1525, the -V=full description, malformed-directive table, and line-number examples. Run the documented commands at commit 510cad4 and compare their output with each README block. Update stale or incomplete examples and statements, choose one line-number convention, and add a golden test for the survey and inspect blocks if practical; done when the documented output and claims match the commands.

Written by the indexing model from the issue text.

Description

documentation P3

These were checked by running the commands at 510cad4.

Example output

  • "Silencing an unused report" (README.md:591-594): it runs plain declscope ./..., which is strict by default, but shows the loose wording nothing it reaches takes a scope. v0.21.0 prints …on B: it already has shared scope, and the same for T.F.

  • Survey and inspect samples (README.md:1472-1525): several numbers are out of date, and rows are silently left out.

    Item README v0.21.0
    Survey declared 20 29
    markdown → cell mutual empty yes
    markdown → cell reached 7 of 10 7 of 18
    markdown → sink 5 of 17, 28 uses 5 of 18, 25 uses
    golden → (core) 4 of 78 4 of 79
    format → json 2 of 105 2 of 107
    Open declarations 114 109

    The survey sample leaves out the Packages — qualify table. The inspect sample drops rows such as json → summary from the middle of the table, and cuts the "Declarations crossed" sentence short.

Statements

  • -V=full (README.md:227) says "A build from a checkout answers devel". go build in a checkout answers a VCS version. Only go run, or a build with -buildvcs=false, answers devel.

  • The malformed-directive table (README.md:628-630) gives one directive's message for another:

    Input README Actual
    //declscope:core twice duplicate declscope:namespace directive duplicate declscope:core directive
    Two identical ignores duplicate declscope:shared directive duplicate declscope:ignore directive
    A stray //declscope:core declscope:namespace must appear… declscope:core must appear…

  • Line numbers are counted two ways. Most examples treat the // file.go caption as outside the file (lines 114-115, 770-778, 1066 and 1159). The strict-fix example (534-537) and the account.go example (1100) count it as line 1.

Suggested fix

  • Regenerate the samples, or mark them as excerpts.
  • Use <name> in the message table.
  • Pick one convention for line numbers.
  • A golden test over the survey and inspect README blocks would keep them from drifting again.
Dominant language
Go
Stars
42
Forks
1
Avg merge
1h 18m
Merged PRs (30d)
94

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

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 mpyw/declscope

All issues in mpyw/declscope

Similar issues

More Go issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.