You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cordova.apache.org by ja...@apache.org on 2018/12/05 12:55:02 UTC

[cordova-contribute] branch master updated: GitHub Templates: Issue Templates and Pull Request Template (#3)

This is an automated email from the ASF dual-hosted git repository.

janpio pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/cordova-contribute.git


The following commit(s) were added to refs/heads/master by this push:
     new fd87cea  GitHub Templates: Issue Templates and Pull Request Template (#3)
fd87cea is described below

commit fd87cea623b54bbc8c2387146181e3dbd70d21f6
Author: Jan Piotrowski <pi...@gmail.com>
AuthorDate: Wed Dec 5 13:54:57 2018 +0100

    GitHub Templates: Issue Templates and Pull Request Template (#3)
    
    This PR adds documentation on GitHub Templates and adds suggested templates.
    
    Its content is the result of this discussion on the mailing list: https://lists.apache.org/thread.html/fe1d0c812b24826bec74ff07e487806a3b5ad8aa1ae882c0294cb6bd@%3Cdev.cordova.apache.org%3E
    
    You can try the issue templates at this repository:
    https://github.com/janpio/cordova-github-templates/issues/new/choose
    https://github.com/janpio/cordova-github-templates/issues/new
    (Pull Request template unfortunately is not that easy, you have to look at the source here)
    
    I don't expect the templates I wrote to match all situations and survive contact with actual users - so please make suggestion on what is missing, could be improved, changed and so on.
    
    Note that whatever we merge here will not be final and those are just text files that will be able to be edited at any time. This is just the starting point.
    
    ---
    
    The section "Distribute GitHub Templates to all repositories" is currently just a TODO, we will have to find a solution for that problem later and describe it via another PR.
    
    ---
    
    Please feel free to nitpick any language and grammar problems - I rewrote this quite often, so it is very possible there are some "organically grown" sentences that could use some polishing.
---
 .github/ISSUE_TEMPLATE.md                  | 38 ++++++++++++++++++++
 .github/ISSUE_TEMPLATE/BUG_REPORT.md       | 38 ++++++++++++++++++++
 .github/ISSUE_TEMPLATE/FEATURE_REQUEST.md  | 19 ++++++++++
 .github/ISSUE_TEMPLATE/SUPPORT_QUESTION.md | 21 +++++++++++
 .github/PULL_REQUEST_TEMPLATE.md           | 29 +++++++++++++++
 README.md                                  |  1 +
 github-templates.md                        | 57 ++++++++++++++++++++++++++++++
 7 files changed, 203 insertions(+)

diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md
new file mode 100644
index 0000000..37ea445
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE.md
@@ -0,0 +1,38 @@
+<!--
+Please have a look at the issue templates you get when you click "New issue" in the GitHub UI.
+We very much prefer issues created by using one of these templates.
+-->
+
+### Issue Type
+<!-- Please check the boxes by putting an x in the [ ] like so: [x] -->
+
+- [ ] Bug Report
+- [ ] Feature Request
+- [ ] Support Question
+
+## Description
+
+## Information
+<!-- Include all relevant information that might help understand and reproduce the problem -->
+
+### Command or Code
+<!-- What command or code is needed to reproduce the problem? -->
+
+### Environment, Platform, Device
+<!-- In what environment, on what platform or on which device are you experiencing the issue? -->
+
+### Version information
+<!-- 
+What are relevant versions you are using?
+For example:
+Cordova: Cordova CLI, Cordova Platforms, Cordova Plugins 
+Other Frameworks: Ionic Framework and CLI version
+Operating System, Android Studio, Xcode etc.
+-->
+
+## Checklist
+<!-- Please check the boxes by putting an x in the [ ] like so: [x] -->
+
+- [ ] I searched for existing GitHub issues
+- [ ] I updated all Cordova tooling to most recent version
+- [ ] I included all the necessary information above
diff --git a/.github/ISSUE_TEMPLATE/BUG_REPORT.md b/.github/ISSUE_TEMPLATE/BUG_REPORT.md
new file mode 100644
index 0000000..0fc99aa
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/BUG_REPORT.md
@@ -0,0 +1,38 @@
+---
+name: πŸ› Bug Report
+about: If something isn't working as expected.
+
+---
+
+# Bug Report
+
+## Problem
+
+### What is expected to happen?
+
+### What does actually happen?
+
+## Information
+<!-- Include all relevant information that might help understand and reproduce the problem -->
+
+### Command or Code
+<!-- What command or code is needed to reproduce the problem? -->
+
+### Environment, Platform, Device
+<!-- In what environment, on what platform or on which device are you experiencing the issue? -->
+
+### Version information
+<!-- 
+What are relevant versions you are using?
+For example:
+Cordova: Cordova CLI, Cordova Platforms, Cordova Plugins 
+Other Frameworks: Ionic Framework and CLI version
+Operating System, Android Studio, Xcode etc.
+-->
+
+## Checklist
+<!-- Please check the boxes by putting an x in the [ ] like so: [x] -->
+
+- [ ] I searched for existing GitHub issues
+- [ ] I updated all Cordova tooling to most recent version
+- [ ] I included all the necessary information above
diff --git a/.github/ISSUE_TEMPLATE/FEATURE_REQUEST.md b/.github/ISSUE_TEMPLATE/FEATURE_REQUEST.md
new file mode 100644
index 0000000..cabb35f
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/FEATURE_REQUEST.md
@@ -0,0 +1,19 @@
+---
+name: πŸš€ Feature Request
+about: A suggestion for a new functionality
+
+---
+
+# Feature Request
+
+## Motivation Behind Feature
+<!-- Why should this feature be implemented? What problem does it solve? -->
+
+## Feature Description
+<!-- Describe your feature request in detail -->
+<!-- Please provide any code examples or screenshots of what this feature would look like -->
+<!-- Are there any drawbacks? Will this break anything for existing users? -->
+
+## Alternatives or Workarounds
+<!-- Describe alternatives or workarounds you are currently using -->
+<!-- Are there ways to do this with existing functionality? -->
diff --git a/.github/ISSUE_TEMPLATE/SUPPORT_QUESTION.md b/.github/ISSUE_TEMPLATE/SUPPORT_QUESTION.md
new file mode 100644
index 0000000..cf665b3
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/SUPPORT_QUESTION.md
@@ -0,0 +1,21 @@
+---
+name: πŸ’¬ Support Question
+about: If you have a question, please check out our Slack or StackOverflow!
+
+---
+
+<!------------^ Click "Preview" for a nicer view! -->
+
+Apache Cordova uses GitHub Issues as a feature request and bug tracker _only_.
+For usage and support questions, please check out the resources below. Thanks!
+
+---
+
+* Slack Community Chat: https://cordova.slack.com (you can sign-up at http://slack.cordova.io/)
+* StackOverflow: https://stackoverflow.com/questions/tagged/cordova using the tag `cordova`
+
+If you are using a tools that uses Cordova, like e.g. Ionic, check their support channels:
+
+* Ionic Framework
+  * [Ionic Community Forum](https://forum.ionicframework.com/)
+  * [Ionic Worldwide Slack](https://ionicworldwide.herokuapp.com/)
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
new file mode 100644
index 0000000..3a9a89d
--- /dev/null
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -0,0 +1,29 @@
+<!--
+Please make sure the checklist boxes are all checked before submitting the PR. The checklist
+is intended as a quick reference, for complete details please see our Contributor Guidelines:
+
+http://cordova.apache.org/contribute/contribute_guidelines.html
+
+Thanks!
+-->
+
+### Platforms affected
+
+
+### Motivation and Context
+<!-- Why is this change required? What problem does it solve? -->
+<!-- If it fixes an open issue, please link to the issue here. -->
+
+### Description
+<!-- Describe your changes in detail -->
+
+### Testing
+<!-- Please describe in detail how you tested your changes. -->
+
+### Checklist
+
+- [ ] I've run the tests to see all new and existing tests pass
+- [ ] I added automated test coverage as appropriate for this change.
+- [ ] Commit is prefixed with `(platform)` if this change only applies to one platform (e.g. `(android)`)
+- [ ] If this Pull Request resolves an issue, I linked to the issue in the text above (and used the correct [keyword to close issues using keywords](https://help.github.com/articles/closing-issues-using-keywords/))
+- [ ] I've updated the documentation if necessary.
diff --git a/README.md b/README.md
index 4d6f8f8..9383b17 100644
--- a/README.md
+++ b/README.md
@@ -12,3 +12,4 @@ This repository contains documents describing everything a contributor of Apache
 
 - [Deprecation and Archiving of Repositories](deprecation.md)
 - [GitHub Labels](github-labels.md)
+- [GitHub Templates](github-templates.md)
diff --git a/github-templates.md b/github-templates.md
new file mode 100644
index 0000000..ddd37c3
--- /dev/null
+++ b/github-templates.md
@@ -0,0 +1,57 @@
+# GitHub Templates
+
+GitHub supports templates that are pre-populated into the description input field of a newly opened Issues and Pull Requests. Apache Cordova uses both options.
+
+## Issue Templates
+
+The job of an issue template is to make sure, the creator includes all necessary information in an issue they open. It can also supply information to the reporter like text or links that are relevant before opening an issue.
+
+Apache Cordova uses [GitHub's multiple issues template functionality](https://help.github.com/articles/about-issue-and-pull-request-templates/), which
+lets users choose what type of issue they want to create:
+
+Note: You can "test" and preview these issue templates by [creating an issue](/issues) in this repository.
+
+### Bug Report
+
+Collect all necessary information to understand if this is an actual bug or just a user problem. The information collected should enable the Apache Cordova community to reproduce and resolve the problem.
+
+See [`.github/ISSUE_TEMPLATE/BUG_REPORT.md`](.github/ISSUE_TEMPLATE/BUG_REPORT.md) for our current bug report template.
+
+### Feature Request
+
+What new feature is being requested and what problem does it solve?
+
+See [`.github/ISSUE_TEMPLATE/FEATURE_REQUEST.md`](.github/ISSUE_TEMPLATE/FEATURE_REQUEST.md) for our current feature request template.
+
+### Support Question
+
+People having problems with using one of Apache Cordova's components tend to also create issues. Apache Cordova unfortunately does not have the community to handle that volume of issues. Because of that, this template mainly refer people to the proper, more suited support channels:
+
+- Stack Overflow
+- Slack
+- Framework channels (like e.g. Ionic Forum)
+
+**Note that Apache Cordova will close support questions if they are submitted to the repository anyway.**
+
+See [`.github/ISSUE_TEMPLATE/SUPPORT_QUESTION.md`](.github/ISSUE_TEMPLATE/SUPPORT_QUESTION.md) for our current support question template.
+
+### Fallback
+
+Users can still ignore the specific issue templates by going to the `/issues/new` URL directly or use the "Don’t see your issue here? Open a regular issue." link below the template selection. This template provides the fallback for this case.
+
+See [`.github/ISSUE_TEMPLATE.md`](.github/ISSUE_TEMPLATE.md) for our current fallback issues template.
+
+## Pull Request Template
+
+Similar to an [Issue Template](#issue-template), the Pull Request template ensures that new Pull Requests include all necessary information. It is also used to nudge contributors to run tests, write documentation etc.
+
+See [`.github/PULL_REQUEST_TEMPLATE.md`](.github/PULL_REQUEST_TEMPLATE.md) for our current pull request template.
+
+## Distribute GitHub Templates to all repositories
+
+TODO
+<!--
+How can changes to these templates be distributed simply to all our (many) repositories?
+Maybe a shell script that copies to locally checked out repositories, then commits and pushes to all of them?
+cordova-coho maybe already does something like this?
+-->


---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@cordova.apache.org
For additional commands, e-mail: commits-help@cordova.apache.org