Clarify steps to remove organization owners

[waldyrious]

We have detailed descriptions of project governance processes in the COMMUNITY-ROLES.md document, but some of them are clearer than others. In particular, the process for retiring inactive organization owners (of which I was a test subject in #2257) is a bit vague.

To fix this ambiguity, describing the process step-by-step would be ideal. As an initial proposal, I'd suggest changing the following passage in the section "For removing inactive organization members":

Once the role change is completed, make sure to update the lists below accordingly.

... to read something like this:

Once they acknowledge the message (or after a week without any reaction), go to github.com/orgs/tldr-pages/people and [...].

Afterwards, move their name to the list of former owners, below in this document.

Finally, once the membership changes are complete (both removal from the organization and adding as collaborator), and the lists are updated, close the issue opened to track this process.

The [...] part is what I'm unsure about. I suppose it would be something like "remove them from the org and then invite them as collaborators to the repos where they had participated", but then does that process offer the ability to convert them to external collaborators? And if so, is this the same thing as repo-specific collaborators? I suspect not, and if my suspicion is correct, then the latter (repo-specific collaborators) would be preferred, I think.

In addition, there should probably be an extra step to verify that the collaborator permissions are "write" rather than "admin" (this ensures the sets of available actions, and therefore responsibilities, are clearly separated between the different stages of participation, so that there's no confusion about what is expected from each person). It also reduces the risk of damaging actions in case the accounts are abandoned for longer periods and happen to be compromised.

I have suggestions for making all transition steps more defined, but this is what IMO would bring the "retirement" process in par with the other ones, so we should probably start there.

Thoughts?

[agnivade]

All good.

I suppose it would be something like "remove them from the org and then invite them as collaborators to the repos where they had participated", but then does that process offer the ability to convert them to external collaborators? And if so, is this the same thing as repo-specific collaborators? I suspect not, and if my suspicion is correct, then the latter (repo-specific collaborators) would be preferred, I think.

I can clarify that. External collaborators is just a collated representation of repo-specific collaborators. So, for example if a user is a collaborator in 2 repos, then he/she would show up as an external collaborator with access to 2 repos.

You cannot add external collaborators from the org page. One has to go to each repo and do that. So I don't think there are 2 ways of doing this.

Therefore, the steps are -

• Go to https://github.com/orgs/tldr-pages/people
• Select the person, click "convert to outside collaborator".
• This will retain all previous access the person already had to those repos. If in case (like yours), the person was directly added as an org member, one has to go to the individual repos and add the person as collaborator.

Checking for "write" and not "admin" seems fine.

[sbrl]

Sounds good to me! Go to start somewhere, and this does seem like the most logical place 😺

[waldyrious]

Ok, that makes things easier :) So the first sentence in my proposal above would be:

Once they acknowledge the message (or after a week without any reaction), go to github.com/orgs/tldr-pages/people, select the person, and click the "convert to outside collaborator" [button|link].

Please confirm whether it is a link or a button or some other UI element.

[agnivade]

Its a button in a dropdown menu.

[waldyrious]

Ok, that makes it perfectly clear. By the way, the image would actually be a great addition to the docs, don't you think?

[agnivade]

I dont have much of an opinion on that. I think text bullets are fine, but dont have an issue with images.

[sbrl]

Hrm, maybe! They'd help clarify a bit, I think. Unless there are some official GH help articles we could link to?

[waldyrious]

I agree images are ideal, but in the interest of making sure things move forward, I proposed the text-only change (#2279) rather than wait for an opportunity to consistently add images to all steps (which I'm not sure would be a good idea anyway, since the document would become quite long then).

On a separate note, I found myself reconsidering my position regarding having the list of owners at the end of this document. The rationale I presented last time makes sense for the list of current owners, but not as much for the list of former owners, which feels a bit out of place in that file. Does this bother you guys at all, and if so, what would you suggest to improve the situation?

[sbrl]

Thanks for the PR :D

Hrm, what specifically are you talking about when you say that it feels out of place? My only thought of the subject is that the current and former maintainers lists should be next to each other.

[waldyrious]

@sbrl when I moved MAINTAINERS.md to COMMUNITY-ROLES.md in #1897, you asked:

Curious as to why the contents of MAINTAINERS.md has been moved to the bottom of COMMUNITY-ROLES.md, though.

to which I replied:

No particular reason, I just thought it made sense to present the sequence in the "when --> how --> who" order.

And while this can justify including the current owners, the former owners don't really fit that sequence / logic, hence my concern that it might be "out of place".

[sbrl]

Ah, I see. Where else would you propose we put them then?

[waldyrious]

It could make sense to restore the MAINTAINERS.md file, and simply point to it from the COMMUNITY-ROLES.md page (and perhaps rename the latter to something more descriptive of community dynamics / role changes). Another option is could be to simply add that info to the README. Do any of these make sense to you?

Mind you, I don't have strong opinions on this -- it just feels slightly odd, but nothing that we can't live with if an optimal solution can't be easily found.

[agnivade]

I don't mind either way.

[sbrl]

I don't particularly mind either way either. If I had to choose, I'd restore MAINTAINERS.md, and link to it in COMMUNITY-ROLES.md.

[waldyrious]

@sbrl I slightly prefer that option too. Do you mind doing the honors? This week is going to be quite busy for me. Otherwise, let's open a separate issue to track that.

[sbrl]

Oops! I committed to master instead of doing a PR. I'm sure I created a branch..... Said commit is reference just about this comment.

I've restored MAINTAINERS.md. If we're restoring it, should it contain a list of all maintainers too, such as the brilliant @pxgamer?

Thoughts?

[waldyrious]

I've restored MAINTAINERS.md. If we're restoring it, should it contain a list of all maintainers too, such as the brilliant @pxgamer?

Agreed. It should include people at all stages listed in COMMUNITY-ROLES.md (which, again, could probably have a better name to clarify it's primarily about the role transition processes.

[sbrl]

Is there anywhere I can find a list of everyone to update MAINTAINERS.md at all?

[waldyrious]

Is there anywhere I can find a list of everyone to update MAINTAINERS.md at all?

I assume this is the same you asked about in Gitter, so as I said there, the links are available in COMMUNITY-ROLES.md, although it's possible they're not prominent enough there. At the very least, they should be at the top of the corresponding sections in MAINTAINERS.md.

The list of collaborators can found here: https://github.com/tldr-pages/tldr/settings/collaboration; and the list of org members (including owners) is available here: https://github.com/orgs/tldr-pages/people.

Please correct me if I misinterpreted you.

[sbrl]

Ah, oops! I don't think I connected the dots :P

I see now. I'll go and open a PR on MAINTAINERS.md now.

[zlatanvasovic]

@waldyrious What's your stance on this now?

[waldyrious]

It looks like the changes that were discussed here have all been implemented in #2279, 9875efb and #2308. I'll close the issue, thanks for the nudge!

@sbrl, if you could also take a look just to make sure we didn't leave anything out, that'd be appreciated :)

[sbrl]

I think we're good here now. Thanks, @waldyrious 😺