[Cordova Wiki] Update of "IssueWorkflow" by JoshSoref

[Apache Wiki <wi...@apache.org>]

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Cordova Wiki" for change notification.

The "IssueWorkflow" page has been changed by JoshSoref:
https://wiki.apache.org/cordova/IssueWorkflow

Comment:
Move Issue content from ContributorWorkflow

New page:
== Issue Workflow ==
=== Identifying a problem ===
 1. You've run into a problem.
 1. The first thing you should do is [[https://issues.apache.org/jira/issues/?jql=project%20%3D%20CB%20AND%20issuetype%20%3D%20Bug%20AND%20resolution%20%3D%20Unresolved%20AND%20status%20%3D%20Open%20ORDER%20BY%20priority%20DESC|search Jira]].
 1. If you find a matching issue, great, remember the CB-xxxx bit.
 1. If you don't, click "Create Issue", the project should be prefilled as Cordova, you'll select "Bug" as the issue type.
 1. Consider that you've decided to work on ticket # CB-1234 for the cordova-x repository. You are charged with updating some documentation.

=== Updating Jira ===
 * Committers will be emailed whenever an issue is created.
 * They will often be updated when someone has looked at it for the first time.
 * If you want to be able to update JIRA issues, you need to ask for permissions to do so on the [[http://cordova.apache.org/#mailing-list|mailing-list]]. You don't need to be a committer to get JIRA access.
 * An issue having an assignee indicates that a person intends to work on it.
 * If you want to work on an issue that's assigned to someone else and it hasn't been worked on in the past week, please feel free to take it.
 * If it has been worked on in the last week, then you should add a comment to the issue stating your intention. You can work on it, but in this case, it's probably a good idea to try to talk to the person.
 * When a patch has been merged into the apache repository, the apache committer who did the merge will fill in the `version fixed` field appropriately.
 * The version field is essentially obsolete due to the multi-repo multi-version world -- so you can generally ignore it. If a bug actually does map to a cadence release (e.g. 3.1.0), feel free to fill it in.
 * You can resolve an issue as Not Fixed -- ''''It's unclear what this means''''.
 * You can resolve an issue as Duplicate.

=== Providing patches ===
There are a couple of ways to provide a patch:
 * You can upload patches to Jira via `git format-patch`
 * You could paste a diff to Jira (you won't get authorship if you do this)
 * You can send a pull request to the [[https://github.com/search?q=%40apache+cordova|github.com/apache/cordova]]-* repository

== Git Workflow ==
=== Setting up your repository ===
If you already have a git repository for the area where you'll be doing work, great, you can skip this step.
The following commands will give you two remotes: origin (apache) and github (your repository). Replace `you` with your github.com account name in the following commands:
{{{
$ git clone https://git-wip-us.apache.org/repos/asf/cordova-docs.git
$ git remote add github https://github.com/you/cordova-docs.git
}}}
=== Update your master branch ===
You'll want to update from upstream to make sure you're working on the latest code. Work starts from the master branch.

{{{
$ git fetch origin
$ git checkout master
}}}

=== Create a topic branch ===
Let's create a new branch based off of master and call it "CB-1234".

{{{
$ git checkout master
$ git checkout -b CB-1234
$ git branch
  master
* CB-1234
}}}
You can name the topic branch anything, but it makes sense to name it after the ticket. This topic branch is now isolated and branched off the history of your master branch.

=== Make File Changes ===
Let's update the accelerometer documentation for the "watchPosition" function.

As it happens, the docs repository is organized with a top level `docs` directory. Inside the `docs` directory is a folder for each language, the canonical language is English (`en`). Inside each language are folders, one for each released version of Cordova, and an `edge` folder for the next version of Cordova. API documentation is inside that directory in a directory named `cordova` (there's also a Guide for how to use Cordova in the `guide` directory). Inside the API directory, documentation is organized by plugin, the accelerometer is part of the geolocation plugin and is thus in the `geolocation` directory. At the next directory, there's a class document `geolocation.md` (similarly named in the other directories according to their respective directory names) and documents for each method `geolocation.watchPosition.md` (with the second part of the file varying according to the respective method).

Thus, we're going to want to work on `docs/en/edge/cordova/geolocation/geolocation.md`. Specifically, we're going to announce that this API is now available on the HailOS platform. Typically you'd perform some more meaningful change to a file, and you'd use an editor for that. (For this change, you can expect feedback to complain that the insertion should be sorted alphabetically, but it's just a demo, unless we want to include that in a later section.)

{{{
$ perl -pi -e 's/(- Android)/\1\n- HailOS/' docs/en/edge/cordova/geolocation/geolocation.watchPosition.md
$ git status
# On branch master
# Changes not staged for commit:
#   (use "git add <file>..." to update what will be committed)
#   (use "git checkout -- <file>..." to discard changes in working directory)
#
#	modified:   docs/en/edge/cordova/geolocation/geolocation.watchPosition.md
#
no changes added to commit (use "git add" and/or "git commit -a")
}}}
git status shows that you have modified one file.

=== Commit the File Changes ===
git add will stage the file changes. You can then commit the staged file(s) with git commit. This is the standard  process to make changes to a git repository: stage, then commit.

{{{
$ git add docs/en/edge/cordova/geolocation/geolocation.watchPosition.md
$ git status
# On branch master
# Changes to be committed:
#   (use "git reset HEAD <file>..." to unstage)
#
#	modified:   docs/en/edge/cordova/geolocation/geolocation.watchPosition.md
#
$ git commit -m "CB-1234 geolocation.watchPosition works @HailOS

- HailOS support for geolocation.watchPosition was added to Cordova a year ago,
  this just updates the documentation to reflect that."
[detached HEAD bb95c71] [CB-1234] geolocation.watchPosition works @HailOS
 1 file changed, 1 insertion(+)
}}}
==== About Commit Messages ====
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 repo) assume that the first line is top-level summary that is 50 characters or less. Thus there will be highlighting and truncating of the commit message using these assumptions, and it will look weird if these assumptions are not kept. And there should be a blank line between the summary and any further detailed body. For example, here is a good example of a commit message:

{{{
CB-1234 Fixed the whizbang widget

- added more sanity checking in the build script.
- fixed the API to return the correct value in the scenario where there
  aren't any whizbangs present.
- corrected the documentation.

As an alternate to a bullet list, you could put long text here in
paragraph form, with each line wrapped at 72 chars and blank lines
between paragraphs.
}}}
Note that the first line does two things: (1) it is less than 50 characters. Subsequent lines after the first may exceed 50 characters. (2) it references a Jira issue by its id (CB-1234). Commonly, there should be a Jira issue open for defects and new features, and it is good practice for commits to point to the Jira issue they are addressing. And vice versa, you should add a comment to the Jira issue referencing the commit id(s) that contain your work. By adding the Jira number to the front of the commit message, you can take care of both in one step: there will be an [[http://www.apache.org/dev/svngit2jira.html|automatic comment]] added to the Jira item with the commit id, and of course the Jira item id will be in the git commit message.

Additionally, if your commit is to the {{{cordova-js}}} repository, then you are encouraged to add a prefix to the first line of your commit message that identifies which platform the change is for, as multiple platforms use this repository. This helps make it clear which platform authors should take interest in this commit. Here are 2 examples:

{{{
CB-2345 android: Improved exec bridge by using strings instead of JSON
CB-3456 all: Fixed plugin loading paths that start with /.
}}}

Long commit messages are not necessary, especially if there is a reference to a Jira item. More good advice on this topic is in the [[http://git-scm.com/book/ch5-2.html#Commit-Guidelines|Git book]].

=== Test Your Changes ===
The contributor is responsible to test their changes and correct any problems with their changes before a pull request is submitted. The testing includes both verifying the function they added/touched, plus running the test suites to verify there are no regressions.

When we say "run the test suites" this includes all automated tests in mobile-spec, manual tests in mobile-spec that might be affected by the change, and any platform-specific unit tests (i.e., cordova-android/test, cordova-ios/CordovaLibTests, cordova-js jake test, cordova-plugman npm test, etc.)

It is recommended that you 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 your change. It is also recommended that where reasonably feasible, you add automated tests to validate your change and catch any future regressions.

If you are writing documentation (i.e., cordova-docs), then be aware of the [[https://github.com/apache/cordova-docs/blob/master/STYLESHEET.md|style guidelines]].

=== Commit More File Changes ===
{{{
$ myeditor accelerometer/watchPosition.md
$ git commit -a
}}}
=== Prepare to Send Pull Request ===
Before sending the pull request, you should ensure that your changes merge cleanly with the main documentation repository, and that the granularity of your commits make sense.

{{{
$ git checkout master
$ git pull apache master
$ git checkout CB-1234
$ git rebase master -i
}}}
The rebase -i step allows you to re-order or combine commits. This can help to make your commits more readable.

You can do this by pulling the latest changes from the main repository back into our master. We make sure that our master is always in sync before issuing pull requests. Next, we rebase the history of the master branch onto the topic branch ticket_11. Essentially, this will rewind your divergent commits, fast-forward your topic branch to the latest commit of the master, and then re-apply your topic branch commits in order. Ensures a clean application of code changes. The [[http://book.git-scm.com/4_rebasing.html|git community book has an excellent chapter on rebasing]].

Alternatively, you can use git merge master instead of git rebase master, but your topic branches history may not be as clean.

Last thing is to make your code changes available from your fork.

{{{
$ git checkout CB-1234
$ git push origin CB-1234
}}}
== Sharing your Changes ==
By pushing your topic branch onto your fork, a cordova-x committer can review and merge your topic branch into the main repository.

=== Sending a Pull Request from GitHub ===
Pull requests sent to the [[http://github.com/apache|Apache GitHub repositories]] are used to take contributions.

 * Open a web browser to your GitHub account's cordova-x fork.
 * Select your topic branch so that the pull request references the topic branch.
 * Click the Pull Request button.