How to connect GitHub, decide what shows publicly, ask for the help youactually need, and hand a project on when it is time.

There is a particular kind of WordPress project that never gets found.

It works. It has users. It solves a real problem. But it is not on
wp.org, or it is on wp.org and the listing says nothing about the fact
that one person has been carrying it alone for three years and would
quite like some company. There is no shelf for it. GitHub has it, but
GitHub has forty million other things too, and nobody browses GitHub
looking for a WordPress plugin that needs a documentation writer.

The Repos directory is that shelf.

This guide covers all of it: connecting your GitHub account, what gets
pulled in and when, what shows publicly and what stays private, how to
say what your project needs, how offers of help work, how contributions
get credited, and how to hand a project to a new maintainer without
anything falling on the floor.

It is long because the feature is deep. Use the contents to skip.

Contents

1. What this directory is, and what it is not
2. Connecting your GitHub account
3. What happens after you connect
4. What shows publicly, and what does not
5. The My Repositories dashboard
6. Saying what your project needs
7. When someone offers to help
8. Setting your own help preferences
9. Verifying a project
10. Contributions and credit
11. Handing a project on
12. Health, staleness, and the quiet nudge
13. Browsing the directory
14. Questions I keep getting asked

1. What this directory is, and what it is not

It is not a mirror of your GitHub account.

I want to be blunt about that early, because it shapes every other
decision in the feature. When I first sketched this, the obvious version
was: connect GitHub, list everything public, done. Instant directory,
thousands of entries on day one.

I did the arithmetic on real data before building it. Across the accounts
connected to WPFolks there were 4,812 public repositories. Of those,
2,325 were forks. Nearly half. The rest was the usual mix any working
developer accumulates: dotfiles, a portfolio site, tutorial follow-alongs,
three abandoned experiments, and somewhere in there the two or three
things they actually maintain.

A directory that listed all of it would have been 48 percent forks and
would have buried the genuine projects under everything else. Worse, it
would have listed work nobody offered. Public on GitHub means “you may
read this.” It does not mean “please send me adoption applications.”

So the directory works on consent, not classification. Things appear
because someone chose to put them there, or because they were already
linked to a listing on WPFolks. Nothing appears because an algorithm
decided your repo looked WordPress-shaped.

That is the whole design. Everything below follows from it.

2. Connecting your GitHub account

Head to Settings → GitHub, at wpfolks.org/settings/?tab=github.

There are two ways to link GitHub, and they are not equivalent. This trips
people up, so it is worth being precise.

Option A: Authorise with GitHub (recommended)

Click the connect button and you will be sent to GitHub to authorise
WPFolks, then dropped back on the same settings tab with a confirmation.

Authorising stores an access token against your account. That token is
what makes the following possible:

• Higher rate limits. Unauthenticated requests to GitHub are capped at
  60 an hour for the whole site. Authenticated requests get 5,000. If you
  have ever wondered why a sync seemed to stall, this is usually why.
• Ownership detection. GitHub only returns the permissions object on
  an authenticated request. Without a token I cannot tell whether you can
  push to a repository, which means I cannot verify it as yours.
• Verification. Same reason. See section 9.
• Contribution credit. Merged pull requests you author on listed
  projects only get counted when the scan can authenticate as you.

Authorising does not expose anything private. The sync skips private
repositories entirely, whether you have a token or not.

Option B: Just type your username

There is also a plain username field. Filling it in is enough for the
sync to find your public repositories and pull them in.

What it will not do is verify anything. You will see your projects, you
can publish them, but the verified marker will not appear and control
checks will fail.

If two people are working together on a project, both should authorise
properly. A maintainer with a username but no token cannot be verified
as the maintainer, and a contributor with a username but no token will not
have their merged pull requests counted. This came up in testing more than
once and the symptom is always the same: everything looks fine, and then
one specific thing silently does not work.

3. What happens after you connect

Connecting fires a sync immediately. After that it runs on a schedule.

The rolling sync deliberately works through folks in slices rather than
hammering GitHub with everyone at once. If you have just connected and
your projects have not all appeared, give it an hour, or use the manual
refresh on an individual project (see section 5).

What gets pulled in

