If you aren’t familiar with GitHub’s organizational options, they are a really neat feature that allows for some general defaults to be set up for an overall organization. It’s a great way to establish some consistency within a set of projects in an Organization. Need a default license? A default Code of Conduct? To set-up a lot of issue templates without the tedious two-step “copy/paste” into every repository? The Organization’s .github directory is the place to do it. GitHub has been adding new features into the proverbial ‘.github’ repository or directory for a while now, and they are an effective way of tracking and controlling how GitHub works. What we are specifically looking at here comes from the GitHub Community Health Files, where there are many things that can be established as defaults for an Organization.
In VMware’s GitHub footprint, we’ve been turning some of these features on generically in our Organizations, with the intent of keeping things generic (we have a diverse set of developers and users) as well as just providing good basic defaults for projects. While we think the defaults are good starting places, a project may need to fine tune those settings and want to provide alternatives to the defaults. The good news is GitHub allows for local repositories to override the Organization’s files with their own. But knowing how to override these defaults may not be obvious. Here’s a short primer on how to do just that.
How to Override an Organization’s Defaults
Generally speaking, you can override the default Organization’s .github repo’s choices by making a .github directory in your specific project space and providing a file with the same name. GitHub will generally follow this order in checking things, and take whichever it finds first:
Project specific file in .github -> File from Organization’s .github.
There is an odd special case that should be taken into consideration. In the case where the Organization has an established default file, but a project doesn’t want or need that default, overriding that default assignment is not necessarily obvious. However, we did find a way around it.
As mentioned, GitHub looks for the files in the following order:
Project specific file in .github -> File from Organization’s .github.
This means that the project’s designated files will override the file at the Organization level if it’s present. And that’s the key. But there’s more. GitHub takes this comparison slightly beyond that and equates an empty file as a file that is not present. Meaning, an empty file will not override the Organization’s version.
Thankfully, this isn’t a big deal. Assuming a file is present and it contains content, this approach will work.
Case in point on https://github.com/vmware, we have a .github repository that defines some generic issue templates. For the sake of argument, let’s say you only want to have a template for bugs without any of the other features, or vice versa, or none altogether you can accomplish these overrides by that by having a file similar to these:
To override: <organization>/.github/.github/ISSUE_TEMPLATE/bug-report.yml
Add to: <organization>/<repository>/.github/ISSUE_TEMPLATE/bug-report.yml
name: 🐛 Bug report
To override: <organization>/.github/.github/ISSUE_TEMPLATE/config.yml
Add to: <organization>/<repository>/.github/ISSUE_TEMPLATE/config.yml
blank_issues_enabled: true
To override: <organization>/.github/.github/ISSUE_TEMPLATE/feature-request.yml
Add to: <organization>/<repository>/.github/ISSUE_TEMPLATE/feature-request.yml
name: 🚀 Feature request
That might not look like much, and it’s not. Each of those files have a total of one line but it’s sufficient in letting GitHub know that you don’t want the Organization’s version of the templates. They will likely throw out some errors if you look at them on GitHub, as they aren’t technically valid, but they will (respectively) override the Organizations files should you want to. And if you override all of them in this manner, you will effectively go back to having no templates at all.
One Size Fits Only Some
In the end, Organizational defaults are great things. They can simplify management and organization, and keep an entire Organization more consistent. However not every project is the same, and sometimes these defaults aren’t right for specific projects. Understanding the tools we have to work with can help a project choose for itself what works best for it. Sometimes just asking different questions is needed, and sometimes being able to disable them entirely is what the project needs for itself, and it’s community.
Stay tuned to the Open Source Blog and follow us on Twitter for more deep dives into the world of open source contributing.
