Improving the onboarding process for new contributors

Community Community Feedback
1

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?

3 Likes
2

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/openrefine.org · GitHub

1 Like
3

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:

4

Beyond newcomer induction, it's also worth thinking about offboarding of inactive members, especially if we are proactively giving accesses to people: it's worth revoking them if they are not used.

I am thinking that some sort of threshold (say, 2 years of inactivity in the project) could be a valid way to revoke accesses for people, which could likely be automated (although I haven't looked closely into GitHub's API for that).

5

I think it could be good to actually use the processes written in the gouvernance document, making them actually fit the practices. That would sort of "automate" the integration of people in a sense, by giving people clear pathways.

Here is an example of what it could look like, inspired from other communities I have interacted with. It might look a little "over the top" because it's very formal compared to how we currently operate, but given the right tooling I think it could actually work well. My goals when writing it down were:

  • recognize many forms of contributions to OpenRefine with formal membership of the project
  • have roles with low barriers of entry and low risks to the project
  • make access to roles with more sensitive rights voted on by the community

Teams

The OpenRefine project consists of various teams:

Developers

Rights:

  • triage issues (add/remove tags, close issues)
  • review PRs
  • vote in elections

To become one:

  • get two code pull requests merged in the one of OpenRefine's GitHub repositories

Maintainers

Rights: like developers, but also:

  • merge pull requests
  • publish releases
  • review security vulnerability reports

To become one:

  • become a Developer first
  • then get elected as a Maintainer (see: election process)

Term: two years (re-election possible)

Translators

Rights:

  • vote in elections

To become one:

  • contribute translations to the tool or documentation

Documenters

Rights:

  • vote in elections
  • merge documentation changes on the openrefine.org website

To become one:

  • make at least two documentation contributions on the openrefine.org website

Designers

Rights:

  • vote in elections

To become one:

  • propose a change to OpenRefine which gets implemented

Trainers

Rights:

  • vote in elections

To become one: one of

  • run one training event around OpenRefine
  • publish an openly accessible tutorial about OpenRefine

Code of Conduct committee

Rights:

  • vote in elections
  • respond to Code of Conduct reports
  • be moderator on the forum

To become one:

  • first, be part of any other team
  • then, get elected

Term: three years (re-election possible)

Advisory committee (which we could rename?)

Rights:

  • formally represent the project at Code for Science & Society

To become one:

  • first, be part of any other team
  • then, get elected

Term: three years (re-election possible)

Election process

To run an election:

  • create a thread on the forum (in the Elections category - to be created) listing the person and role applied to
  • eligible voters can vote to Support (+1), Accept (0) or Oppose (-3) the promotion
  • after 14 days, the person is elected if the sum of votes is non-negative
6

I like this role based approach. I should definitely not be a maintainer anymore but instead just developer.

7

For the record, I also started separately a similar document here OpenRefine Playbook Sandbox - Martin Magdinier - Google Docs as part of Requesting Feedback: Documenting OpenRefine Community Handbooks. I think it is time to merge the two conversations.

8

@Martin , is this the place to have larger discussions about the structure of this project?

9

I am trying to keep the conversation on the right thread

I find @abbe98 comment here pertinent:

How do we represent those requests on GitHub? Is it simply creating an issue on OpenRefine's main repository?

I'll be keen to document it in the governance as part of the upcoming round of updates outlined here.

10

I'd open an issue... copy Antonin's ask into it. Then sit back and see the interest on the issue and :+1: (or not) over next 1-4 weeks (holidays) because it doesn't hurt anything at all.

1 Like
11

Issues don't feel completely fitting to me, as we don't really use them for project management tasks so far, so it feels a bit weird to me to mix bug and improvements requests with that. Issues like the one to announce the barcamp feel a bit of an ad-hoc hack. I don't have strong resistance, it would work for sure, but I think there is also value in bringing those discussions to the forum, where developers have more occasions to meet users, trainers and other members of the community, which feels like a useful thing.

To make it visible on GitHub, we could also consider using pull requests instead. I've been experimenting with this model on Codeberg, by having a list of members in the repository (with the intention that it could then be used for some automation, like detecting membership expiry automatically and opening the corresponding PRs automatically, or something like that.)

12

I like the PR approach a lot.

13

PRs would pollute the git history and it might be confusing given that it has its own rule-set for approval(I don't have very strong opinion).

If I needed more or less rights for myself or someone else today I would create an issue.

On a related note. I actually think it makes sense to bring more (Github) project management to Github as the users affected by it are there. For example something like the Github label rework should definitely have been on Github given the impact it had on developers.