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

Open
  • Is something wrong?
#126 2 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
3/5
Estimated time
1-2 days
Newbie friendliness
25/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Quiet
Tech stack
github, python
Domain
documentation

Research direction

Read scripts/issue-drafts/_DISCUSSION_who_is_using_this.md and locate the Maturity block and existing Discussions link in README.md. Post and pin the drafted thread, add a direct link near the Maturity block, and contact the named external contributors. Done means the README links the thread and at least one non-maintainer has posted an issue or Discussion reply; this depends on external participation.

Written by the indexing model from the issue text.

Description

documentation help wanted
Status (2026-11-04)

The title and "What's wrong" below describe 2026-08-20 and are partly out of date:

  • Steps 1 and 2 are mostly done: Discussion #158 ("Are you using PhilanthroPy?") is posted and README.md links it directly, but it is not pinned (the repository has no pinned Discussions as of 2026-11-04). Pinning it is the one mechanical step left. #188 ("What tripped you up?") was added on 2026-09-06. Both shell checks under "Done when" now pass. The draft file the table points at, scripts/issue-drafts/_DISCUSSION_who_is_using_this.md, no longer exists because it was posted.
  • Step 3 is done (outreach on 2026-09-06, logged on #127).
  • What is left is the part no shell check can assert. External issues: 2 (#129 by slegarraga, #357 by Jahnavi-HJ), target 3. External Discussion replies: 1 (#188), target 2. #158 has 0 replies.

This issue closes when both targets are met by people other than the maintainer. Step 4 still applies: nothing seeded.

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.

Dominant language
Python
Stars
11
Forks
23
Avg merge
15h 13m
Merged PRs (30d)
30

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 PhilanthroPy-Project/PhilanthroPy

All issues in PhilanthroPy-Project/PhilanthroPy

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.