For each public repository: name, description, primary language, topics,
stars, forks, open issues, open pull requests, last push date, and whether
it is a fork or archived.

Two details worth knowing, because they affect numbers you will see:

Open issues excludes pull requests. GitHub’s own open_issues_count
counts issues and pull requests together, which means a repository with
twelve open PRs and no issues reports twelve open issues. I fetch the pull
request count separately and subtract it, so the number shown is what you
actually mean by open issues.

Forks are recorded but never listed. They are pulled in so you can see
them on your own dashboard, and so the aggregate counts are honest. They
never appear in the public directory. More on that next.

4. What shows publicly, and what does not

Three rules, in order of precedence.

Rule 1: Forks are never listed. No exceptions.

Not if a listing points at one. Not if you toggle it by hand. The
directory promises original projects looking for contributors, and a fork
sending people to somebody else’s work is not that.

This is enforced in four separate places (the public query, the
auto-publish gate, the manual save handler, and the reconcile command)
specifically so that no single missed path can leak one back in.

If you are maintaining a hard fork of an abandoned plugin as a genuinely
separate project, the right move is to detach it on GitHub so it is no
longer marked as a fork. Then it is a project in its own right and it
behaves like one here.

Rule 2: Repos linked to a live listing publish automatically

If you have a plugin or theme listing on WPFolks and that listing has a
GitHub URL on it, the matching repository is published automatically.

The reasoning: you submitted that listing, and you put the repository URL
on it yourself. That is an affirmative act on WPFolks, not a guess about
your intentions. Surfacing it is honouring a decision you already made.

The listing has to be live, not merely submitted. Submissions sit in
pending until approved, and trusting the link alone would push unapproved
plugins into the public directory through the back door.

Rule 3: Everything else is opt-in

Every other repository sits on your dashboard, visible only to you, until
you choose to publish it.

This is where most genuinely interesting projects live: premium plugins
with no wp.org listing, agency tools, block libraries, CLI utilities, the
internal thing you built that turned out to be useful to other people.
None of them have a listing to link against, so none of them auto-publish.
They need one click from you.

And you can always say no

Hiding a project by hand is recorded as a deliberate choice, not just an
absence. A later sync will not quietly re-publish it because a listing
link appeared in the meantime. If you hid it, it stays hidden until you
say otherwise.

5. The My Repositories dashboard

Everything you control lives at wpfolks.org/dashboard/repositories/,
also reachable from the dashboard sidebar.

Finding the project you want

The list shows up to 100 projects at a time, and it is ordered
deliberately:

1. Published projects first
2. Then originals before forks
3. Then archived last
4. Then by most recent push, then by stars

Forks are hidden by default, since they cannot be published anyway. Tick
Show forks if you want to see them.

There is also a search box. If you have a lot of repositories, search is
the fastest way to reach the one you want. Filters are held in the URL, so
a filtered view is linkable and survives saving.

What you can set per project

Each row carries a small form:

• Status. What state the project is in. See below.
• What it needs. The help tags. See section 6.
• A note. Free text, shown on the project page. This is where you say
  the thing the tags cannot, like “the test suite is the part I would most
  like a hand with” or “happy to pair with someone on their first PR.”
• Show in the public repos directory. The publish toggle. Absent on
  forks, replaced by a line explaining why.
• Refresh from GitHub. Pulls fresh data for that one project, without
  waiting for the hourly sync. Rate limited, so if you press it twice in
  a row the second press will tell you to wait a few minutes.

The four statuses

Be honest with these. The whole value of the directory is that its
signals mean something, and “actively maintained” on a project last
touched in 2023 costs everyone.

6. Saying what your project needs

This is the bit that makes the directory more useful than a list of
repositories, and it is the bit most people skip. Do not skip it.

There are eight help tags:

Two things happen when you set these.

Your project appears in the Help wanted view. That is a filtered slice
of the directory at /repos/help-wanted/, for folks specifically looking
for something to work on.

Folks who match get told. Anyone who has set matching help preferences
gets a notification that a project just asked for the thing they said they
were up for. This is the single highest-value action you can take on this
screen, and it takes about ten seconds.

