Skip to content

Instantly share code, notes, and snippets.

@coisa

coisa/ISSUE_TEMPLATE.md

Created June 5, 2023 20:29
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save coisa/ae251b23282ca01ae7ceebd1ea1be432 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save coisa/ae251b23282ca01ae7ceebd1ea1be432 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
ISSUE_TEMPLATE.md

Description

Describe the task in a concise and cohesive manner.

Rather than dictating how a task should be accomplished, the description should focus on the expected outcome.

Motivation

Explain the motivation behind the creation of this task. Why this task was needed.

Identifying the most suitable solution will be easier with these insights.

Related Tickets

The following example shows one or more tickets related to this one:

What is the current Behavior?

The purpose of this section is to briefly describe the current behavior.

In the case of a BUG, what anomalous behavior is observed? What's going on that shouldn't be happening?

The task description should clarify whether it is aimed at improving an existing process that can be improved in another way, or whether it cannot be improved using the features currently available.

Possible Causes

This section applies only to BUG tasks, and it should list possible causes of the application's incorrect behavior.

What is the Expected Behavior?

Once this task has been completed, describe the expected behavior.

What should be the behavior of a BUG as opposed to what was described previously?

When this task defines a new feature, what behavior should be observed?

Acceptance Criteria

Describe the minimum criteria for this task in a list form (example below).

  • In GitHub, you should be able to create new tasks using predefined templates;
  • A predefined Pull-Request template should be available directly in GitHub for creating a new Pull-Request;
  • There should be a respect for GitHub Flavored Markdown notation in the templates;

Steps for Validation

Describe the steps required to validate that this task complies with the previously described acceptance criteria.

The following example illustrates how to validate the task:

  • [] Go to the url http://github.com;
  • [] Click on the "New Issue" link;
  • [] Next to the "Title" field, select the task template;
  • [] Edit the description field in accordance with the selected template;

Implementation Suggestions

Describe how you suggest to accomplish this task, whether through a specific technology or by referencing a section of the application's code.

If there are multiple suggestions for resolving the problem, you may list them all.

Additional Information

Provide any additional information that may assist in resolving the issue.

Here are a few examples:

  • Operating System: Manjaro Linux 4.19.13
  • Browser: Chromium 71.0.3578.98
  • Software Version: 1.0.0
  • URI: http://gist.github.com
  • File path: .github/ISSUE_TEMPLATE/example.md

Logs

This section should be used to add logs that could assist in solving or proving a particular behavior.

Here is an example of how to add logs:

user@servername:/absolute/path/to/file.log 
Jul 14 00:08:47 INFO: My custom script info log
Jul 14 00:08:48 ERR: OH NO! Something wrong happens!

Screenshots

Include screenshots, images, or prototypes that may assist in resolving this issue.

![Screenshot 01: Image Of A Cat] (http://thecatapi.com/api/images/get?format=src&type=gif) ![Screenshot 02: Now We Have A Dog] (https://api.thedogapi.com/v1/images/search?format=src&mime_types=image/gif)

Checklist

  • [] The task title is descriptive and does not have multiple interpretations;
  • [] The template was respected, and only non-pertinent sections were removed;
  • [] Labels describing the task type and its severity have been added;
  • [] A person responsible for the task has been assigned;
Raw
PULL_REQUEST_TEMPLATE.md

Description

Briefly summarize the changes made in this Pull Request. You should explain the purpose of this Pull Request, as well as the motivation for making the changes.

Related Tickets

There should be at least one related task for every Pull Request. Consider creating a task and assigning it here if there isn't one for this Pull Request.

The following example shows how tickets should be referenced:

  • Fixes XYZ-01 (Jira)

Related Pull-Requests

In the same way, list any possible Pull Requests related to or dependent upon this one.

  • Depends on PR #1
  • Depends on user/repository#1

Merge this Pull Request only after all Pull Requests it depends on have been published or are ready to be published.

What is the current behavior?

The purpose of this topic is to describe the current behavior briefly.
Describe the behavior that the modification sent in this Pull Request aims to change. This Pull Request aims to change the behavior described in this section.

What is the expected behavior?

Explain how this Pull Request should behave after the modifications have been made.

Impact of the change

Please describe here any potential impacts of this Pull Request, positive or negative.

  • Customer Impact: Does the customer notice any change in behavior or visuals?
    If there is a need to notify the customer about the changes in this Pull Request, please describe it here.

  • Performance Impact: Will there be any positive or negative impact on the performance of this or an adjacent system?
    In the event that there are impacts, how can they be verified?

  • Adjacent Impacts: Does this Pull Request affect any systems, services, or processes? Does any system, service, or process need a new specification, validation, re-implementation, or documentation?

How can it be tested?

Provide a step-by-step description of how the proposed changes in this Pull Request can be validated.

In case the production scenario is slightly different, make sure you mention any specific settings required for the test.

Include any scripts or test cases that guarantee the proposed changes will work with the Pull Request.

  • Access the url http://github.com/user/repository/pulls;
  • Click the "New pull request" button;
  • Select the branch to merge;
  • Select the template next to the "Title" field;
  • Fill in the requested data in the template;
  • Click the "Create pull request" button;

Additional information

Provide any additional information that may assist in resolving the issue.

Here are a few examples:

  • Operating System: Manjaro Linux 4.19.13
  • Browser: Chromium 71.0.3578.98
  • Software Version: 1.0.0
  • URI: http://gist.github.com
  • File path: .github/PULL_REQUEST_TEMPLATE/example.md

Logs

This section should be used to add logs that could assist in solving or proving a particular behavior.

Here is an example of how to add logs:

user@servername:/absolute/path/to/file.log 
Jul 14 00:08:47 INFO: My custom script info log
Jul 14 00:08:48 ERR: OH NO! Something wrong happens!

Publishing dependencies

Before or after publishing changes in staging and/or production environments, if any manual action is required.

  • Copy configuration files to the /home/app/config folder
  • Execute the SQL described below in the database: UPDATE ...
  • Execute the commands described below in the environment console: ls -lash

Checklist

  • The title of this Pull Request follows the pattern: "[XYZ-01] A concise and cohesive description of the proposed change".
  • Only topics not relevant to this Pull Request were removed from the template;
  • Added labels describing the type of modification and its severity;
  • This Pull Request has been assigned to a responsible person;
  • The code I write follows PSR-12's style guide.
  • The code I wrote has been self-reviewed.
  • All hard-to-understand sections of the code are adequately commented.
  • Documentation regarding the modifications made in this Pull Request has been updated.
  • No warnings were generated as a result of the changes made.
  • Correction or implementation tests have been added that verify the feature works as intended.
  • Despite the changes, existing and new unit tests pass.
  • Merge conflicts have been adjusted and reviewed, and dependencies that have been changed have been properly merged and published.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment