Github enables using templates in order to customize and standardize the information contributors include when they open issues and pull requests in the repository. The proposed set of templates is adjusted to be applicable mainly to CAMARA API specification subprojects.
GitHub uses templates for the repository if the respective template configuration files are placed in any of the following places:
- the root of the repository
- the
.github
folder - the
docs
folder
In order to use templates for issues and pull request for the CAMARA Subproject the following steps need to be taken:
-
Copy the folder .github to the root of Subproject repository.
-
Edit the
config.yml
file inside.github/ISSUE_TEMPLATE/
folder:
- to allow creating blank issues (without template) set:
blank_issues_enabled: true
- Edit or add external links using the following structure in
contact_links:
array:
- name: Subproject discussions
url: https://github.com/camaraproject/Commonalities/discussions
about: Please ask and answer questions here.
- Modify Issue and PR templates in Markdown files included in the
.github
folder if needed.
- Issue templates include headers, where the name and descripttion of issue category, the suggested title of the issue, the labels and assigness for the issue can be configured, e.g.
---
name: Bug
about: Describe the bug in Provider Implementation
title: ''
labels: 'implementation:bug'
assignees: ''
---
Templates are automatically imported when creating new issue or PR via Github web interface.
Github allows to multiple templates to be used for creating issues. The screenshot below presents available options with proposed set of templates and configs:
Note, that Report a security vulnerability option is added by Github and opening blank issues is enabled. Preconfigured external links (here: Subproject discussions, CAMARA API Design Guidelines) will be opened in new tab of the browser.
The proposed issue categories are prepared with Github labels:
Category | Description | Labels |
---|---|---|
Bug | Describing bugs in Provider Implementations | implementation:bug |
Correction | Suggesting corrections of API specification or indicating misalignment with API design guidelines | correction |
Documentation | Indicating issues with API documentation or supplementary documents | documentation |
Enhancement | Suggesting ideas for new API features or questions on directions for API evolution | enhancement |
Subproject management | Indicating issues with subproject repository or release management process | subproject management |
Tests | Indicating issues with API tests | tests |
Pull request template is based on the template use in Kubernetes project
It requires to indicate kind of PR as one of:
- bug
- correction
- enhancement/feature
- cleanup
- documentation
- subproject management
- tests
The proposed above values correspond to issue categories, with additional type: cleanup for simple correction of typos/spelling mistakes or application of guidelines.
After describing what the PR does, the link to relevant issue should be added.
Thanks to Github keywords: Fixes #<issue number>
, or Fixes (paste link of issue)
pull request is linked to relevant issue to show that a fix is in progress and to automatically close the issue when the pull request is merged.
The pull request template includes the place to input a clear, concise description of the change that will facilitate creation of the Release Notes.
Github templates documentation