executablebooks / meta

A community dedicated to supporting tools for technical and scientific communication and interactive computing
https://executablebooks.org
132 stars 167 forks source link

Reference developer conventions in repos (+CoC) #79

Open chrisjsewell opened 4 years ago

chrisjsewell commented 4 years ago

Not sure where the best place(s) to do this is, e.g. README.md, CONTRIBUTING.md, in the RTD docs and also remove/streamline any duplication of the conventions from the repos

At the same time can also add/reference Code of Conduct (#62)

(also consider SUPPORT.md: https://github.blog/2017-07-20-support-file-support/)

mmcky commented 4 years ago

Thanks @chrisjsewell -- this is an important issue -- as I get confused where things should go and I am part of the project. Should we setup a executablebooks/contribute repo that contains all material across repos for contributors.

An alternative would be to setup a org wide docs repo that contains userguides, general project information for jupyterbook etc. which could be a site that then references all the sub-repo's documentation sites as an organisational layer and single point of entry to all documentation.

chrisjsewell commented 4 years ago

@mmcky I was going to suggest just using this repository, but actually I see you can also create a .github repository to store default "community health" files: https://docs.github.com/en/github/building-a-strong-community/creating-a-default-community-health-file

choldgraf commented 4 years ago

In the jupyter projects, we use a pattern called "team-compass" that contains a combination of:

some examples:

chrisjsewell commented 4 years ago

Should we just change this repository to be named .github? The con is that it's not as self-descriptive as meta or team-compass, but the (big IMO) pro is that you get this default automation by GitHub

(e.g. in #80 I have made the dev-conventions.md just include CONTRIBUTING.md, so if we changed this repo name to .github it would now automatically be referenced in all repos that did not already contain a CONTRIBUTING.md)

choldgraf commented 4 years ago

hmmm, I wonder how other projects have handled this. I agree that it would be great to have a single place to standardize the things that can be auto-added to repositories with .github/ but I also think it's clunky to have a "team repository" that's called .github/.

Could we just put whatever is appropriate for .github/ in there, and then in our team docs (meta/ or team-compass/) we add links to those files? (we might even be able to {include} them by pointing to their locations on github)

chrisjsewell commented 4 years ago

hmmm, I wonder how other projects have handled this

No idea, send out a tweet lol 🐦

chrisjsewell commented 4 years ago

I also think it's clunky to have a "team repository" that's called .github

It is, but I think it is the lesser of 2 evils, rather than effectively having to have to maintain two meta-like repositories and splitting discussions between them. Plus this repository is not too public facing, i.e. its just for our discussions, so I don't think its too much of an issue to not have the best name, as long as we know where it is. Therefore, I would still vote to rename this repository to .github.

@mmcky, @jstac, @AakashGfude what's the group consensus?

choldgraf commented 4 years ago

FWIW we do use the .github repository as well in jupyterhub (https://github.com/jupyterhub/.github). We just only use it for github-specific metadata. Thus far this hasn't been an issue - we just define the role of the .github/ repo very narrowly - it only stores one kind of thing, which is github repo configuration, and everything else is in the team-compass repo.

Or put another way, the two repositories serve different purposes. One stores programmatic data for re-use across repositories (.github/) while the other is meant as a clearing-house for team conversation, information sharing, and public-facing documentation (team-compass/)

chrisjsewell commented 4 years ago

We do use the .github repository as well in jupyterhub

Well actually you don't really use it correctly 😛 because you have the CODE_OF_CONDUCT.md and docs/contributing.md in the team-compass when they should be in .github

Or put another way, the two repositories serve different purposes...

I disagree that this is entirely the case, following from above; CONTRIBUTING.md, CODE_OF_CONDUCT.md, etc are important parts of the public-facing documentation

choldgraf commented 4 years ago

sure - it's always a work in progress :-) a lot of the stuff that's there was created before .github/ was a thing and just hasn't been touched in a while. And in general those files are just linking out to the documentation for that repository since we usually put the "content" of the contributing docs in a Sphinx site that is repo-specific, so we haven't enforced strict rules for them in the .github/ repo. The "contributing" docs for the team-compass repository are more "how to get involved" docs for the whole project, as opposed to something that makes sense in the context of any one repository.

My more general point is that where we have a choice between designing for humans and designing for machines, we should maximize and favor designing in human-friendly contexts, and minimize / find workarounds for designing in machine-friendly contexts. IMO a human-readable repository name like meta or team-compass is more human-friendly and expressive than .github.

AakashGfude commented 4 years ago

To me, it feels like a combination of both of your ideas can be a good approach. A .github repo with all the necessary configs and md files - CODE_OF_CONDUCT.md , CONTRIBUTING.md etc. Since it is a nice way to maintain consistency, in that we only have to edit one file instead of individually doing it for all repos with common community health files.

We can treat the .github repo just for config, health files, public facing documentation. And create issues, relevant only for those files there ?

And keep this as a place for planning and collaborations?

mmcky commented 4 years ago

@choldgraf I think the definitions you introduced are sensible delineators and agree with @AakashGfude

One stores programmatic data for re-use across repositories (.github/) while the other is meant as a clearing-house for team conversation, information sharing, and public-facing documentation (team-compass/)

It seems sensible to me to use .github for programmatic / re-use across the repos and seems aligned with what github had in mind for it: https://docs.github.com/en/github/building-a-strong-community/creating-a-default-community-health-file I view .github as a source for default files / sponsor config buttons etc.

I think most team wide discussions should be retained in meta or team.

chrisjsewell commented 4 years ago

Ok so be-it, the development conventions have been removed from the documentation: b4c48a6c867ef62c6c4a8a8c10c338c68c22c57c

choldgraf commented 4 years ago

so, how should people find those developer conventions? (I've never used the automatic github thingy so I just don't know where to look).

In the docs, I don't think we should remove a reference to them entirely, we should add a link to wherever users should find them

chrisjsewell commented 4 years ago

so, how should people find those developer conventions?

So if you open an issue now e.g. in https://github.com/executablebooks/sphinx-book-theme/issues

  1. You will now see the community issue templates, then
  2. The community guidelines and CoC are linked to (and same for PRs):

Screenshot 2020-07-29 at 17 35 04

image

we should add a link to wherever users should find them

Was easier when they were in the same repository 😉 but I'll leave that for you to do

We can also add some https://github.com/behaviorbot (as they do in jupyter) to link to them when new users open their first commit/pr

chrisjsewell commented 4 years ago

added the welcome bot 😁

image image
choldgraf commented 4 years ago

amazing - nicely done