Role transitions to match new governance guidelines

[waldyrious]

Now that the project finally has explicit criteria for role transitions (updated link after #1897), the first thing we need to do is update the current contributors' roles to match them.

Here are the changes that should be done, according to the document:

• a) Contributors to be added as collaborators in this repo: actually, I'd rather not collate this particular list myself, since that would entail opening PRs which are still on my unread notifications list, and would therefore disappear from it without the review I'd wish to give them. So I'll just describe the process and ask for someone else to step in. What I did was go to https://github.com/tldr-pages/tldr/graphs/contributors and click on the "x commits" links where x >= 5, starting at the bottom. Then I checked whether the commits actually corresponded to 5 or more distinct, non-trivial PRs, or whether some of them were multiple commits from the same PR. One example of the latter is (at the time of writing) @Larry850806. See also @chuanconggao as an example of someone with 5 merged PRs but one of them being a trivial one (python: fix typo #642). The first user who matches the criteria (again, counting from the bottom) is @zdroid (PRs Fix build-index.js coding style #1101, Drop bugs URL from package.json #1110, Add apt-get autoremove #1011, Simplify package.json #1090, Fix the indentation in PDF conversion files #1091), so he'd be one of those to be added as a collaborator. I'd appreciate if someone else could repeat this process for the other contributors and complete this list; otherwise, that's going to have to wait until I'm done clearing my notification backlog.

• b) Collaborators to be added as members of the organization: Nothing to do here, unless I'm missing something. @jeeftor (added after the exchanges here and here) is the only collaborator in the repo who's not a member of the org, and I believe he hasn't showed interest in performing maintenance tasks. Please correct me if I'm wrong.

• c) Organization members to be converted to owners: This one is pretty easy. The current members that aren't owners (a distinction which unfortunately isn't publicly viewable) are @danzimm, @edgurgel, @Leandros and @sbrl. Among those, only @sbrl has been active in the project for the past 6 months, and thus is eligible for transitioning to an organization owner. To be exact, he was added to the organization on 2017-08-10, and 6 months from then would be 2018-02-10, but at that time he had already made plenty of contributions to the project (31 commits to be precise), so his addition was already late by our criteria.

• d) Organization members to be converted to collaborators: between July 9 2017 and today, this is the commit count of the current org members, in alphabetical order: agnivade: 66 | danzimm: 0 | edgurgel: 0 | felixonmars: 1 | igorshubovych: 0 | Leandros: 0 | ostera: 0 | rprieto: 0 | rubenvereecken: 0 | sbrl: 35 | waldyrious: 51.
  Of course, project activity is not measured exclusively in commits, and this is especially true for maintenance work, but it's the only thing what we can easily measure, and is correlated with merged PRs, so it can work as a rough estimate.
  Based on this, applying the new guidelines would result most of the current members transitioned to former maintainers, except @agnivade, @sbrl and myself (and @rprieto, which should IMO remain a perennial owner of the organization, as the creator of the project). At a glance, this feels like an accurate representation of the current maintenance team, but feel free to correct me if I missed any details.

• e) Organization members that need to make their membership public: ignoring those who are to be removed, as mentioned above, only @sbrl remains to make his membership public.

Once these steps are completed, the MAINTAINERS.md file should be updated in accordance.

---

In addition to reactions to the items above, I'd appreciate your comments to the following questions which I faced by writing this:

