Skip to content

docs: restock the good-first-issue starter board with concrete open issues - #339

Open
maxime2476 wants to merge 1 commit into
ColumbusLabs:mainfrom
maxime2476:docs/restock-starter-queues
Open

docs: restock the good-first-issue starter board with concrete open issues#339
maxime2476 wants to merge 1 commit into
ColumbusLabs:mainfrom
maxime2476:docs/restock-starter-queues

Conversation

@maxime2476

Copy link
Copy Markdown

Closes #278 for the documentation half. The labeling half needs triage rights, so it is
written up below as a ready-to-apply batch rather than applied here.

What changed

docs/good-first-issues.md previously sent newcomers to two label search URLs and nothing
else. If those searches came back thin, the reader had no way to tell whether the project
had no starter work or whether they had searched wrong.

The board now lists the open issues directly:

  • Two tables covering the 18 open starter issues, split into good first issue (8 rows)
    and good-first-rule (10 rows), each with area and difficulty so a reader can filter by
    eye instead of by query string.
  • A dated snapshot line (2026-07-28) that names the GitHub queues as the source of truth,
    so a table that drifts is visibly stale rather than quietly wrong.
  • The evidence guidance table kept, moved under "What a good starter PR looks like".
  • The historical v0.3 tables kept verbatim, with a note marking them as history and
    pointing back to the active board.

Every one of the 18 linked issues was checked as open with a matching title before the
table was written.

On the issue premise

#278 says open GFI volume is "low/empty". That is not quite what the queue looks like now:
9 good first issue and 10 good-first-rule issues are open. The real gap is narrower and
matches the acceptance criteria closely. Only 5 open issues carry difficulty: small, and
all 5 are area: docs. There is no small-sized work at all in reporters, fixtures, or
detectors, which are exactly the tracks the board tells newcomers to look at.

So the batch below is built to fill that specific hole rather than to raise the raw count.

Proposed batch for AC 1

Twelve starter issues, all difficulty: small, spanning the four tracks named in #278.
Each one was checked against the tree at 2d577cf, and the observation that motivates it is
listed so a maintainer can confirm before filing.

Docs

docs/rules.md has 39 dedicated rule sections, but 23 shipped rule ids have none. Splitting
by pack keeps each issue small.

  1. Document the five Python pack rules missing from docs/rules.md
    documentation, good first issue, difficulty: small, area: docs
    python-complex-control-flow, python-dead-abstraction, python-duplicate-logic,
    python-large-function, and python-todo-comment do not appear anywhere in the file.
    The other two Python rules do have sections (python-route-sprawl, python-error-handling),
    which makes the gap look like an oversight rather than a decision.

  2. Add docs/rules.md sections for the Ruby and Rails pack rules
    documentation, good first issue, difficulty: small, area: docs
    Six ids ship without a section: ruby-dead-abstraction, ruby-duplicate-logic,
    ruby-large-function, ruby-todo-comment, rails-controller-sprawl, rails-route-sprawl.

  3. Add docs/rules.md sections for the Kotlin and Compose pack rules
    documentation, good first issue, difficulty: small, area: docs
    Six ids ship without a section: kotlin-dead-abstraction, kotlin-duplicate-logic,
    kotlin-large-function, kotlin-todo-comment, compose-large-composable,
    compose-state-hoisting.

  4. Add docs/rules.md sections for the Swift and SwiftUI pack rules
    documentation, good first issue, difficulty: small, area: docs
    Six ids ship without a section: swift-dead-abstraction, swift-duplicate-logic,
    swift-large-function, swift-todo-comment, swiftui-large-view, swiftui-state-sprawl.

Reporters

Thirteen of the modules in src/reporters/ have a matching file in tests/reporters/.
These three do not, and no other test references them either.

  1. Add a unit test for src/reporters/payoffSection.ts
    good first issue, difficulty: small, area: reporter
    No file under tests/ references payoffSection.

  2. Add a unit test for src/reporters/suppressionAudit.ts
    good first issue, difficulty: small, area: reporter
    No file under tests/ references suppressionAudit, though --audit-suppressions runs
    in the scan:self script.

  3. Add escaping tests for htmlEscape.ts and markdownEscape.ts
    good first issue, difficulty: small, area: reporter
    Neither helper is referenced from tests/. Both sit on the path where scanned source
    text reaches rendered output, so a regression here shows up as broken or unsafe report
    markup.

Fixtures

  1. Grow examples/node-api past a single file
    good first issue, difficulty: small, area: detector
    The example is one file, src/server.ts, which limits what the node pack can be
    demonstrated or smoke-scanned against.

  2. Grow examples/react-native past a single file
    good first issue, difficulty: small, area: detector
    Same shape: one file, src/ReleaseScreen.tsx, for a pack with rules such as
    rn-host-forwarding.

  3. Add false-positive fixtures for the Ruby, Rails, and Python packs
    good first issue, difficulty: small, area: detector, type: false-positive
    examples/false-positives/ covers ten rule areas and includes compose/ and swiftui/,
    but has no directory for Ruby, Rails, Python, Vue, or Svelte. Ruby, Rails, and Python
    are the tightest scope for one PR.

Conservative detector tweaks

Both of these follow a pattern the project already uses, where a hardcoded exclusion list
becomes configurable without changing default behavior.

  1. Make the duplicated-literal number ignore list configurable
    good-first-rule, difficulty: small, area: detector, type: false-positive
    COMMON_NUMBER_LITERALS is fixed at ["0", "1", "2", "-1"] in
    src/detectors/duplicatedLiteral.ts:40. String literals already extend through
    duplicatedLiteralIgnoreStrings, so the numeric side is the asymmetry. Adding
    duplicatedLiteralIgnoreNumbers touches the same files the string option already
    touches: src/core/types.ts, src/config/mergeConfig.ts, and the detector.

  2. Make the license and copyright exclusion in commented-out-code configurable
    good-first-rule, difficulty: small, area: detector, type: false-positive
    isLicenseOrCopyrightLine in src/detectors/commentedOutCode.ts hardcodes four
    patterns: SPDX-License-Identifier, Copyright, Licensed under, and
    All rights reserved. Repos with a house header outside that set get the banner
    flagged as commented-out code. This mirrors the configurable-markers work already done
    for todo-comment in Add configurable markers for todo-comment #4.

Follow-up once the batch exists

The board tables in this PR are built only from issues that are open today, so nothing here
links to an issue that does not exist. After the batch is filed and labeled, the two tables
want one more pass to add the new rows and refresh the snapshot date.

Testing

npx tsx --test tests/docs/*.test.ts reports 9 passing and 2 failing. Both failures are in
ciProviderDocs.test.ts against docs/ci-bitbucket.md, a file this PR does not touch, and
they reproduce identically on a clean checkout of 2d577cf. They come from CRLF line endings
on a Windows checkout meeting regexes that expect \n.

The starter board pointed at label search URLs only, so a newcomer had to run
the search themselves to find out whether anything was open. Replace that with
concrete tables of the 18 currently open `good first issue` and `good-first-rule`
issues, split by general work and rule work, with area and difficulty per row.

Mark the live GitHub queues as the source of truth and date the snapshot so a
stale table is obvious. Keep the historical v0.3 Done tables intact and label
them as history rather than the current queue.

Refs ColumbusLabs#278
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Restock good-first-issue and good-first-rule queues

1 participant