Mailing-List: contact commits-help@cordova.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@cordova.apache.org
MIME-Version: 1.0
Content-Type: text/plain; charset="utf-8"
Content-Transfer-Encoding: quoted-printable
From: Apache Wiki <wikidiffs@apache.org>
To: Apache Wiki <wikidiffs@apache.org>
Date: Thu, 24 Oct 2013 01:10:08 -0000
Message-ID: <20131024011008.38841.33483@eos.apache.org>
Subject: 
 =?utf-8?q?=5BCordova_Wiki=5D_Update_of_=22ContributorWorkflow=22_by_JoshS?=
 =?utf-8?q?oref?=
Auto-Submitted: auto-generated

Dear Wiki user,

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

The "ContributorWorkflow" page has been changed by JoshSoref:
https://wiki.apache.org/cordova/ContributorWorkflow?action=3Ddiff&rev1=3D40=
&rev2=3D41

Comment:
Extract Issue content to IssueWorkflow

   * Step - 3: Create an account in jira apache  http://issues.apache.org/j=
ira/
   * Step - 4: Bookmark the following link: http://issues.apache.org/jira/b=
rowse/CB (this is the official url for cordova jira issues)
   * Step - 5: Introduce yourself to the community, by giving a brief intro=
ductory mail to dev@cordova.apache.org
+  * Step - 6: [[IssueWorkflow|Work on an issue]]
  =

  If you have completed these steps, you are now ready to start contributin=
g.
  =

@@ -81, +82 @@

  =3D=3D=3D Easier for the Maintainer =3D=3D=3D
  Maintainers like topic branches. It is easier to review the pull request =
and merge commits into the main repository.
  =

- =3D=3D Issue Workflow =3D=3D
- =3D=3D=3D Identifying a problem =3D=3D=3D
-  1. You've run into a problem.
-  1. The first thing you should do is [[https://issues.apache.org/jira/iss=
ues/?jql=3Dproject%20%3D%20CB%20AND%20issuetype%20%3D%20Bug%20AND%20resolut=
ion%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 a=
s Cordova, you'll select "Bug" as the issue type.
-  1. Consider that you've decided to work on ticket # CB-1234 for the cord=
ova-x repository. You are charged with updating some documentation.
- =

- =3D=3D=3D Updating Jira =3D=3D=3D
-  * 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 perm=
issions to do so on the [[http://cordova.apache.org/#mailing-list|mailing-l=
ist]]. 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 comme=
nt to the issue stating your intention. You can work on it, but in this cas=
e, 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 co=
mmitter who did the merge will fill in the `version fixed` field appropriat=
ely.
-  * 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 me=
ans''''.
-  * You can resolve an issue as Duplicate.
- =

- =3D=3D=3D Providing patches =3D=3D=3D
- 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 thi=
s)
-  * You can send a pull request to the [[https://github.com/search?q=3D%40=
apache+cordova|github.com/apache/cordova]]-* repository
- =

- =3D=3D Git Workflow =3D=3D
- =3D=3D=3D Setting up your repository =3D=3D=3D
- If you already have a git repository for the area where you'll be doing w=
ork, great, you can skip this step.
- The following commands will give you two remotes: origin (apache) and git=
hub (your repository). Replace `you` with your github.com account name in t=
he 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
- }}}
- =3D=3D=3D Update your master branch =3D=3D=3D
- You'll want to update from upstream to make sure you're working on the la=
test code. Work starts from the master branch.
- =

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

- =3D=3D=3D Create a topic branch =3D=3D=3D
- 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 aft=
er the ticket. This topic branch is now isolated and branched off the histo=
ry of your master branch.
- =

- =3D=3D=3D Make File Changes =3D=3D=3D
- Let's update the accelerometer documentation for the "watchPosition" func=
tion.
- =

- As it happens, the docs repository is organized with a top level `docs` d=
irectory. Inside the `docs` directory is a folder for each language, the ca=
nonical language is English (`en`). Inside each language are folders, one f=
or each released version of Cordova, and an `edge` folder for the next vers=
ion of Cordova. API documentation is inside that directory in a directory n=
amed `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 `ge=
olocation` directory. At the next directory, there's a class document `geol=
ocation.md` (similarly named in the other directories according to their re=
spective directory names) and documents for each method `geolocation.watchP=
osition.md` (with the second part of the file varying according to the resp=
ective method).
- =

- Thus, we're going to want to work on `docs/en/edge/cordova/geolocation/ge=
olocation.md`. Specifically, we're going to announce that this API is now a=
vailable on the HailOS platform. Typically you'd perform some more meaningf=
ul change to a file, and you'd use an editor for that. (For this change, yo=
u can expect feedback to complain that the insertion should be sorted alpha=
betically, 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/geolocat=
ion/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 direct=
ory)
- #
- #	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.
- =

- =3D=3D=3D Commit the File Changes =3D=3D=3D
- 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 yea=
r ago,
-   this just updates the documentation to reflect that."
- [detached HEAD bb95c71] [CB-1234] geolocation.watchPosition works @HailOS
-  1 file changed, 1 insertion(+)
- }}}
- =3D=3D=3D=3D About Commit Messages =3D=3D=3D=3D
- You are highly encouraged to describe your {{{git commit}}} with enough d=
etail for someone else to understand it. In doing so, your commit message c=
an consist of multiple lines. However, it also is highly encouraged that th=
e first line of your commit message not exceed 50 characters. This is becau=
se 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 t=
hat is 50 characters or less. Thus there will be highlighting and truncatin=
g 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 th=
e summary and any further detailed body. For example, here is a good exampl=
e 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 characte=
rs. Subsequent lines after the first may exceed 50 characters. (2) it refer=
ences a Jira issue by its id (CB-1234). Commonly, there should be a Jira is=
sue 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 y=
our 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.or=
g/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 us=
e this repository. This helps make it clear which platform authors should t=
ake 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 referenc=
e 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]].
- =

- =3D=3D=3D Test Your Changes =3D=3D=3D
- The contributor is responsible to test their changes and correct any prob=
lems with their changes before a pull request is submitted. The testing inc=
ludes 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 mo=
bile-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 d=
id with your change, so a committer can understand what testing was done be=
fore they merge your change. It is also recommended that where reasonably f=
easible, you add automated tests to validate your change and catch any futu=
re regressions.
- =

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

- =3D=3D=3D Commit More File Changes =3D=3D=3D
- {{{
- $ myeditor accelerometer/watchPosition.md
- $ git commit -a
- }}}
- =3D=3D=3D Prepare to Send Pull Request =3D=3D=3D
- Before sending the pull request, you should ensure that your changes merg=
e 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 he=
lp to make your commits more readable.
- =

- You can do this by pulling the latest changes from the main repository ba=
ck into our master. We make sure that our master is always in sync before i=
ssuing pull requests. Next, we rebase the history of the master branch onto=
 the topic branch ticket_11. Essentially, this will rewind your divergent c=
ommits, 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 appli=
cation of code changes. The [[http://book.git-scm.com/4_rebasing.html|git c=
ommunity 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
- }}}
- =3D=3D Sharing your Changes =3D=3D
- By pushing your topic branch onto your fork, a cordova-x committer can re=
view and merge your topic branch into the main repository.
- =

- =3D=3D=3D Sending a Pull Request from GitHub =3D=3D=3D
- Pull requests sent to the [[http://github.com/apache|Apache GitHub reposi=
tories]] 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.
  =

  =3D=3D=3D Getting Noticed =3D=3D=3D
  It is strongly recommended that you sign up for the [[http://cordova.apac=
he.org/#mailing-list|mailing list]] before issuing a pull request. If your =
pull request is related to an existing JIRA issue, then add a comment to th=
e issue with a link to your pull request. If it's not (or you're feeling to=
o lazy to search through JIRA), then you should email the mailing-list to n=
otify committers of your pull request.