Skip to content

Zero external issues and zero Discussions: post and pin the who's-using-this thread #126

Description

@shivamlalakiya

What's wrong

Every issue ever filed against this repository is maintainer-authored, and there are zero
Discussions
even though Discussions is enabled.

That is one specific line on the JOSS reviewer checklist:

Collaborative effort: Does the project show evidence of community engagement such as
contributions from multiple developers, issues/discussions from external users, or community
influence on the development described in the paper?

Half of that item is already strong: 17 merged external pull requests from 5 external
contributors. The other half reads as absent. A reviewer sees an issue tracker where every entry
is the maintainer talking to themselves.

There is also no instrument by which a user could signal existence. The library makes no network
calls and has no telemetry, deliberately, and that is worth keeping. So a pinned Discussion is the
only available channel.

Where

File Locate with
the drafted thread body, written and never posted ls scripts/issue-drafts/_DISCUSSION_who_is_using_this.md
the existing generic Discussions link, near the bottom grep -in 'discussion' README.md
the Maturity block the direct link should sit near grep -n -i 'maturity' README.md

What to change

  1. Post the drafted Discussion at scripts/issue-drafts/_DISCUSSION_who_is_using_this.md and
    pin it. Read it first: it was drafted before the paper landed and may want a sentence about
    the JOSS submission.
  2. Link the thread directly from README.md. There is already a generic
    /discussions link, but it sits in the contributing section near the bottom of the file, where
    a prospective user does not reach it. Add a direct link to the pinned thread near the Maturity
    block.
  3. Message the five external contributors (@slegarraga, @shubhrai23, @fuleinist, @BortnikMaxim,
    @AsavariCharati) and ask whether they hit anything worth filing. They touched the docs and the
    test suite; they will have noticed something. One issue from a contributor who is not you costs
    one message and changes the shape of the tracker.
  4. Do not manufacture the signal. Do not file issues from a second account, and do not seed the
    Discussion with fake replies. A reviewer can read timestamps, and the whole point of this
    project's honesty passes is that the record survives inspection.

Tests to add or extend

None. Nothing here touches code.

Done when

# Exits 0 only once at least one Discussion exists.
R=PhilanthroPy-Project/PhilanthroPy
test "$(gh api graphql -f query="{repository(owner:\"${R%%/*}\",name:\"${R##*/}\"){discussions{totalCount}}}" \
  --jq '.data.repository.discussions.totalCount')" -gt 0

# And that the README links the thread itself, not just the generic tab.
grep -qE 'discussions/[0-9]+' README.md

Plus, and this is the part that actually matters and no shell check can assert: at least one issue
or Discussion reply authored by somebody who is not the maintainer.

Partly self-healing, but not in time

JOSS reviewers are instructed to file issues directly against the submitted repository under their
own accounts, so this gap closes during review. It does not help at triage, which is when the
checklist is first read.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationhelp wantedExtra attention is needed

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions