GitHub Template proposal


I just created a repository https://github.com/OWASP/github-template that could be used as a copy&paste-resource for projects under OWASP‘s GitHub organization. Why would we need something like this? Because a consistent documentation of high quality is something users and contributors alike are increasingly expecting from providers of open source software!

This is elaborated in more detail in the description of the GitHub Organization Reboot working session which is planned for the OWASP Summit 2017. The topic was also covered in my talk OWASP Juice Shop: Achieving sustainability for open source projects (📺) from this year’s AppSecEU in Belfast. It featured several Open Source Antipatterns, among them being:

  • Barren README: An empty or lackluster front-page radiates the impression that nobody takes serious care of the project.
  • Badge Barrage: The front-page is overcrowded with (mostly useless) information and status badges.
  • PR Disaster: Pull Requests are routinely ignored or flogged to death.
  • Contributor Laurels: Not giving enough credit to contributors.

All these can be countered (at least partially) by the proposed GitHub Template, which comes with a pre-sectioned README.md and several (optional) files for a project’s contribution guide, troubleshooting section and media references of the project. The template is based on my own Juice Shop project repositories, so please refer to these as live examples to determine if you like the structure or not:

  • https://github.com/bkimminich/juice-shop (extensive documentation, large project, uses all proposed sub-files to externalize content off the growing README.md)
  • https://github.com/bkimminich/juice-shop-ctf (brief documentation, small side-repo, uses inline sections over sub-files)

OWASP GitHub Template screenshot 1 OWASP GitHub Template screenshot 2 OWASP GitHub Template screenshot 3

To apply the template to your own or any new GitHub projects, simply follow these steps:

  1. unpack all the files from https://github.com/OWASP/github-template/archive/master.zip into your repository base path
  2. replace all occurences of GitHub Template with your own project name
  3. follow the TODO instructions

At the moment this is only a working draft of a template. Nothing about it is mandatory at this point.

Your Pull Requests, feedback, constructive criticism and other input is most welcome to give us something to discuss during the GitHub Organization Reboot working session at the upcoming OWASP Summit 2017!