Skip to content
Permalink
Browse files
CB-13624 : revised contributor docs and fixed typos
  • Loading branch information
audreyso committed Dec 6, 2017
1 parent 23702e8 commit 568a663e182bfa1f97e017f2749bc726ec5ccf5f
Show file tree
Hide file tree
Showing 10 changed files with 64 additions and 63 deletions.
@@ -27,7 +27,7 @@ This page describes the technical steps for releasing the `Hello-world-app` (see

## Get Buy-in

Email the dev mailing-list and see if anyone has reason to postpone the release.
Email the dev mailing-list at dev@cordova.apache.org and see if anyone has reason to postpone the release.

E.g.:

@@ -52,7 +52,7 @@ E.g.:

## Update Release Notes & Version

Increate the version within `package.json` using `SemVer`, and remove teh `-dev` suffix.
Increment the version within `package.json` using `SemVer`, and remove the `-dev` suffix.

(cd cordova-app-hello-world; v="$(grep '"version"' package.json | cut -d'"' -f4)"; if [[ $v = *-dev ]]; then v2="${v%-dev}"; echo "cordova-app-hello-world: Setting version to $v2"; sed -i '' -E 's/version":.*/version": "'$v2'",/' package.json; fi)

@@ -143,7 +143,7 @@ Upload:
Find your release here: https://dist.apache.org/repos/dist/dev/cordova/

## Start VOTE Thread
Send an email to dev ML with:
Send an email to dev mailing list with:

__Subject:__

@@ -251,7 +251,7 @@ Subject: [ANNOUNCEMENT] Cordova App Hello World Release
Do the same things regarding announcements as described in cadence-release-process, where they make sense.

## Close JIRA Issue
* Double check that the issue has comments that record the steps you took
* Double check that the issue includes comments that record the steps you took
* Mark it as fixed

## Finally:
@@ -24,5 +24,5 @@
We use GitHub pull requests for code reviews.
1. Commit to a branch on your own fork of the repo that you're changing
2. Use GitHub to create a pull request
3. Email out the link to it
3. Email out the link to it to dev@cordova.apache.org

@@ -37,7 +37,7 @@ It's convenient to have the origin of your git repos to point to Apache's repos
(as opposed to your clone of them on github). The easiest way to do this is to
delete them and re-clone them using coho:

git clone https://git-wip-us.apache.org/repos/asf/cordova-coho.git
git clone https://github.com/apache/cordova-coho.git
cd cordova-coho
npm install
cd ..
@@ -70,15 +70,15 @@ Understanding how Apache works goes a long way:

### Step 1: Mail the Mailing-list (_optional_)
This is required if any of the following apply:
* Your change will add/remove/change a public Cordova API
* You suspect that your change has a chance of being controversial
* You would like feedback before you begin
* Your change will add/remove/change a public Cordova API.
* You suspect that your change has a chance of being controversial.
* You would like feedback before you begin.

When possible, try to phrase things in the form of a proposal. If no one objects (within a workday or two), then consider yourself to have [lazy consensus](http://www.apache.org/foundation/glossary.html#LazyConsensus).

### Step 2: Ensure there is a JIRA issue
* They are not necessary for *all* changes, (e.g. style nits, refactoring)
* They should always be used for new features and bugs
* They are not necessary for *all* changes, (e.g. style nits, refactoring).
* They should always be used for new features and bugs.

### Step 3: Create a topic branch (_optional_)
* Using a public topic branch is necessary only when you would like to collaborate on the feature.
@@ -87,25 +87,25 @@ When possible, try to phrase things in the form of a proposal. If no one objects

### Step 4: Make your changes
* Thank you for making the world a better place.
* Please beign your commit with the issue. Ex. `CB-XXXX **PLATFORM** Fixed broken scrolling`
* Please begin your commit with the issue. Ex. `CB-XXXX **PLATFORM** Fixed broken scrolling`

### Step 5: Test your changes ###
* You are responsible for testing the commits you push.
* Tests vary by repo, but in general:
* Plugins: Automated tests in mobile-spec and/or manual tests in mobile spec
* Tools: run `npm test` from the project root
* Platforms: Native unit tests (i.e., `cordova-android/test`, `cordova-ios/CordovaLibTests`)
* Cordova JS: Run `grunt test`
* If there is no existing test that exercises your code, consider adding one
* Plugins: Automated tests in mobile-spec and/or manual tests in mobile spec.
* Tools: run `npm test` from the project root.
* Platforms: Native unit tests (i.e., `cordova-android/test`, `cordova-ios/CordovaLibTests`).
* Cordova JS: Run `grunt test`.
* If there is no existing test that exercises your code, consider adding one.
* If you are writing documentation (i.e., cordova-docs), be aware of the [style guidelines](https://github.com/apache/cordova-docs/blob/master/STYLESHEET.md).

### Step 6: Ask for a code review (_optional_)
* Do this if you want a second pair of eyes to look at your code before it goes in.
* Use GitHub pull request.

### Step 7: Push your change
* When possible, rebase & squash your commits
* Make sure you can figure out what your commit does by the first line of your commit discription.
* When possible, rebase & squash your commits.
* Make sure you can figure out what your commit does by the first line of your commit description.
* If it fixes a regression, then also cherry-pick it into the appropriate release branch.

Here is an example workflow for committing a change when you've made it on a topic branch
@@ -151,13 +151,13 @@ The `git rebase -i` step is your chance to clean up the commit messages and to c
* For all commits:
* Prefix with JIRA IDs: CB-1234
* For commits to cordova-js or to plugins:
* Prefix the message with the affected_platform so that it's clear who should take interest in the commit
* Prefix the message with the affected_platform so that it's clear who should take interest in the commit.
* e.g.: `CB-1234 android: Improved exec bridge by using strings instead of JSON`
* e.g.: `CB-1234 all: Fixed plugin loading paths that start with /`

### Step 8: Update JIRA
* An Apache bot should have already added a comment to the issue with your commit ID (based on the CB-1234 being in the commit message).
* Click the "Resolve Issue" button
* Click the "Resolve Issue" button.
* Add a comment saying what version the commit is in (e.g. Fixed in 0.1.3-dev).

### Step 9: Delete your topic branch
@@ -174,12 +174,12 @@ deleting those topic branches. No sense in letting cruft accumulate.
# Which Branch to Commit To

### Platforms, mobile-spec, cordova-js, cordova-docs:
* Commit all changes to branch: `master`
* If it fixes a regression, cherry-pick into the release branch (see CuttingReleases)
* e.g. To cherry pick the last commit from master: `git cherry-pick -x master`
* Commit all changes to branch: `master`.
* If it fixes a regression, cherry-pick into the release branch (see CuttingReleases).
* e.g. To cherry pick the last commit from master: `git cherry-pick -x master`.

### All other Repos:
* Commit all changes to branch: `master`
* Commit all changes to branch: `master`.

# Processing Pull Requests #

@@ -38,4 +38,5 @@
* [Triaging JIRA issues](jira-triage.md)

## Misc

* [Storing Repo Versions Design](storing-repo-versions-design.md)
@@ -22,25 +22,25 @@
# JIRA Issue Triage Process

## Goal
Every issue needs to be triaged. A triaged issue is actionable and there is an eventual desire to resolve it and has all the fields set accurately. In particular, low quality issues are eliminated from the system. Also, critical issues need to be fixed asap and this process should highlight those.
Every issue needs to be triaged. A triaged issue is actionable and there is an eventual desire to resolve it and has all the fields set accurately. In particular, low quality issues are eliminated from the system. Also, critical issues need to be fixed asap and this process should highlight those issues.

## Process
Go through each [unresolved bug that is not labeled 'triaged' ordered by created Date](https://issues.apache.org/jira/issues/?jql=status%20not%20in%20(Resolved%2C%20Closed)%20AND%20(labels%20is%20EMPTY%20OR%20labels%20!%3D%20triaged)%20AND%20%20project%20%3D%20CB%20ORDER%20BY%20createdDate%20DESC).

- Ensure the bug details has sufficient details for a repro. If not, message the reporter with questions. If the reporter does not respond in 4 business days. Resolve the bug as `Invalid`. They are welcome to re-activate the bug with details at a later date.
- If you can reproduce the issue. Add a label `reproduced`. If not, Resolve the bug as `Cannot reproduce`.
- Ensure the bug details have sufficient details for a reproduction. If not, message the reporter with questions. If the reporter does not respond in 4 business days, resolve the bug as `Invalid`. They are welcome to re-activate the bug with details at a later date.
- If you can reproduce the issue, add a label `reproduced`. If not, resolve the bug as `Cannot reproduce`.
- If you are not an expert in the area or do not have the hardware for triaging, reference the platform and/or component owner in helping triage the bug.
- Edit the following fields:
- **Component**: Should be ideally a single component. *For plugin issues do not add platform names here.*
- **Work item type**: Ensure it has the correct classification - feature request vs task vs bug.
- **Priority**:
- `Blocker`: This will block the current release of the component. The failure is catastrophic and easy to hit. 'Hello world' and [mobilespec](https://github.com/apache/cordova-mobile-spec) does not build or crashes.
- `Critical`: This will cause the main function of the component to fail and needs to be fixed asap but will not block the release.
- `Critical`: This will cause the main function of the component to fail and needs to be fixed asap, but will not block the release.
- `Major`: Important one to fix.
- `Minor`, `Trivial`: Nice to haves.
- **Label**: Use the following:
- `regression` - A change introduced in previous release or commit that surfaced the issue. Ideally, add a link to the commit that caused the issue.
- `ios`, `android`, `windows`, `browser`, `node` etc. platforms - If it is a plugin issue and affects one of these platforms
- `ios`, `android`, `windows`, `browser`, `node` etc. platforms - You can use these labels, if it is a plugin issue and affects one of these platforms
- `beginner` or `easyfix` - For issues that are easy for a new contributor to fix. We will eventually publish an easyfix query for new contributors to participate.
- `triaged` - Indicates bug that has been triaged and does not need to be triaged again.
- `reproduced` - Bug that has a reproduction.
@@ -55,20 +55,20 @@ Go through each [unresolved bug that is not labeled 'triaged' ordered by created

- **Environment**: Represents the machine setup required to reproduce the problem. Great place for mobile OS, host OS versions etc.
- **Affected version**: Specify the version of the component that the issue appears in.
- **Assigned To**: If you plan to work on a particular issue, assign it to yourself. If the issue has not been worked on by the assignee i.e. status is not `in progress` or it's clear that the assignee is not looking at this actively. The issue can be taken up by anyone.
- **Assigned To**: If you plan to work on a particular issue, assign it to yourself. If the issue has not been worked on by the assignee i.e. status is not `in progress` or it's clear that the assignee is not looking at this actively, the issue can be taken up by anyone.

At the end of triage session, send an e-mail to the dev list discussing bugs that need urgent attention. Good bugs in this area are recent regressions or other issues having a wide impact. These would require a patch release to fix them.

## Asking for help
Sometimes while there is a bug or a feature request that seems valid, but it might not be high priority for one of the committers to fix. Following up with the issue reporter quickly and coaching him through making a contribution with a pull request is a good idea.
Sometimes there is a bug or a feature request that seems valid, but it might not be high priority for one of the committers to fix. Following up with the issue reporter quickly and coaching them through making a contribution with a pull request is a good idea.

## Tips when asking for more info from reporter
- If the cordova version is not provided, ask reporter to use “cordova -v” to verify which version of cordova he/she is using.
- If the cordova version is not provided, ask reporter to use “cordova -v” to verify which version of cordova they are using.
- If the platform version is not provided, ask the reporter to use “cordova platform ls” to verify which platform version he/she is using.
- If the issue is unclear, ask the reporter to provide more details via screen shot, sample code, or a command line log.

## Dealing with feature requests
New features to plugins should ideally be cross platform (at least across more than one major platform - Android, iOS, Windows). The design should account for ease of detection or meaningful degradation in the absence of the feature on a partcular platform. For feature requests that are overly specific to a particular usecase - we should resolve them with resolution reason `Later` or `Won't Fix`. There is little value in carrying the debt of these issues.
New features to plugins should ideally be cross platform (at least across more than one major platform - Android, iOS, Windows). The design should account for ease of detection or meaningful degradation in the absence of the feature on a particular platform. For feature requests that are overly specific to a particular use-case - we should resolve them with resolution reason `Later` or `Won't Fix`. There is little value in carrying the debt of these issues.

## Open issues
- Assignments: Who does JIRA triage? Do we need a weekly rotation duty? Should we publish a schedule? Should we distribute by component?
@@ -31,7 +31,7 @@ Replace `Android` with the platform you are releasing.

## Get Buy-in

Email the dev mailing-list and see if anyone has reason to postpone the release.
Email the dev mailing-list at dev@cordova.apache.org and see if anyone has reason to postpone the release.

E.g.:

@@ -63,13 +63,13 @@ See if any dependencies are outdated

(cd cordova-android && npm outdated --depth=0)

Update them in each project's `package.json` file. Make sure to run through the test section below for compatability issues. The `--depth=0` prevents from listing dependencies of dependencies.
Update them in each project's `package.json` file. Make sure to run through the test section below for compatibility issues. The `--depth=0` prevents from listing dependencies of dependencies.

Checkin updated modules (use npm 3.10.1+)
Check-in updated modules (use npm 3.10.1+)

rm -rf node_modules
npm install --production (skips devDependencies)
git add node_modules/* (checkin all modules needed for platform add git url)
git add node_modules/* (check-in all modules needed for platform add git url)
git commit -m "$JIRA Updated checked-in node_modules"
npm install (Re-add devDependencies for ability to run tests locally)

@@ -79,12 +79,12 @@ Ensure license headers are present everywhere. For reference, see this [backgrou

coho audit-license-headers -r android | less

Ensure all dependencies and subdependencies have Apache-compatible licenses
Ensure all dependencies and subdependencies have Apache-compatible licenses.

coho check-license -r android

## Prepare Release
Increase the version within package.json using SemVer, and remove the `-dev` suffix
Increase the version within package.json using SemVer, and remove the `-dev` suffix.

for l in cordova-android; do ( cd $l; v="$(grep '"version"' package.json | cut -d'"' -f4)"; if [[ $v = *-dev ]]; then v2="${v%-dev}"; echo "$l: Setting version to $v2"; sed -i '' -E 's/version":.*/version": "'$v2'",/' package.json; fi) ; done

@@ -94,13 +94,13 @@ If the changes merit it, manually bump the major / minor/ patch version in `pack

( cd cordova-android && git log --pretty=format:'* %s' --topo-order --no-merges $(git describe --tags $(git rev-list --tags --max-count=1))..master )

Update the repos `RELEASENOTES.md` file with changes since the last release
Update the repos `RELEASENOTES.md` file with changes since the last release.

coho update-release-notes -r android
# Then curate:
vim cordova-android/RELEASENOTES.md

Commit these changes together into one commit
Commit these changes together into one commit.

(cd cordova-android && v="$(grep '"version"' package.json | cut -d'"' -f4)" && git commit -am "$JIRA Updated RELEASENOTES and Version for release $v")

@@ -109,7 +109,7 @@ Commit these changes together into one commit
**PATCH RELEASE NOTES**


If you have prepared the release notes in your release branch for a patch release, you will have to cherry-pick the RELEASENOTES only into your master branch as well (stage only the appropriate hunk).
If you have prepared the release notes in your release branch for a patch release, you will have to cherry-pick the RELEASENOTES only into your master branch as well (stage only the appropriate chunk).

git checkout master
git checkout -p RELEASENOTES_COMMIT_SHA_HASH
@@ -126,7 +126,7 @@ After, prepare your release branch by using `coho prepare-release-branch` comman
* Updating version numbers (`VERSION` file & package.json). On `master`, it gives version a minor bump and adds `-dev`


Run the following command (make sure to replace the version below with what is listed inside `package.json`)
Run the following command (make sure to replace the version below with what is listed inside `package.json`).

coho prepare-platform-release-branch --version 5.0.0 -r android
# Ensure commits look okay on both branches
@@ -160,7 +160,7 @@ To submit a fix:
(cd mobilespec && cordova run android --emulator)
```

2) Create a hello world app using the cordova CLI
2) Create a hello world app using the cordova CLI.

```
cordova create ./androidTest org.apache.cordova.test androidTest
@@ -169,7 +169,7 @@ To submit a fix:
(cd androidTest && cordova run android --emulator)
```

3) Run your platform's `./bin/create` script. Ensure generated project builds & runs both through an IDE and through the cordova/* scripts
3) Run your platform's `./bin/create` script. Ensure the generated project builds & runs both through an IDE and through the cordova/* scripts.


```
@@ -181,13 +181,13 @@ To submit a fix:

The output from `./cordova/version` should show the new version of `cordova-android`.

4) Run cordova-lib tests
4) Run cordova-lib tests.

```
(cd cordova-lib/cordova-lib && npm test)
```

Feel free to cleanup the projects you just created
Feel free to clean up the projects you just created.

```
rm -rf androidTest*
@@ -40,7 +40,7 @@ TODO: Should not mention testing other than checking medic

# Interactive Plugins Release

Though we are still working out some kinks, it is recommend to try the new coho interactive plugins release command which will handle many of the manual steps listed below.
Though we are still working out some kinks, it is recommended to try the new coho interactive plugins release command which will handle many of the manual steps listed below.

`coho prepare-plugins-release`

0 comments on commit 568a663

Please sign in to comment.