Skip to content

Latest commit

 

History

History
101 lines (71 loc) · 4.3 KB

Issue and PR template Howto.md

File metadata and controls

101 lines (71 loc) · 4.3 KB
Raw

Using templates for Issues and Pull Request for CAMARA repositories

Introduction

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

Configuration

In order to use templates for issues and pull request for the CAMARA Subproject the following steps need to be taken:

  1. Copy the folder .github to the root of Subproject repository.

  2. 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.
  1. 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: ''
---

Usage

Templates are automatically imported when creating new issue or PR via Github web interface.

Issue templates

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

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.

References

Github templates documentation

Github keywords to link an issue and pull request

Full Emoji List