meta
meta copied to clipboard
executablebooks
Reference developer conventions in repos (+CoC)
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)
- [x] jupyter-book (https://github.com/executablebooks/jupyter-book/issues/825)
- [x] myst-nb
- [x] myst-parser
- [x] markdown-it-py
- [ ] markdown-it-myst (when moved)
- [x] sphinx-book-theme
- [ ] sphinx-copybutton
- [ ] sphinx-togglebutton
- [ ] sphinx-panels
- [ ] sphinx-thebe
- [ ] thebelab (when moved)
- [x] jupyter-cache
- [ ] myst-language-support
(also consider SUPPORT.md: https://github.blog/2017-07-20-support-file-support/)
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.
@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
In the jupyter projects, we use a pattern called "team-compass" that contains a combination of:
- team-wide conversation that doesn't fit into one repo (e.g. we use this to organize meetings, discuss CoC issues, plan grants, etc
- information about and for the team (things like what @chrisjsewell added in guidelines PR, also things like general "contributing" docs)
- shared infrastructure resources (for things like bots, CI/CD configurations, etc)
some examples:
- https://github.com/jupyterhub/team-compass
- https://github.com/jupyterlab/team-compass
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)
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)
hmmm, I wonder how other projects have handled this
No idea, send out a tweet lol 🐦
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?
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/)
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
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.
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?
@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.
Ok so be-it, the development conventions have been removed from the documentation: b4c48a6c867ef62c6c4a8a8c10c338c68c22c57c
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
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
- You will now see the community issue templates, then
- The community guidelines and CoC are linked to (and same for PRs):
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