A tag is a request, not a commitment. Nobody is owed anything because you
ticked Documentation. It just means the ask is visible.

7. When someone offers to help

On any published project page there is an I can help control. A folk
picks the kind of help they are offering, from the same eight categories,
and sends it.

Here is the full path:

1. They offer. One offer per person per help type, so nobody can spam
   the same maintainer six times for the same thing.
2. You get an email and a notification. The email tells you who, on
   what project, offering what.
3. You accept or decline. Both from the project page. Declining is a
   normal outcome and not a rudeness. A maintainer who cannot take on
   supervising a new contributor this month is allowed to say so.
4. They get told either way. No silent rejections. The one thing worse
   than a no is nothing at all.
5. If you accept, they appear as an accepted contributor on the
   project page, and they earn the Project Helper badge.

Accepted contributors being visible on the page matters more than it
sounds. It is the difference between a project that looks like one
person’s burden and one that looks like something a few people are
building. That perception is most of what decides whether a sixth person
gets involved.

8. Setting your own help preferences

The contributor side of the same coin. On the My Repositories screen there
is a panel for what you are up for, using the same eight categories.

Setting them does two things:

• The “Matched to you” view works. In the directory you can filter to
  only projects asking for the kinds of help you offer. Without
  preferences set, this view tells you to set them first, because an
  unfiltered “matched” list would be a lie.
• You get notified when a match appears. When a maintainer adds a tag
  you have said yes to, or opens a project for adoption in your area, you
  hear about it.

You do not need to own a single project to do this. If you have never
shipped a plugin and want to write documentation for someone who has, this
is the whole feature for you.

9. Verifying a project

A verified project carries a marker saying WPFolks confirmed the person
listing it can actually push to it.

The check is simple and it is not self-reported. With your GitHub token,
I ask GitHub for your permissions on that repository and look for admin
or push access. If GitHub says you have it, the project is verified. If
GitHub says you do not, it is not, and no amount of insisting changes
that.

This is why authorising properly matters rather than just typing a
username. Without a token there is no permissions object, so the check
cannot run at all.

Verification also governs claiming. A repository that came in through a
plugin listing but was not matched to a folk can be claimed by whoever can
prove they can push to it.

10. Contributions and credit

Once a day, WPFolks scans for merged pull requests you have authored on
projects listed here, and credits them to you.

Merged, specifically. Not opened. A PR that is still in review is work in
progress; a merged PR is work that landed and that a maintainer chose to
accept. Only the second one is a contribution.

Two badges come from this:

Both count toward your profile and appear alongside your wp.org badges.
The gap between one and ten is deliberate: the first badge is for showing
up, the second is for keeping it up, and there is nothing in between
because a badge for your fourth PR would be noise.

There are three more badges on the maintainer side:

Contribution scanning needs your GitHub authorisation, for the same rate
limit reasons as everything else.

11. Handing a project on

This is the feature the rest of the trust layer exists to protect, and the
one I care most about getting right.

Every WordPress developer has watched a useful plugin die quietly. Not
dramatically. The maintainer’s job changed, or their kid was born, or they
simply got tired, and there was no obvious way to hand it to any of the
people who would gladly have taken it. So it sat there getting slowly
more broken until the day it stopped working entirely.

The handover flow exists to make that unnecessary.

Opening a project for adoption

Set the status to Seeking a maintainer and mark it open for adoption.
It then appears in the directory’s Needs a maintainer filter, and folks
with matching preferences are notified.

You can also write an adoption brief: what the project is, what state it
is in, what a new maintainer would be taking on. Be honest here too. The
handover that works is the one where the incoming maintainer knew what
they were getting.

Applications

Interested folks apply. You see the applications on the project page and
choose. One pending application per person, so nobody can pile on.

You are under no obligation to accept anyone. “Nobody suitable applied” is
a legitimate outcome, and better than handing a project with real users to
somebody you are not confident about.

The handover checklist

Once you accept someone, the state moves to Handover in progress and a
seven-item checklist appears:

1. GitHub repository transferred or admin access granted
2. WordPress.org SVN commit access updated
3. WordPress.org plugin or theme owner changed
4. Deploy keys, tokens, and CI secrets rotated
5. Any project domain, docs site, or demo handed over
6. Support inboxes and forum moderation handed over
7. Users told about the new maintainer

