Issue Workflow

Identifying a problem

  1. You've run into a problem.
  2. The first thing you should do is search Jira.

  3. If you find a matching issue, great, remember the CB-xxxx bit.
  4. If you don't, click Create Issue, the project should be prefilled as Cordova, you'll select "Bug" as the issue type.

  5. 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

Providing Patches

There are a couple of ways to provide a patch:

Please note that patches for plugins should be made against their dev branch instead of their master branch.

Git Workflow

See also GitCommands

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.

Debugging

For chasing down problems, see NodeInspector.

Make File Changes

There is a Style Guide containing coding conventions...

Let's update the accelerometer documentation for the "watchPosition" function.

The docs repository is organized with:

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).

re: Jira issue references:

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 Git book.

Please do not use square brackets in a commit message. If the commit is used in a pull request, the merging of the pull request will strip out the square brackets and their contents from the commit message, which is probably not what you want.

Test Your Changes

The contributor is responsible for testing their changes and correcting any problems with their changes before submitting a pull request. Testing includes both verifying the functionality added/touched, and plus running the test suites to verify there are no regressions.

When we say "run the test suites" this includes:

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 your change. Please where reasonably feasible add automated tests to validate your change and catch any future regressions.

Documentation

If you are writing documentation (i.e., cordova-docs), then be aware of the 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 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 Apache GitHub repositories are used to take contributions.

More Info

For more information about Git, see GitWorkflow

Things to keep in mind

  1. If you want to solve existing issues, look for jira issues that are 'Open' and not 'In Progress'. This indicates someone is not already working on it. Either comment on the issue or bring it up on the mailing list that you wish to try to work on the issue.
  2. When you want to create a new issue, make sure you check whether similar issues already exist or not. This will avoid duplicates.
  3. After creating a new jira issue, if you want to assign that issue to yourself and were unable to do so, don't worry, send a mail to dev@cordova.apache.org and it will be assigned. Assigning ownership in jira requires an additional privilege level.

  4. Whenever you are in doubt, feel free to ask on the mailing list about where to help out and how to go about doing it. Contributors are welcome here!
  5. Your pull requests should be handled according to ProcessingPullRequests in the CommitterWorkflow.

IssueWorkflow (last edited 2014-02-01 16:07:58 by BasBosman)