Skip to content

Issue Workflow

Jump to bottom
Jan Piotrowski edited this page Sep 14, 2017 · 4 revisions

Table of Contents

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

  • 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 or own one, you need to ask for increased Jira permissions to do so on the mailing-list. You don't need to be a committer to get JIRA access or to have these increased Jira permissions.
  • 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.
  • Issues can be resolved as "Fixed", "Duplicate", "Not a Problem", etc.
  • Here is a list of what you are permitted to do in Jira, depending on your role.

Providing Patches

There are a few possible ways to provide a patch:

  • You can send a pull request to the github.com/apache/cordova-* repository. This is the preferred way. The instructions below assume this approach.
    • To ensure that your request is seen, paste the pull request link into the relevant JIRA issue, or in an email to the mailing-list.
  • 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 should always call out someone to review your changes. You can pick a reviewer from the component list.

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.

Start by getting a github.com account. Replace `you` with your github.com account name in the following commands.

Next, find the desired Apache repository on github.com (i.e., https://github.com/apache/cordova-docs.git ) and fork it so that you have your own copy of the repo on your own github.com account (i.e., https://github.com/you/cordova-docs.git ).

Run the following commands, they will give you two remotes: origin (your repository) and apache (apache):

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.

Create a topic branch

Let's create a new branch based off of master and call it "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

Each git repository has a README file with instructions specific to the content of that repository. This should be the first file you look at in the repo. It will help you get oriented, and contains any special instructions.

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

The docs repository is organized with:

  • a top level `docs` directory.
    • a folder for each language.
    • The canonical language is English (`en`).
      • one folder for each released version of Cordova.
      • `edge` folder for the next version of Cordova.
        • `guide` directory - a Guide for how to use Cordova.
        • `cordova` directory - API documentation.
          • documentation is organized by plugin, the accelerometer is part of the geolocation plugin and is thus in the `geolocation` directory.
            • Class document `geolocation.md` (similarly named in the other directories according to their respective directory names)
            • Method documents `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.)

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

About Commit Messages

You are highly encouraged to describe your 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:

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:
  • There should be a Jira issue open for defects and new features
  • Commits should point to the Jira issue they are addressing.
  • Comment in the Jira issue referencing the commit id(s) that contain your work.
  • Including the Jira number at the beginning of the commit message, you can take care of both in one step:
    • there will be an automatic comment added to the Jira item with the commit id
    • of course the Jira item id will be in the git commit message.
Additionally, if your commit is to the 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:

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:

  • all automated tests in mobile-spec,
  • manual tests in mobile-spec that might be affected by the change,
  • `npm test` for JS linting
  • any platform-specific unit tests
    • `cordova-android/test`
    • `cordova-ios/CordovaLibTests`
    • `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 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

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.

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.

The push command will prompt you for your github.com userid and password.

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.

  • 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.
  • Paste the pull request link into the relevant JIRA issue, or in an email to the mailing-list.
    • Call out someone to review your changes. You can pick a reviewer from the component list.

More Info

For more information about Git, see https://github.com/cordova/cordova-discuss/wiki/git-Workflow

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 https://github.com/apache/cordova-coho/blob/master/docs/processing-pull-requests.md in the https://github.com/apache/cordova-coho/blob/master/docs/committer-workflow.md.
Clone this wiki locally