This is an automated email from the ASF dual-hosted git repository.
shazron pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/cordova-docs.git
The following commit(s) were added to refs/heads/master by this push:
new 8327a0d GH-822: Update contribution docs for GitHub issues (#823)
8327a0d is described below
commit 8327a0d03254f3ff07d6fe59d3678d5a19937e1e
Author: Gearóid <mena...@users.noreply.github.com>
AuthorDate: Mon May 28 17:46:18 2018 +0900
GH-822: Update contribution docs for GitHub issues (#823)
- Rewrite the contribution and issue guidelines to reflect the move to
GitHub issues
- Add a basic issue template, as cordova-docs is the first repo to use
GitHub issues
- Update the pull request template to tell the user to create an issue on
GitHub
---
.github/ISSUE_TEMPLATE.md | 25 +++++++++++++++++++++++++
.github/PULL_REQUEST_TEMPLATE.md | 3 +--
www/contribute/contribute_guidelines.md | 29 +++++++++++++++++------------
www/contribute/issues.md | 21 ++++++++++++++++++---
4 files changed, 61 insertions(+), 17 deletions(-)
diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md
new file mode 100644
index 0000000..af5f515
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE.md
@@ -0,0 +1,25 @@
+<!--
+Before creating an issue, please take a look at
http://cordova.apache.org/contribute/contribute_guidelines.html, and ensure you
are creating your issue in the correct repository.
+
+Please only report issues with the website and documentation here. Fill out
the template below with as much detail as possible to help us to solve your
issue.
+-->
+
+**Issue Type**
+[ ] Bug
+[ ] Feature Request
+
+**Priority**
+[ ] Minor <!-- very specific or only affects a few people -->
+[ ] Major <!-- important and impacts many people -->
+[ ] Critical <!-- Bugs (not features) that block the main function of a
component and affect a large number of people -->
+[ ] Blocker <!-- Catastrophic bugs that prevent projects from building or
cause basic projects to crash immediately -->
+
+**Environment**
+* OS:
+* Browser:
+
+**Description**
+<!--
+If this is a bug, outline how to reproduce it as clearly as possible.
+If this is a feature request, describe in detail how it would work.
+-->
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index 91582f4..fcb21db 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -17,6 +17,5 @@ Thanks!
### Checklist
-- [ ] [Reported an issue](http://cordova.apache.org/contribute/issues.html) in
the JIRA database
-- [ ] Commit message follows the format: "CB-3232: (android) Fix bug with
resolving file paths", where CB-xxxx is the JIRA ID & "android" is the platform
affected.
+- [ ] Commit message follows the format: "GH-3232: (android) Fix bug with
resolving file paths", where GH-xxxx is the GitHub issue ID & "android" is the
platform affected.
- [ ] Added automated test coverage as appropriate for this change.
diff --git a/www/contribute/contribute_guidelines.md
b/www/contribute/contribute_guidelines.md
index ce4a2c4..d07c84f 100644
--- a/www/contribute/contribute_guidelines.md
+++ b/www/contribute/contribute_guidelines.md
@@ -5,7 +5,7 @@ title: Apache Cordova Contribute Guidelines
# Contributor Guidelines
-Thanks for helping to improve Cordova! This page provides a general guide on
making contributions to Cordova. If you can't find something on this page,
please feel free to contact the [dev mailing
list](http://cordova.apache.org/contact) or ask questions on the Cordova Slack.
+Thanks for helping to improve Cordova! This page provides a general guide on
making contributions to Cordova. If you can't find something on this page,
please feel free to contact the [dev mailing
list](http://cordova.apache.org/contact) or ask questions on the [Cordova
Slack](http://slack.cordova.io/).
## Prerequisites
@@ -14,18 +14,17 @@ Before contributing to Apache Cordova, it is recommended
that you complete the f
1. Join the [mailing list](http://cordova.apache.org/contact/) and send a
brief introduction of yourself (optional)
2. Create an [Apache
JIRA](https://issues.apache.org/jira/secure/Signup!default.jspa) account
-## Working with JIRA
-
-Issues for Apache Cordova are hosted in the Apache JIRA. All code
contributions made to Cordova should have a corresponding JIRA issue. When
reporting issues, please follow [these guidelines](./issues.html).
+## Working with Issues
+Issues for most Apache Cordova components are hosted in the [Apache
JIRA](https://issues.apache.org/jira/browse/CB). However, some components
instead have their issues on GitHub. If a repository has an _Issues_ tab on
GitHub, issues should be reported there instead of JIRA. All code contributions
made to Cordova should have a corresponding JIRA or GitHub issue. When
reporting issues, please follow [these guidelines](./issues.html).
#### Claiming Issues
-If you find a JIRA issue that you would like to work on, you can ask to claim
it; please leave a comment indicating your intention and a committer will
assign it to you. Some issues in JIRA are auto-assigned to certain
contributors. If it is clear that an issue is not being worked on, feel free to
work on it yourself (but please comment first to let the assignee know). If you
are looking for a place to start, try searching the [issues labelled
easyfix](https://issues.apache.org/jira/issu [...]
+If you find an issue that you would like to work on, you can ask to claim it;
please leave a comment indicating your intention and a committer will assign it
to you. Some issues in JIRA are auto-assigned to certain contributors. If it is
clear that an issue is not being worked on, feel free to work on it yourself
(but please comment first to let the assignee know). If you are looking for a
place to start, try searching the [issues labelled easyfix in
JIRA](https://issues.apache.org/jira/ [...]
## Submitting Code
-For all submitted code, there must be a corresponding issue in JIRA. If there
isn't an existing issue, please create one. You can submit code using one of
the following methods:
+You can submit code using one of the following methods:
* Submit a pull request at one of the Apache Github mirrors at
`github.com/apache/<repo name>` (**Strongly Preferred**)
* Upload patches created with `git format-patch` to the JIRA issue
@@ -35,19 +34,19 @@ For all submitted code, there must be a corresponding issue
in JIRA. If there is
The workflow for creating pull requests on Github generally follows these
steps:
-1. [Open a JIRA issue](./issues.html) if one has not already been created
+1. [Open an issue](./issues.html) if one has not already been created
(optional if the repository's issues are on GitHub instead of JIRA)
2. [Create a local fork](https://help.github.com/articles/fork-a-repo/) of the
appropriate Apache repository
-3. In your local fork, create a branch dedicated to the JIRA issue you are
working on
+3. In your local fork, create a branch dedicated to the issue you are working
on
4. Push your commits to this branch
5.
[Squash](http://www.git-scm.com/book/en/v2/Git-Tools-Rewriting-History#Squashing-Commits)
these commits into one single commit (see the section below regarding commit
messages)
6. [Create a pull
request](https://help.github.com/articles/using-pull-requests/) on the Apache
repository
7. Ask for code review
-Please include the JIRA id in the title of any pull requests made to Github.
The Apache Git bot will link the PR and the JIRA issue automatically. For more
help on Git, see the [Git documentation](http://git-scm.com/doc)
+Please include the issue id in the title of any pull requests made to Github.
The Apache Git bot will link a PR and the JIRA issue automatically if it finds
a JIRA issue ID in the commit message. For more help on Git, see the [Git
documentation](http://git-scm.com/doc).
#### Code review
-However you submit code, you should always call out a reviewer to look at and
merge your code. A good place to find a reviewer is [the component
list](https://issues.apache.org/jira/browse/CB/?selectedTab=com.atlassian.jira.jira-projects-plugin:components-panel)
or you can send a mail out to the [dev mailing
list](http://cordova.apache.org/contact) with a link to the pull request.
+However you submit code, you should always call out a reviewer to look at and
merge your code. A good place to find a reviewer is [the component list on
JIRA](https://issues.apache.org/jira/browse/CB/?selectedTab=com.atlassian.jira.jira-projects-plugin:components-panel)
or you can send a mail out to the [dev mailing
list](http://cordova.apache.org/contact) with a link to the pull request.
## Testing your code
@@ -63,7 +62,7 @@ When we say "run the test suites" this includes:
* `cordova-js: jake test`
* `cordova-plugman: npm test`
-Please add a comment in Jira about what testing you did with your change so a
committer can understand what testing was done before they merge it in.
+Please add a comment in the issue about what testing you did with your change
so a committer can understand what testing was done before they merge it in.
#### Adding tests
@@ -71,12 +70,18 @@ If possible, please include tests that validate your
changes and catch any futur
## Git Commit Messages
-When contributing, please have your commit messages begin with the JIRA id and
relevant platform (if appropriate) followed by a description of the commit.
Here are two examples:
+When contributing, please have your commit messages begin with the the issue
id (if there is one) and relevant platform (if appropriate) followed by a
description of the commit. Here are two examples for JIRA tickets:
```
CB-2345 android: Improved exec bridge by using strings instead of JSON
CB-3456 all: Fixed plugin loading paths that start with /
```
+If you created an issue on GitHub, the issue number starts with `GH` instead
of `CB`:
+```
+GH-2345 android: Improved exec bridge by using strings instead of JSON
+GH-3456 all: Fixed plugin loading paths that start with /
+```
+
You are highly encouraged to describe your git commit with enough detail for
someone else to understand it. In doing so, your commit message can consist of
multiple lines. However, it also is highly encouraged that the first line of
your commit message not exceed 50 characters. This is because some of the
tooling that sits on top of git (such as the httpd apps that let you browse the
repos) assumes that the first line is top-level summary that is 50 characters
or less. Thus there will be [...]
```
diff --git a/www/contribute/issues.md b/www/contribute/issues.md
index 1ed1737..f8adc5f 100644
--- a/www/contribute/issues.md
+++ b/www/contribute/issues.md
@@ -5,11 +5,26 @@ title: Apache Cordova Reporting Issues
# Reporting Issues
-Thank you for helping to improve Cordova! Issues for Apache Cordova are hosted
at the Apache [JIRA](https://issues.apache.org/jira/browse/CB). A JIRA account
is required before you can submit issues (you can easily [create one
here](https://issues.apache.org/jira/secure/Signup!default.jspa)). Before
submitting an issue, please take a moment to search JIRA to see if an issue
already exists. If it does, please consider commenting or voting for the issue
to help raise its visibility.
+Thank you for helping to improve Cordova! Most issues for Apache Cordova are
currently hosted at the [Apache
JIRA](https://issues.apache.org/jira/browse/CB). However, we are starting to
move issue management to GitHub.
+## Should I report an issue on JIRA or GitHub?
+If the repository you are reporting an issue for has an _Issues_ tab on
GitHub, please report it there. Otherwise report it on JIRA.
+
+## Creating an issue on GitHub
+
+Find the repository of the component which your issue applies to. To figure
out which repository to report your issue to, you can take a look at the [full
list of Cordova repositories](https://github.com/apache?q=cordova). Some of the
most popular repositories are:
+
+* [cordova-android](https://github.com/apache/cordova-android): core Android
functionality
+* [cordova-ios](https://github.com/apache/cordova-ios): core iOS functionality
+* [cordova-cli](https://github.com/apache/cordova-cli): command-line tool (the
`cordova` command)
+* [cordova-docs](https://github.com/apache/cordova-docs): the Cordova website
and documentation
+
+Once you have found the correct repository to create your issue in, go to the
_Issues_ tab, and click _New issue_. Simply fill out the issue template, and
submit your issue. If there is no _Issues_ tab, please report the issue on JIRA
instead.
## Creating an issue in JIRA
+A JIRA account is required before you can submit issues (you can easily
[create one here](https://issues.apache.org/jira/secure/Signup!default.jspa)).
Before submitting an issue, please take a moment to search JIRA to see if an
issue already exists. If it does, please consider commenting or voting for the
issue to help raise its visibility.
+
Once you have created an account and logged in, click the blue "Create" button
at the top of the [Cordova JIRA](https://issues.apache.org/jira/browse/CB) page
to create an issue. In the dialog that appears, please fill out the following
fields _to the best of your ability_. All fields besides those listed here can
be left blank.
Field | Description
@@ -24,7 +39,7 @@ Description | A thorough description of the issue. For
bugs, please provide
Labels | Please label your issue with the platform it affects (e.g.
ios, windows, android, etc.). Include other relevant labels such as regression,
easyfix, bug, dev, staging, production, discussion, question, security, legal,
enhancement, production, and/or feature.
Priority | The impact of the issue (see below)
-## Issue Priority
+# Issue Priority
We gauge issue priority on the following scale:
* **Minor/Trivial:** The feature or bug is very specific or only affects a few
people
@@ -34,7 +49,7 @@ We gauge issue priority on the following scale:
If you aren't sure about the priority, leave the default (major) selected.
Please be aware that as our contributors triage issues, they may change the
priority based on our criteria.
-## Finding out versions
+# Finding out versions
You can quickly find out versions of platforms/plugins you're using by running:
--
To stop receiving notification emails like this one, please contact
shaz...@apache.org.
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscr...@cordova.apache.org
For additional commands, e-mail: commits-h...@cordova.apache.org