1. The PRs eligible for checking whether to add a contributor as a repo collaborator should be non-trivial (an example is provided above). I've submitted GOVERNANCE: non-trivial PRs as criterion #1876 proposing this amendment to the governance guidelines.
2. Should maintainers be responsible for regularly checking who has surpassed the threshold to be added as a collaborator? I am inclined to say yes, because it's in the interest of the maintenance team to make sure new hands are joining the project, even though at this first stage it will take a bit more work to go through the backlog of past contributors to match the guidelines just approved. We could always decide to apply the guidelines from now on, rather than retroactively, but again, it's in our interest to add more people to the repo. (Of course, others are very welcome to assist in this process, including by pointing out their own fulfillment of the criteria.)
3. We really need to keep records of when people are added to the organization, since GitHub doesn't seem to expose this information in the repository settings. Fortunately @sbrl's addition was discussed on Gitter (Add @sbrl to MAINTAINERS #1586 would also have helped if it had been made on time), but ideally issues should be opened to track such transitions.
4. Is anyone aware of advanced GitHub search queries we could use for measuring non-commit maintenance work, like issue comments, PR reviews, etc.?
5. I think @igorshubovych might need to remain a member of the org becuse the automated commits to update the index file are attached to his account (at least that's what the repo's RSS feed tells me). Is there anyone familiar with this kind of Travis setup who can confirm whether his removal from the org could mess up that system? Client authors would stand the most to suffer from such a disruption, I reckon.

[agnivade]

Contributors to be added as collaborators in this repo:

I want to start this as an organic process, going top to bottom, inviting the more active members first, and then slowly working my way down. To that effect, I want to start with @jsonbruce and @pxgamer who have been contributing actively at this moment.

Collaborators to be added as members of the organization:

Yep, @jeeftor can be removed. I had pinged him myself on gitter and did not get any response.

Pts c), d) and e) are also correct. I confirm that those transitions need to be made.

---

Responding to your additional questions

1. Agree.
2. Yes, I think it will naturally occur to you (atleast it happens to me) that someone is showing interest. And it doesn't hurt to check every now and then. We don't need to be super religious and check every single day. Nobody is getting paid after all 😆
3. Great.
4. No idea. 😕
5. There is a github token in the .travis.yml file. Removing Igor will affect that. I can update it to my token though.

---

To conclude, @waldyrious , why don't you start with pts 2,3,4. I will start with 1.

[waldyrious]

Great, thanks for the detailed response :) A few notes (numbering unrelated to the above; just adding for cross-reference):

1. I agree it makes sense to start from the top, and you're right that gut feeling is probably the most likely trigger for the verification, and indeed preferable to a completely mechanical process. (It is also how the current members have been added, of course, so I fully get that POV). That said, I'll look into fully processing the list when I get the time, if only for completeness' sake.
2. Regarding @jeeftor, I should point out that we didn't define a process or criteria for removing repo collaborators; he certainly fits the criteria for being added as a collaborator, just not as a maintainer. So the action to take here is... well, no action at all; he simply doesn't transition from collaborator to maintainer. That does raise an interesting question, though: should we include a process to streamline the list of collaborators, just like we have for the list of maintainers (org members)? I don't think it's that problematic to keep them, since it's not reflected externally (in the MAINTAINERS.md file or the public listing of org owners).
3. Thanks for confirmation about the github token. Let's document the new token by adding a comment in the .travis.yml file noting who it belongs to. I wonder if it could somehow be associated with the tldr-bot account? That would be perfect :)
4. Last but not least: adding and removing people should be accompanied by a standard, agreed-upon message, so that we make sure we're not giving out the wrong signals. I think Homebrew has a nice template we could use for inspiration. We'd want something much shorter, but in the same spirit. What do you think?

[agnivade]

1. Sure.
2. Hmm, in that case, I fear that we might have a list of stale collaborators since we never remove them from there. I thought of it like you move from collaborator, to member to owner. And similarly, you get demoted from owner, to member to collaborator and then get removed from collaborator too.
3. We had some issues with using the bot token. I will see if I can transfer it to my account.
4. Great. 👍

[sbrl]

Re making my membership public: I didn't realise I hadn't done yet - I've done that now :P

1. I've approved and merged GOVERNANCE: non-trivial PRs as criterion #1876.
2. Yep - sounds like a good idea to me - especially people pointing out their own fulfillment of our guidelines.
3. Indeed. Perhaps we could add it to the maintainers list? Though I do like the creating an issue about it better.
4. A user's page tells you not only how many commits they've made in a repository, but also the number of PRs they've reviewed on a month-by-month basis. I think this i driven by the events API
5. Hrm yeah - I've noticed those on my dashboard. It looks like there's some access token or other added to travis (this is where it does the automated commits I think...?)