This is a checklist and not automation, on purpose. Every item is
something only the two humans involved can actually do, and half of them
happen on systems WPFolks has no access to. A progress bar that claimed
to have rotated your CI secrets would be a lie with security
consequences. What the checklist does is make sure nobody forgets item 4
at two in the morning.

Item 7 is the one people skip and the one that matters most to users. If
you have a plugin with ten thousand installs, those ten thousand sites are
about to start receiving updates from a different person. Tell them.

When everything is ticked, the state moves to Transferred, and the new
maintainer earns the Project Rescuer badge.

12. Health, staleness, and the quiet nudge

Every listed project carries an activity state, worked out from its last
push date and its archived flag:

There is also a freshness score, from 0 to 5, driving the small activity
meter on project cards.

This is computed rather than declared, so it cannot drift out of sync with
reality. A project cannot claim to be actively maintained while its last
commit was in 2023, because the state comes from the commit date, not from
the dropdown.

If one of your projects goes quiet past the stale threshold, you get a
nudge. It is not a telling-off. It is a prompt to do one of three things,
all of which are fine:

• Push something, if you were meaning to anyway
• Change the status to Maintenance mode, which is an honest description
  of most mature software
• Open it for adoption

A stale project with an accurate status is genuinely useful information.
A stale project claiming to be actively maintained wastes the time of
everyone who relies on it.

13. Browsing the directory

The directory lives at wpfolks.org/repos/.

Three views along the top:

• All projects. Everything published.
• Help wanted. Only projects that have asked for something.
• Matched to you. Only projects asking for the kinds of help you said
  you were up for. Needs your preferences set first.

And filters down the side:

• Search by name or description
• Status, the four states above
• Help needed, the eight tags
• Language, drawn from the languages actually present in the directory
  rather than a fixed list
• Open for adoption, on its own

Sort by most recently active, most stars, or newest.

Each project has its own page at /repos/{owner}/{name}/, with the
README rendered, health signals, open issues and pull requests, accepted
contributors, sibling projects from the same maintainer, and the “I can
help” panel.

14. Questions I keep getting asked

Do I have to publish anything to use this?
No. Connect GitHub and publish nothing, and you still get contribution
credit for merged PRs on other people’s listed projects, plus the ability
to offer help and to set your preferences.

Will my private repositories show up?
No, and more than that: they are never fetched. The sync skips anything
marked private before it stores a single field, so private repositories do
not exist in the WPFolks database at all. They are not listed, not counted,
and not visible on your own dashboard either.

Why is my fork not showing up?
Forks are never listed. See section 4. If it is genuinely
a separate project now, detach it on GitHub and it will behave like one.

I connected but nothing appeared.
The rolling sync is hourly and works in slices. Give it an hour, or hit
refresh on an individual project. If your projects still are not there
after that, check that the GitHub tab shows as connected rather than just
having a username filled in.

Why does my project say 0 open issues when GitHub says 5?
Because GitHub counts pull requests as issues. If you have five open PRs
and no issues, GitHub reports five open issues. I subtract the PR count so
the number means what you expect. The pull request count is shown
separately.

Can I list a project I do not own?
You can list one you can push to, which is verifiable. You cannot list
somebody else’s project on their behalf.

What happens to my project if I delete my WPFolks account?
It comes out of the directory. The repository is yours and lives on
GitHub; nothing here has any claim on it.

I published something by accident.
Untick the publish toggle. It is recorded as a deliberate hide, so a later
sync will not put it back.

One more thing

The reason this directory only has a few dozen projects in it, when the
underlying data has thousands of repositories, is that every single entry
is there because a person decided it should be.

That ratio is not a problem I am trying to fix. It is the product.

If you maintain something in the WordPress space, take the ten seconds to
set your help tags. The worst case is nothing happens. The best case is
that the documentation writer, or the translator, or the co-maintainer you
have been quietly wishing for turns out to have been one filter away the
whole time.

Connect your GitHub account
or browse the directory.

Questions, or something in here that does not match what you are seeing?
Reply to this post or email me at hello@wpfolks.org. I read everything.