GitHub template repository with best practices

👥 Working Groups Governance
1

Hi,

I’ve been working on preparing a template repository for GitHub trying to follow some recommendations and best practices to build sustainable projects.

GitHub Best Practices Template

The repository currently provides some indications (and templates) for:

  • Project Description
  • Contributing guidelines
  • Code of Conduct
  • Governance rules
  • License
  • Code owners in your project
  • Templates for your issues/pull requests
  • Security policy
  • Fundings file
  • Citation

The objective is to provide a nice scaffolding solution for any project. Developers would only have to use the repository as template and adapt and fill the gaps in the templates.

Any comment would be more than welcome!

3 Likes
2

I don’t think it’s just about the project documentation, but also about the nature of the project.

Here’s some fun reading from Sophie Huilian Qiu and Bogdan Vasilescu’s lab: https://dl.acm.org/doi/pdf/10.1145/3359224

1 Like
3

Thanks @RichardLitt ! I remember having read that paper, I’ll revisit it :nerd_face:

4

Also, this is old, but this is what I used to use when I audited repositories full-time. audit-templates/audit-template.md at dd837d08c357b1bff09fca80269fdb59f8719a74 · mntnr/audit-templates · GitHub

2 Likes
5

oldie but goldie! thanks again!

6

Thanks for sharing your checklist!

2 Likes
7

In the past I contributed to

1 Like
8

Hi Ryuno-Ki,

thanks a lot! those indications & checklist are quite useful to guide the writing of readmes. I’ll review it to see how to enrich our proposal, thanks again!

Cheers,

9

As I’ve been thinking about setting up better standards for my repos, this is a great start. A few questions for Javier:

  • I presume you’re happy to accept contributions? :grinning:
  • Is the choice of CC-BY-SA intentional, or just your default for projects? Switching to any permissive license makes it more likely different users would be interested in using the template. In particular, I’d be nervous using this as a template, because I’d need to ask myself: if I just use this as a template and update for my own uses, does that mean my entire doc set has to be CC-BY-SA?
    • The key question is: are you building a research project, or a template to give away where you want as many coding projects to use it (perhaps so we can later do research by looking at projects who do)?
  • Have you thought about tying details here more directly to the default repo files that GitHub offers? They also suggest a SUPPORT.md file, which I think is useful.

Separately, seeing the default repo files docs makes me wonder if the root dir is the best place, or if files like this work better in /docs to keep the root cleaner (except for of course README.md). Although I suppose that kind of question will always be a personal style thing, given how many other config files tend to clutter the root dir of a repo anyway…

10

Hi @ShaneCurcuru!

of course contributions are welcome! feel free to open a PR :partying_face:

Regarding the license, in this particular project, I think relaxing the license may help reaching more public. I’ve changed the license to CC-BY, I’ll see if that helps.

I didn’t hear about SUPPORT.md file, I’ll have a look, thanks!

Cheers,

11

Also related, I just learned about Justin Colannino’s Minimum Viable Governance MVG repo, that contains a complete, well defined, yet simple governance model you can drop into a repo to govern a group of maintainers. Well worth a read.

Long term - it could be exciting to work with GItHub (or other repo hosters) to build a “choose a governance model” into their new repo tool, like ChooseALicense.

2 Likes