Just following with the repo permissions discussion originally started here:
So my opinion is very much from an organisational governance so this may reflect my proposal. I’m happy to adapt as the project’s governance hasn’t yet been finalised.
Currently new users (lets say users instead of members as this is a term used in GitHub) invited to the opensourceway organisation default to being Member. These users will be able to clone and pull all repos the organisation owns – currently that would be guidebook and theopensourceway_old_website
“By default, members of an organization will have Read permissions to the organization's repositories.”
This “green room” allows the owners to allocate higher level of permissions if and when required. I think we should keep this default whilst teams are being decided and when more teams are being added.
Just to note that there are both “base permissions” and “repository permissions” allowing more refinement of access for members of the organisation (or external collaborators) specific to a repo. The above suggested Read permission would be the base permission of the organisation.
To apply repository permissions I would suggest we use teams with the appropriate access.
From least access to most access, the permission levels for an organization repository are:
• Read: Recommended for non-code contributors who want to view or discuss your project
• Triage: Recommended for contributors who need to proactively manage issues and pull requests without write access
• Write: Recommended for contributors who actively push to your project
• Maintain: Recommended for project managers who need to manage the repository without access to sensitive or destructive actions
• Admin: Recommended for people who need full access to the project, including sensitive and destructive actions like managing security or deleting a repository
Currently there is only really a need for the Triage where members can:
• Assign labels, issues, and PRs
• Apply milestones
• Request PR reviews
See more of a detail breakdown here: https://help.github.com/en/github/setting-up-and-managing-organizations-a...
However Triage can not physically push to the repo i.e. merge or force push to that repo or branch directly. They can, like other users, create a Pull Request from a forked repo and follow the review process.
This maybe considered too restrictive but I feel its acceptable that authors themselves, who wrote the piece, are not permitted to push to the repo – it would imply that a review hasn't taken place. Ideally it would be the review team that would say OK after some back and forth and they themselves merge the author’s content in. This implies that that there would be a team of editors.
Editors themselves would have the Write permission which of course grants more permission including:
• Push to the contributor’s branch (easily)
• Lock conversations
• Submit reviews that affect a PR’s mergeability (this feature flags when PRs shouldn’t be merged)
• Apply suggested changes to PRs
Of course members can be added to multiple teams with the more permissive level being applied.
It really comes down to the teams and what roles they play in the repo and gradually adding more teams if and when required. Currently I can envision the below teams based on the current flow of the workflow process:
• Authors: members of the organisation that have been assigned as author or co-author of a chapter. They are also able to assist with labeling issues to help other authors on boarding.
• Editors: members of the organisation that can perform editorial reviews on author’s contributions permitting successful contributions to be merged into the repo.
These teams are very simple and serve a very distinct role in the project, but we should also consider the glue that keeps the repo going identifying that group of members. Usually we would have the term “core” team that do a wide range of things outside the scope of the current authors and editors. But at the moment I think there isn’t a current need to identify that but something to consider when the project becomes more mature.
Another note that Outside collaborators (those not invited to the organisation) can be invited to a repo’s team in case they wish not to be added to the opensourceway organisation.
Lastly only owners can assign repositories to teams and therefore manage team access (though I believe members of an organisation can create teams).
Here are steps to do this here: https://help.github.com/en/github/setting-up-and-managing-organizations-a...
Any thoughts would be much appreciated!
Hey everyone, just a few thoughts on this (I’ll open up another one for the interview stories)
As now the requirement to have the SME pass as a part (the first part even) of the Editorial process it would be great to define for both the contributor and the team the responsibilities of nominating, acquiring and assisting said SMEs.
Perhaps it would be beneficial to draft out guidelines on the individual steps including how to obtain, facilitate with the author, sign off, and retain their assistance for future chapters if possible. I would assume a SME in one area could also be a SME in another.
Granted, getting some SMEs will be more difficult than others (especially if they are from a different industry e.g. medical) but generally the process should follow the same flow. I will also admit that I have not pursued a SME before, and those with more experience in doing so your insight would be extremely appreciated.
I drafted up a few ideas into the initial “stages” as I dn’t want to get too ahead of myself.
• Authors would be able to nominate multiple SMEs as part of their contribution. This is with the assumption they have conducted research and are aware of SMEs in that particular subject. However, it should be noted that this isn’t a requirement for the following reasons: we don’t want to raise the on-boarding higher for authors; the subject could be outside their industry; they could be the only SME themselves or don’t know enough SMEs to identify a preferable one.
• If an author does suggest SME(s) they also provide references or other form of verification of knowledge/expertise. Link to their talks, books, articles, etc.
• If there is no SME nominated then it would fall to the TOSW (The Open Source Way) team to source this (I would expect)
◦ Would this be who ever is assigned as editorial team picking up that PR/chapter?
◦ Would be good to have a label “Needs SME” so everyone could chip in and make suggestions
◦ Would also be good to have a list of proposed SMEs for different sections. Additions made to this list can be ad hock “Oh I just watched this great talk from so-so and they demonstrated a lot of knowledge in X, I’ll add it to the nomination list”. We can use this list to when we come across chapters with the “Needs SME” label and see if someone has already been nominated on that particular topic. We eventually could identify the status of that nominee if they participated, not been asked or other when we start getting more content.
• If there are multiple SMEs requested for the same chapter I would think that by approaching them all would help increase the chances of them accepting. If they accepted but the chapter was allocated to another SME, we should encourage them to be an SME or an author in another chapter. Hopefully they would be interested to do so.
Would be nice to have a informal canned response to asking a potential SME to participate.
• If there is a conflict about the most appropriate SME (doubt this will happen) then the TOSW would collectively agree on the appropriate SME on the PR itself?
• Who’s responsibility is it when an author has submitted a contribution and a SME is required. Who to reach out to the nominated SME?
◦ I would think it would be TOSW team’s responsibility
◦ Unless the author has stated they have a line of communication to the nominated SME. Would the TOSW team assist?
• We could fall into the chicken & egg scenario where a SME could be ‘anyone’ in a particular field. This is relevant to those chapters that may overlap other industries like medical so a nominated SME could simply be “a professional in that area”. This would mean that a SME could be acquired prior to a signed off nomination.
• Note here, I assume that TOSW would perhaps have more leverage to request for assistance from potential SMEs due to the proportion of RedHat employees on the team and thus have a larger pool or SMEs to request internally.
• Should we have timelines to give SMEs?
◦ We should have a label indicating that the chapter is being “SME reviewing” or something similar or would its position on the project board be enough?
• What will the on-boarding of an SME look like? Would they be credited, how?
• How would the SME and author communicate. Ideally it would be via the GitHub repo but that in itself has a learning curve and we can’t assume SME will learn the tool. What would be the most simplest alternative? Email, private calls? Who’s responsibility is it to arrange these?
◦ My immediate thought would be the editorial team member assigned the chapter would start the interaction between the two and only nudge the author and SME for an update occasional… But ultimately the author would be responsible for the actual sessions/communication.
◦ We may have to draft up a simple process for those to raise issues regarding to the author/SME interactions to the assigned editorial team member (or TOSW editorial team). Things like, clash of ideas, lack of response etc.
• Once the author and SME are happy with the review they would indicate this on the PR itself.. Perhaps a label “SME passed”. The chapter would then proceed to the next pass.
So OK, those my initial thoughts.
My biggest drive to thinking about this is entirely selfish (haha) for the self-care chapter and obtaining an appropriate SME. I feel I could help with acquiring a SME (a medical or mental health practitioner) but wanted to see if that is going beyond the responsibilities and/or there just needs to be an alignment and communication on who is connecting who :)
I’m interested in getting involved with the new edition of The Open Source Way. What’s the best way for me to contribute?
Lead Technical Writer, Red Hat Ansible Automation Platform