Building strong ties in the community with GitHub Community Health Files

The Insight Toolkit (ITK) is an open source software project that provides computational image analysis methods that are high quality, cutting-edge, and well-documented through its vibrant community. In this post, we discuss community health files created for ITK’s migration to GitHub.

As a standard, basic entry point, ITK’s CONTRIBUTING.md document specifies the ways in which community members can contribute to the toolkit. Moreover, GitHub recently added support for additional community health files that can be applied across all repositories in a GitHub Organization.

GitHub labels

GitHub issues and pull requests can be labeled so that community members can clearly identify the areas the issues and contributions are related to. This helps a contributor grasp a clear picture of the tasks ahead, as well as a mechanism for organization.

Labels in ITK are grouped into three categories:

• area: area of the toolkit affected by the issue or pull request.
• status: status of the issue or pull request for cases when further data is required to reproduce the issue, or when the issue is blocked by another task that is yet to be solved, etc.
• type: nature of the issue or pull request (e.g. enhancement, bug, etc.)

For further information on creating GitHub labels, please visit GitHub’s creating-a-label help page.

GitHub issue templates

GitHub issues can be customized to offer templates that are tailored to a project. In ITK, given the depth and breadth of the project, we decided to provide a series of templates to guide contributors so they provide required information concerning an issue. Reviewers then have the same information to reproduce, confirm and help find a fix to the issue.

An issue template is specified as a Markdown *.md file located in the .github/ISSUE_TEMPLATE folder. Each file contains a series of sections to allow for a clear and detailed description of the issue, the current and expected behaviors, as well as the affected versions, and the necessary data to reproduce it.

Issue templates are also accompanied by HTML markup comments to guide community members through the process and report sections.

Each issue template Markdown file contains a YAML header that allows a template to specify some of its properties, such as its name and its description. GitHub labels are assigned automatically depending on the nature of the issue through specification in the YAML header.

Finally, with the clear intention of providing a more visual guide through the issue templates, YAML headers are enriched with Unicode emoji code points. Note: not all are supported (there is no list of supported code points) and not all Markdown-syntax emojis were supported at the time the ITK GitHub issue templates were created.

GitHub pull request templates

GitHub pull requests can be customized to offer templates that are tailored to a project. The pull request template provided in ITK contains HTML markup comments that provide guidance to users when opening a pull request, but the comments are not displayed as part of the pull request once it is opened.

Also, a series of checkboxes allow reviewers to have a grasp of the components of a pull request, as well as serving as a reminder to contributors of the components a pull request may require.

In ITK, since a single pull request template is offered, it is directly located under the .github folder (i.e. no PULL_REQUEST_TEMPLATE folder exists).

For further information on GitHub issue and pull request templates, visit GitHub’s about-issue-and-pull-request-templates help page. To create GitHub issue and/or pull request templates, please visit the creating-issue-templates-for-your-repository help page.