I want to start this as an organic process, going top to bottom, inviting the more active members first, and then slowly working my way down. To that effect, I want to start with @jsonbruce and @pxgamer who have been contributing actively at this moment.

Sounds like a good place to start to me!

[waldyrious]

Hmm, in that case, I fear that we might have a list of stale collaborators since we never remove them from there. I thought of it like you move from collaborator, to member to owner. And similarly, you get demoted from owner, to member to collaborator and then get removed from collaborator too.

That's possible, but we'd need to define that last step explicitly first, to be consistent. However, let me first tell you why I think that's not necessary.

My view is that it's ok for that to be a permanent status. Unlike the role of maintainer, which implies being active helping out with the repo, the collaborator status is more of a "marker" to indicate that someone has reached a given threshold -- in this case, the baseline metrics we defined as a signal that they understand what the project is about an are able to contribute productively to it. That's to say, there's no way to "unmeet" those requirements. So unless they actively break the trust that the status represents (say, by making commits that go against the goals or guidelines of the project), there's nothing that the project stands to gain by removing them. Especially since they're not listed anywhere public, so people won't be mistaken to expect them to be active maintainers.

That said, if you disagree, I'd suggest first opening an issue (or PR) for the addition of this clause to the governance document. I wouldn't want to act outside of the boundaries specified there.

Perhaps we could add it to the maintainers list? Though I do like the creating an issue about it better.

No reason not to do both :)

A user's page tells you not only how many commits they've made in a repository, but also the number of PRs they've reviewed on a month-by-month basis. I think this i driven by the events API

Oh, interesting. I wonder if there's a way we could get the data in a structured manner, say via API calls via URLs that can be checked directly in the browser. Do you think that's possible?

(this is where it does the automated commits I think...?)

Yeah, we definitely should add a comment to that file noting the token on .travis.yml, and the comment on .travis.yml should mention the upload_assets() function on this file.

[agnivade]

Ok, fair enough.

[sbrl]

Oh, interesting. I wonder if there's a way we could get the data in a structured manner, say via API calls via URLs that can be checked directly in the browser. Do you think that's possible?

Absolutely. Though to see anything more than JSON (which firefox does an exemplary job of presenting nicely, btw), we'd (probably) need to write a server-side application - unless of course the GitHub API supports CORS - then we could host something with GH Pages.

[waldyrious]

Though to see anything more than JSON

That's more than enough! We might want a polished interface later on, but the most important part is to get the actual data. Please share if you can come up with useful queries we can test-drive and hopefully integrate into the process.

[waldyrious]

Ok, so for 2 there's nothing to be done, and I just did 3 (made @sbrl into an owner). I'll work on a template message to send the ones about to be removed from the org (step 4), as well as one for those about to be added as collaborators (step 1), and will post them below for feedback.

[waldyrious]

So here's what I'd propose the process to be like. For changing one or more contributor's roles, we'd open an issue (similar to this one) with a message like this:

For adding new collaborators:

Hi, @username(s)! You seem to be enjoying contributing to the tldr-pages project. You now have had five distinct pull requests merged, which qualifies you to become a collaborator in this repository, as explained in our governance guidelines.

As a collaborator, you will have commit access and can therefore merge pull requests from others, label and close issues, and perform various other maintenance tasks that are needed here and there. Of course, all of this is voluntary — you're welcome to contribute to the project in whatever ways suit your liking.

If you do decide to start performing maintenance tasks, though, we only ask you to get familiar with the maintainer's guide.

Thanks for all your work so far!

For adding new org members:

Hi, @username(s)! Since you've been added as a collaborator in the repository, you have showed interest in performing maintenance tasks. In fact, by the metrics defined in the governance guidelines, you've now met the thresholds to be effectively considered an active maintainer of the project. So, to publicly acknowledge that fact, we'll add you to the tldr-pages organization.

