cordova-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Apache Wiki <>
Subject [Cordova Wiki] Update of "ContributorWorkflow" by JoshSoref
Date Thu, 24 Oct 2013 01:10:08 GMT
Dear Wiki user,

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

The "ContributorWorkflow" page has been changed by JoshSoref:

Extract Issue content to IssueWorkflow

   * Step - 3: Create an account in jira apache
   * Step - 4: Bookmark the following link: (this
is the official url for cordova jira issues)
   * Step - 5: Introduce yourself to the community, by giving a brief introductory mail to
+  * Step - 6: [[IssueWorkflow|Work on an issue]]
  If you have completed these steps, you are now ready to start contributing.
@@ -81, +82 @@

  === Easier for the Maintainer ===
  Maintainers like topic branches. It is easier to review the pull request and merge commits
into the main repository.
- == Issue Workflow ==
- === Identifying a problem ===
-  1. You've run into a problem.
-  1. The first thing you should do is [[|search
-  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 [[|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 [[|]]-*
- == 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 account name in the following commands:
- {{{
- $ git clone
- $ git remote add github
- }}}
- === 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 `` (similarly named in the other directories according to their
respective directory names) and documents for each method `` (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/`.
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/
- $ 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/
- #
- 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/
- $ git status
- # On branch master
- # Changes to be committed:
- #   (use "git reset HEAD <file>..." to unstage)
- #
- #	modified:   docs/en/edge/cordova/geolocation/
- #
- $ 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 [[|automatic comment]] added to
the Jira item with the commit id, and of course the Jira item id will be in the git commit
- 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
- === 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 [[|style
- === Commit More File Changes ===
- {{{
- $ myeditor accelerometer/
- $ 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.
-  * 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.
  === Getting Noticed ===
  It is strongly recommended that you sign up for the [[|mailing
list]] before issuing a pull request. If your pull request is related to an existing JIRA
issue, then add a comment to the issue with a link to your pull request. If it's not (or you're
feeling too lazy to search through JIRA), then you should email the mailing-list to notify
committers of your pull request.

View raw message