Since it was founded in 2008, GitHub has become a significant site for open source. It’s evolved over time with a lot of ancillary functionality, many areas of which I’ve not had much experience of. Most of my personal development, for conferences and non-ICS areas, goes through GitHub. It’s certainly the place I’ve used typically for conference sessions I’ve co-presented. And GitHub Pages was the place I chose for my personal blog a couple of years ago.
For OpenNTF, GitHub has been used, particularly for our Connections projects. As requested by developers, we set up a repo for people and assign them access. But we’ve also used Atlassian BitBucket, because Atlassian kindly gave us a free license as an open source organisation. That’s integrated into a suite also using JIRA, Confluence (for wiki articles) and Bamboo (for build processing). Once of the benefits of JIRA is the ability to have a single dashboard for specific projects. Confluence works well for wiki articles and I used it for XPages OpenLog Logger and Watson Work Services Java SDK. But GitHub has a lot of popularity, particularly in the wider developer community.
Some time ago I was looking at the Watson Developer Cloud Java SDK GitHub repo, when working on Watson Assistant and setting up an XPages Library for Watson Developer Cloud. There were a few aspects of that GitHub repo which were of particular interest to me – code of conduct, contributor covenant, templates for issues and pull requests, integration with CLA Assistant to manage Contributor License Agreements.
Outside of certain projects, like XPages Extension Library, pull requests are probably rarely used in OpenNTF repositories. More typically, everyone collaborates on the same repo in a haphazard manner (which is certainly the case with OpenNTF Domino API, I freely admit). But when collaborating on someone else’s project, as I’ve been doing recently on the IBM Connections Node-RED Nodes, pull requests are the correct way to go. There are specific best practices here, some of which were covered to an extent when the XPages Extension Library first became open source, but that’s best placed for a separate blog post.
So when I was taking on a GitHub repo and looking at receiving and processing pull requests, while also being conscious of CLA requirements and the need to manage that, what I had seen in the Watson Developer Cloud Java SDK was something I wanted to adopt.
Issue Templates
The first step was setting up issue templates. Setting up issues templates and pull request templates is documented in the GitHub help if you want more details. They can either be at the top level, in a docs folder or a .github folder. In most repositories I’ve seen them, they’ve been in a .github folder. That makes sense because it keeps the top level clean and docs folder can be used specifically for documentation.
As a pre-requisite, you might want to go into your “Issues” tab and review the labels you’ve got set up to assign to issues. Click on the “Labels” button and you’ll be able to add, edit and delete all the labels available for you and for users. “good first issue” and “help wanted” are ones I’ve seen on other GitHub projects. They’re useful for encouraging contributions from beyon the main collaborators and from developers new to the technology or process.
Setting up issue templates is very easy to do, with a GUI for managing it on the Settings page of your GitHub repo. “Issues” should already be enabled, assuming it’s a repo you wish to actively maintain (a repo for demos for a conference, for example, may be more “YMMV” so issues are less relevant).If you plan on using GitFlow or some flavour of it, it’s probably worth enabling that on your repo first as well. The templates get created in your default branch, so this will ensure they don’t get put in all branches.
Clicking on the “Set up templates” button allows you to create and manage templates. It will allow you to create templates for bugs, feature requests or custom templates. Editing the template is straightforward, using markdown to set the content. Typically this would give some instructions to help whoever is submitting the issue, so that they provide the information needed to act. You can also add default metadata, like the label to assign.
Pull Request Templates
Pull request templates dont have the same GUI. Instead they have to be created manually, the way issue templates also used to be created. This is why I created the issue templates first. I’d recommend creating it on GitHub itself, as the documentation advises. (I initially tried creating both issue templates and pull request template in my local repo and pushing up, but it didn’t work, maybe I did something wrong.)
Once set up, whenever anyone creates a pull request, the template will be used.
Health Files
You can also set up what are called health files, namely a Code of Conduct and Contributing guidelines. Once set up, they will be available for users when they create an issue or pull request. They will be created in the same folder as the other files we’ve created, and will be called CODE_OF_CONDUCT.md and CONTRIBUTING.md. You can select from an existing Code of Conduct template or create one from scratch. The CONTRIBUTING.md is more a personal document. The third type of health file you can create, if you wish, is a support file.
Default Files Repo
If you wish, you can create a respository of default files for an organisation. We may do that for OpenNTF in the future. At this point, we’re new to this so we’ll wait and see.
CLA Assistant
CLA Assistant is a tool and site set up by the GitHub team at SAP and it allows the repo or organisation owner to track whether the person who creates a pull request has signed whatever contributor agreement should be followed. OpenNTF has always enforced contributor agreements and the reasons for that are clear. It’s important for those consuming the project to have confidence they can use it. It’s crucial for those receiving pull requests to have confidence they’re not invaliding the license they choose to apply to the project. And it’s a critical step if any code is to be taken back into a core IBM product.
Setting it up was surprisingly easy. From the site you configure a CLA either for a whole organisation or a specific repo. If you choose the whole organisation, you can exclude from specific repos. You then choose a CLA from Gist, another GitHub site for small files or snippets. The content we used was the main part of the ICLA. You can specify a minimum number of files or lines of code that need to be updated in a pull request before you require the CLA to be signed. You can also specify usernames or organisations to whitelist – so they don’t need to complete the CLA.
Now, when someone submits a pull request – and also for any pending pull requests – a comment will be added to say that the CLA has not yet been signed. The person just needs to click on that button and digitally sign the CLA. Of course it only needs to be done once for the repo or, if the CLA is assigned to the whole organisation, all repos.
Once completed and re-checked, the repo owner can confidently accept the pull request.
The even better thing, from OpenNTF’s point of view, is that we can easily see everyone who has signed the CLA. We don’t need to track it manually. It doesn’t need to happen retrospectively when the IP manager reviews the project release. It’s all done already, as soon as the pull request is accepted.
And if pull requests are used for all issues or features, as I covered in a recent blog post “Adventures in Git“, it ensures every developer on the project has signed the relevant CLA. It also encourages issues and features to be created for all development. And it makes it easier to manage traceability for the work done for each. And from that, it makes it a lot easier to generate your release notes.
It may seem more work, but in my opinion it’s worth it, particularly when it comes to supportability.