If you accept the invitation, we ask you to make your membership public, and (in case you don't already) start hanging out in the project's Gitter chat room. You'll now be one of the public faces of the tldr-pages project. Welcome aboard!

For removing inactive org members:

Hi, @username(s)! As you know, our governance guidelines define processes for keeping the list of organization members in sync with the actual maintenance team. Since you haven't been active in the project for a while now, we'll be moving you to the status of former maintainer.

In practice, not much will change on your side, since you'll remain a collaborator in the repos you have been active in, and will therefore retain the ability to commit, merge PRs, label and close issues, etc., if you feel so inclined. But even if you don't, keep in mind that every bit of work you already did for the tldr-pages project was a voluntary gift of your time to this community. Your efforts have contributed to a project which helps hundreds of people every day — be proud of it!

And of course, you're welcome back anytime as a maintainer, if you so choose — in which case we'll re-add you to the organization, as is also described in the guidelines. In the meantime, we wish you the best of luck in your new endeavors!

What do you think?

[waldyrious]

As for the current org members who are not actively maintaining the project — @danzimm, @edgurgel, @felixonmars, @igorshubovych, @Leandros, @Ostera and @rubenvereecken: as you can read above and in #1839, we have just adopted a governance policy aimed at improving the project's long-term maintenance workflow, and making sure the tldr-pages organization membership accurately reflects the active maintenance team. Check out the final document at https://github.com/tldr-pages/tldr/blob/master/GOVERNANCE.md.

With that in light, we'll be moving you to the status of collaborator / former maintainer. This means you will cease being members of the organization, but will keep commit access (and with it the ability to edit files, merge pull requests, close issues, and so on). You'll also retain admin access in the repos within the organization of which you are the creators or main contributors.

I'll wait for a couple days for your reactions, and then perform the changes. Of course, you'll automatically be added back in case you decide to return to active maintenance of the project. Is that OK with you?

[edgurgel]

Yes, totally fine 👍

[agnivade]

@waldyrious - The messages look great. I will start inviting collaborators.

[felixonmars]

I thought that I'll be back occasionally, and sometimes review a PR or two, but turns out to be really rarely. Thanks for putting these together and making it easier to attract new members. I'll still keep an eye on the python client.

[waldyrious]

I thought that I'll be back occasionally, and sometimes review a PR or two

@felixonmars just to be clear, you will still be able to do that :) Think of this change as the project releasing you of the responsibility of being officially tagged as a maintainer. This simply means that you won't be expected to be available to maintain the project on a regular basis (which matches your real availability), but still can do it whenever you like. We'd appreciate that, in fact!

[waldyrious]

@agnivade I was wondering if it would make sense to wait until the invitees react to these messages before adding them. Perhaps we could add to the end of the messages "Please reply or thumbs-up this message to confirm."

What do you think?

ps - except for inactive maintainers, for obvious reasons.

[maxsxu]

That's great. So clear roadmap. @waldyrious

[agnivade]

Um, the invitations are already out :)

[waldyrious]

Um, the invitations are already out :)

Yeah, I'm aware :) I was suggesting to add that to the templates above, to be used for future invitations. After all, we'll probably want to keep them somewhere permanent, such as the maintainer's guide or some auxiliary document with template messages (common responses to issues, etc. — /cc @sbrl).

[sbrl]

Sounds great to me! Probably better than I could have worded them :P

[waldyrious]

Hey @agnivade, did you have the chance to experiment with the token change for Travis? I'd like to move forward with the organization-level changes, but I don't want to break any workflows.

[waldyrious]

Also, where do you guys think the template messages proposed above would fit best? GOVERNANCE.md? maintainers-guide.md? Somewhere else?

[agnivade]

did you have the chance to experiment with the token change for Travis?

Not yet. I will do them today.

where do you guys think the template messages proposed above would fit best?

I would say maintainer's guide.

[maxsxu]

maintainer's guide is a good place. 😄

[waldyrious]

Thanks both for the feedback. I started doing as you suggested, but eventually had to go for a different approach, which in the end I think ended up nicer. Please see the details in this comment.

