Improving the onboarding process for new contributors

Hi all,

For a long time, I have been inviting people to the OpenRefine GitHub organization on my own initiative: for people who had made a few successful pull requests, people who were involved in some particular coordination capacity or part of some committee for instance.

I have tried to do this quite proactively, because I think it is better not to wait for people to ask for accesses. The idea is to recognize their existing contributions and give them the opportunity to get involved in more tasks around the project. For instance, triaging issues, making changes to GitHub Projects, reviewing pull requests, and so on. This feels especially important to me because GitHub does not offer any mechanism for someone to request access to a project or organization (unlike GitLab), so people need to be really motivated to search for the contact details of the people they identify as maintainers and reach out outside of the platform.

I think this has contributed to growing the team to some extent, but I think there is still a lot of room for improvement. Here are the downsides I see with this approach:

  • It relies on my own initiative. It is quite arbitrary, intransparent and I can be inconsistent in how I give people access to more rights in the project.

  • It is sort of disconnected from the roles set out in our gouvernance document: it does not follow any particular process laid out there.

  • For the person getting invited to the organization, it might be unclear what it really means. What accesses have they been granted? Are they actually invited to use all of them or are there other social norms they should be aware of? What are the expectations? And so on.

  • It has lead us to having a lot of people in the GitHub organization (currently 72 members), most of them not being really active in the project. Should there be some sort of expiration date? Based on which activity criterion? It would feel like a sensible safety measure to me.

  • When someone becomes part of the organization, they are (I think) automatically subscribed to all notifications on all of our repositories. This amounts to aiming a firehose of digital noise at them. They should be told how to unsubscribe from those notifications, but keep the relevant ones, so that they can rely on GitHub notifications to respond when explicitly pinged or in discussions they are participating in.

So, to counter those problems, I would like to:

  • come up with clear criteria about when to invite people to the GitHub organization (and in which "Team"), which should be written down in the gouvernance document. Those criteria should cater for different roles: for developers, designers, bug reporters…
    The way those people interact with the project differs, so the "thresholds" to get an invitation should be adapted accordingly.
  • write a template for a welcome message, which thanks the person for their contributions to date and notifies them about the new accesses they have been given. It should also explain how to configure GitHub notifications and encourage them to publicize their membership
    in the project (so that they appear in the members list on GitHub even to people who are not in the project).
  • Optionally, write some sort of automation which periodically produces a list of newcomers who should be considered for invitation in the project. I think human review cannot be removed there, because the criteria can likely not be checked automatically. Also, sending a message to a GitHub user is not something that can be automated so easily given that email addresses are often hidden and there is no private message functionality. Anyway, I think the message would be more inviting if it is coming from a human rather than a bot. Some exising project member would then be tasked with reviewing that list and sending out the relevant invites.

Beyond GitHub, we could also take the Forum into account, since a lot of work on the project happens here too (user support, design, coordination). One of the benefits I am hoping for is that we end up with a list of project members which is more representative of the actual state of the project. Based on that, it should be easier to introduce more processes in the project leadership, for instance to renew the advisory committee based on some vote, or other things like that.

What do you think of that? What is your own experience of getting active in the project, and how could that have been improved?


Concerning the problem mentioned above of being flooded by GitHub notifications, I have written up a quick guide to help newcomers work around it: Add GitHub configuration instructions by wetneb · Pull Request #238 · OpenRefine/ · GitHub

1 Like

I am aligned with your approach @antonin_d. Better guidelines on contributing are recurring topics from my contributor's interviews. Overall I would like to focus on documenting contributors' pathways and potentially a contributor's handbook explaining how the project function. I think this work will have more impact than the Proposition for the Ambassador Council

The contributor pathway would describe

  • How OpenRefine is organized as a project, including (this is only a rough list in no particular order)
    • Usage of the forum and the GitHub repos,
    • Organization (with Code for Science & Society, current and past funder)
    • Governance and code of conduct
    • The project history
    • The project roadmap
  • How to get started on the different contributor pathways ;
  • The different tasks one can do and how to perform them ;
  • The criteria to progress within the project, getting more permissions and accessing different tasks.

I found the following documentation regarding pathways: