Issue and Pull Request Templates
What is it? Why do it?
Issues and Pull Requests form the core of developer-community communication regarding identified problems/requested features and their implementation in a given software package. The main function of templates is to provide guidelines on the content of these, usually focused on ensuring a given user/developer provides enough context in a given issue/pull request (PR) for others to understand the motivation and technical details.
Issue Templates
Issue templates are highly customizable, and it’s often appropriate to have multiple available to users to promote better organization of common issue types. By default, the python-project-template provides three base templates
general-issue-template: A general issue template for issues that don’t fit into other categories.
bug-report-template: A template specific to identifying bugs within the package.
feature-request-template: A template for requesting new features of the package.
A user will be prompted to choose between these templates any time they attempt to create a new issue in the repository. You may add new templates to this list as additional common issue themes become clear in your project.
Modifying using the Github Web-Interface
Github offers native support for adding and modifying issue templates directly in it’s web-interface. This is done within the settings menu, and Github has a straightforward guide on how to access this interface, here.
Changing Template Ordering
The ordering of issue templates is controlled by alpha-numeric names of the
template files themselves. To best control ordering, it’s recommended to prefix
the template files with a number (e.g. 0-first_template.md
,
1-second_template.md
, etc.). This is also covered in it’s own section of
the github issue templating guide.
Note
The issue template files can be found in the .github/ISSUE_TEMPLATE
subdirectory of your repository.
Pull Request Template
A pull request template is used to pre-populate any submitted PRs to the
repository. By default, the python-project-template provides a single template
to the project (located at .github/pull_request_template.md
). This template
provides generic fields for:
Change Description: Prompt for overview of what the PR changes
Solution Description: Prompt for technical details of the solution
Code Quality: Checkboxes to verify that the PR adheres to the coding standards of the repository
As well as a set of additional project and issue-specific fields. This template only serves as an initial framework, and you should feel free to modify this as you see fit by directly modifying the template file.