[waldyrious]

Given #1899 and #1902, I'll go ahead and perform the changes to the organization members mentioned above, now that a week has passed since that comment.

• Update 1: I've tested the process with @Ostera, to see how GitHub processes org removal. It looks like the existing collaborator access is also removed, so I'll have to fix the documentation at Complete maintainers' guide #1897 to ensure this is accounted for. I've re-invited him as a collaborator here, which would explain the notification he probably got.

• Update 2: I've updated the membership status of the remaining members: @danzimm, @edgurgel, @felixonmars, @igorshubovych, @Leandros, and @rubenvereecken. The "convert to outside collaborator" option converts them automatically to collaborators in all the repositories of the organization (which is the access they already had as org members) — but that doesn't match the flow we defined for community roles at [RFC] Project governance, Maintainer's guide #1839.
  One way to achieve that could be to remove them from the organization and then re-invite them to the repositories where they had effectively been involved with (see below for details), but that would make the process more cumbersome, since they'd now have to accept the invitation before the change takes effect.
  Another option could be to convert them to collaborators, and then remove their access to the repos they hadn't participated in, but I honestly feel that's unnecessary and borderline aggressively pedantic.
  So with no way to implement the current flow cleanly, I'll also update the documentation at Complete maintainers' guide #1897 to match the results of GitHub's "convert to collaborator" function.

• Update 3: I've deleted the teams in the organization ("Content", "CPP client", "Python client", "Node client", "Elixir client"), which served to provide tiered access to the organization's repositories. Our newly adopted policy simplifies such access levels to a single organization-level access, for simplicity, so the teams are now unnecessary (besides, there wasn't a way to make them public, which goes against our goals of transparency and openness in the governance of the project).

• Update 4: I've updated collaborator access levels for newly transitioned org members to "write" across the board, since the existing organization membership setup included lots of inconsistency with some members having admin access to some repos, some write access, and some even read-only access. Now, every former member has write access to the repos they previously had access to at any level.
  The creators / main authors of the repos retained admin-level access. These are @felixonmars for tldr-python-client; @Leandros for homebrew-tldr and tldr-cpp-client; @igorshubovych for tldr-node-client; and @rubenvereecken for tldr-lint.

• Update 5: I've removed current organization owners from the lists of collaborators in the organization's repositories, since they already have admin access to them. If/when they are eventually converted to collaborators, they'll automatically join those lists.

These changes can be reviewed by current organization owners in the audit log.

[waldyrious]

Regarding other repos in the org, I've invited collaborators for the Python client (tldr-pages/tldr-python-client#55) and for the Node client (tldr-pages/tldr-node-client#197). Let me know if I forgot anyone!

[waldyrious]

The last step that I can do now is making sure all members of the organization have their membership as public. I missed this before, but it looks like @rprieto's membership is set to private. Only he can change that to public, so I'll ask him here to please do so :)

We can also decide to mark the first item in the list above as done (inviting more collaborators), now that @pxgamer and @jsonbruce have been added. I'll open a new issue to track retroactive adding of collaborators based on past contributions. What do you guys think?

[sbrl]

Sounds good to me! Thanks for all the hard work, @waldyrious :D

[waldyrious]

It's been a pleasure to get this long overdue task off my list :) can't wait to get back to reviewing PRs and contributing pages myself! 😄

[waldyrious]

Update: I think we should leave it to @rprieto to decide whether to make his membership in the tldr-pages organization public or not. We already have an exception for the inactivity rule in his case, since he's the creator of the project, so there's precedent for adding an exception to the "publicness" of his membership as well.

Not to mention it might actually convey the incorrect idea that he's presently active as a maintainer, and as someone who people could contact for issues with the project, which is not the case IIUC. So I'll also consider item e) in the opening comment also fully completed, unless others object to this.

[waldyrious]

Given the above comment, and the opening of #1949 to track the remaining work to be done for item a), I'll consider this issue resolved. Thanks everyone for the patience and contributions to the discussion!