Organization tooling for GitHub and npm

[johno]

For large projects, especially those that are split amongst numerous
organizations like unified, are often required to perform a lot of
manual admin tasks.

---

Rendered version

[wooorm]

This is great!

I’m a bit worried about .github repositories as it might conflict if GH decides to set something like this up as well (I think it makes sense for GH to do so).
And I wonder whether having a structure for npm is a bit confusing.

I wonder what else we could automate? badges? Org settings like 2fa security, repo settings like the URL, topics, merge/squash/rebase options, projects, wikis, branch protection rules?

[wooorm]

@RichardLitt I’m sure you’ve done some similar stuff with Maintainer Mountaineer (and maybe that it also conflicts 😬)

@zeke do you have some pointers on similar previous work, or if we could/should GH actions / Probot apps or something else?

[zeke]

Yeah I get asked this a lot, but I don't have a great answer for org-wide GitHub configuration of repos. In general, Probots apps go a long way to help keep configuration out of individual repos. I wish there was a probot for npm publishing.

GitHub Actions might help some of this, but the Actions workflows are also configured on a per-repository basis, so there would still be a lot of redundant configuration for setting up an org.

[zeke]

For Code of Conduct, the Electron project has a single CODE_OF_CONDUCT.md in the main electron/electron repo, and all other repos in the org have a link to that CoC in their READMEs

[wooorm]

@zeke Hmm, yeah, I think we need something new for that 👍
And we currently have one CoC/contributing doc in the main org repo now, but we should investigate if it makes sense to copy them to all repo’s, so they’re easier to find and GH will pick on them as well!

[johno]

I kinda like the idea of repo level files being duplicated within each repo (at least while GitHub doesn't support org-level .github config 🤞😉)

I’m a bit worried about .github repositories as it might conflict if GH decides to set something like this up as well (I think it makes sense for GH to do so).

Makes sense to me. Perhaps we can come up with a different naming convention? Off the top of my head:

• config
• conf
• settings
• org

[RichardLitt]

And we currently have one CoC/contributing doc in the main org repo now, but we should investigate if it makes sense to copy them to all repo’s, so they’re easier to find and GH will pick on them as well!

I would copy them to all repos, especially as they are invariable. This way, GitHub picks them up. Another option is to have a CODE_OF_CONDUCT.md file that just links to the main one in an org repository.

Regarding the tool, in general: I have built tools for this: build-a-space, a tool for automatically updating other repos, and the Maintainer dashboard, a tool for checking how an org or any number of repos look. Both of them could use a little work, but I'm more than happy to do that work, or to redesign how the tool should work in general.

Perhaps we should figure out what the requirements actually are? As far as I can tell, there's a couple of things that my tools don't yet do:

• Configure npm credentials.
• Add labels to repos. For this, I've a few other npm packages and ran a shell script to run them for each repo in an org (it's easy enough to get a list of repos using github-repositories.
• Provide a stable dashboard that you can access online without running it locally.

If we want a tool that does those things, I can work on getting the dashboard online as a service and making it easier to use for team admins, to automatically push buttons and get stuff working. What do you think?

[ChristianMurphy]

I’m a bit worried about .github repositories as it might conflict if GH decides to set something like this up as well (I think it makes sense for GH to do so).

GitHub announced support for using .github repos for community wide files.
https://github.blog/changelog/2019-02-21-organization-wide-community-health-files

[RichardLitt]

Yes! I created https://github.com/unifiedjs/.github yesterday (possibly Monday?), and am going to play around with it to see if it works as advertised. :)

[wooorm]

I’m sorry I‘ve been silent on this lately. I have some halve-working tooling for the GH part, but it isn’t really ready to open up. And I’ve had a busy couple of past and coming weeks unfortunately.

I would like to add that I’m going to be distraction free starting May, so it’s definitely happening then, but I’m hopeful that I could spend time on more policies and tooling before then!

In the mean time, Richard is doing a great job so go ahead and help and review unifiedjs/.github#1!

[zeke]

Hey I just learned about the Settings probot app via https://github.blog/2019-04-10-save-setup-time-with-github-classroom-and-probot -- might be a good fit for this?

[wooorm]

Yes, I believe it could be very similar to the settings app!

I do really like the configuration format. And that it cascades. Most of the current tooling I’ve setup and partially finished works around teams and humans though, which don’t seem to be supported in GH Apps yet (“The APIs needed for teams are not supported yet by GitHub Apps”).

Some ramblings about cascading, I feel we could end up with this:

1. $org/.github/$config
2. $org/$project/.github/$config

(where $org is an organistion, like remarkjs; $config is some to-be-defined file, e.g., config.yml; $project is e.g., remark)

Cascading on by default. Unless an extend directive is found, in which case that file is used. this can be used in the top-level organisation config to load a “collective” config, in for example unifiedjs/governance/.github/config.yml, that everything else “inherits” from.

[johno]

This has been addressed with the combination of .github, github-tools, and npm-tools. Thanks to @wooorm for taking this on and all for the discussion!

[wooorm]

So happy this is done!

Still some work for the future, to streamline this all:

• Thinking of unifiedjs/governance having a humans.yml and structure.yml file with all the info, that gets pulled into the tools
• Somewhere in the future, make it a pluggable system that other orgs can use!

[zeke]

Wow this looks promising. Looking forward to checking out github-tools and npm-tools 👀