Skip to content
This repository was archived by the owner on May 20, 2025. It is now read-only.

Doc updates #184

Merged
merged 3 commits into from
Mar 24, 2016
Merged

Doc updates #184

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
c833c8b
General doc updates
lostintangent Mar 24, 2016
dbe273c
Adding more detail
lostintangent Mar 24, 2016
35b717f
Fixing wording of disabled parameter
lostintangent Mar 24, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
77 changes: 41 additions & 36 deletions cli/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -227,11 +227,11 @@ When the metrics cell reports `No installs recorded`, that indicates that the se

Once your app has been configured to query for updates against the CodePush server, you can begin releasing updates to it. In order to provide both simplicity and flexibility, the CodePush CLI includes three different commands for releasing updates:

1. [General](#releasing-updates-general) - Simply uploads an update to the CodePush server, and therefore, provides the most flexibility in terms of how to generate the update in the first place (e.g. are you using a `gulp` task? running a custom shell script?), since it doesn't apply any opinion about it.
1. [General](#releasing-updates-general) - Releases an update to the CodePush server that was generated by an external tool or build script (e.g. a Gulp task, the `react-native bundle` command). This provides the most flexibility in terms of fitting into existing workflows, since it strictly deals with CodePush-specific step, and leaves the app-specific compilation process to you.

2. [React Native](#releasing-updates-react-native) - Performs the same functionality as the general release command, but also handles the work of generating the updated contents for you (JS bundle and assets), instead of requiring you to run both `react-native bundle` and then `code-push release`.
2. [React Native](#releasing-updates-react-native) - Performs the same functionality as the general release command, but also handles the task of generating the updated app contents for you (JS bundle and assets), instead of requiring you to run both `react-native bundle` and then `code-push release`.

3. [Cordova](#releasing-updates-cordova) - Performs the same functionality as the general release command, but also handles the work of preparing the app update for you, instead of requiring you to run both `cordova prepare` and then `code-push release`.
3. [Cordova](#releasing-updates-cordova) - Performs the same functionality as the general release command, but also handles the task of preparing the app update for you, instead of requiring you to run both `cordova prepare` and then `code-push release`.

Which of these commands you should use is mostly a matter of requirements and/or preference. However, we generally recommend using the relevant platform-specific command to start (since it greatly simplifies the experience), and then leverage the general-purpose `release` command if/when greater control is needed.

Expand All @@ -248,13 +248,13 @@ code-push release <appName> <updateContents> <targetBinaryVersion>

#### App name parameter

This specifies the name of the CodePush app that this update is being released for.
This specifies the name of the CodePush app that this update is being released for. This value corresponds to the friendly name that you specified when originally calling `code-push app add` (e.g. "MyApp-Android"). If you need to look it up, you can run the `code-push app ls` command to see your list of apps.

#### Update contents parameter

This specifies the location of the code and assets you want to release. You can provide either a single file (e.g. a JS bundle for a React Native app), or a path to a directory (e.g. the `/platforms/ios/www` folder for a Cordova app). You don't need to zip up multiple files or directories in order to deploy those changes, since the CLI will automatically zip them for you.
This specifies the location of the updated app code and assets you want to release. You can provide either a single file (e.g. a JS bundle for a React Native app), or a path to a directory (e.g. the `/platforms/ios/www` folder for a Cordova app). Note that you don't need to ZIP up multiple files or directories in order to deploy those changes, since the CLI will automatically ZIP them for you.

It's important that the path you specify refers to the platform-specific, prepared/bundled version of your app. The following table outlines which command you should run before releasing, as well as the location you can subsequently point at using the `updateContents` parameter:
It's important that the path you specify refers to the platform-specific, prepared/bundled version of your app. The following table outlines which command you should run before releasing, as well as the location you can subsequently refer to using the `updateContents` parameter:

| Platform | Prepare command | Package path (relative to project root) |
|----------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------|
Expand Down Expand Up @@ -310,12 +310,6 @@ This provides an optional "change log" for the deployment. The value is simply r

*NOTE: This parameter can be set using either "--description" or "-desc"*

#### Disabled parameter

This specifies whether an update should be disabled. A disabled update is one that is not acquirable by clients. If left unspecified, the update will not be disabled, i.e. clients configured to receive updates from the particular deployment will receive the update [if it applies to them](#target-binary-version-parameter).

*NOTE: This parameter can be set using either "--disabled" or "-x"*

#### Mandatory parameter

This specifies whether the update should be considered mandatory or not (e.g. it includes a critical security fix). This attribute is simply round tripped to the client, who can then decide if and how they would like to enforce it.
Expand Down Expand Up @@ -354,6 +348,12 @@ This specifies the percentage of users (as an integer between `1` and `100`) tha

*NOTE: This parameter can be set using either `--rollout` or `-r`*

#### Disabled parameter

This specifies whether an update should be acquirable by end users or not. If left unspecified, the update will not be disabled (i.e. users will download it the moment your app calls `sync`). This parameter can be valuable if you want to release an update that isn't immediately available, until you expicitly [patch it](#patching-releases) when you want end users to be able to download it (e.g. an announcement blog post went live).

*NOTE: This parameter can be set using either "--disabled" or "-x"*

### Releasing Updates (React Native)

```shell
Expand Down Expand Up @@ -407,10 +407,6 @@ This is the same parameter as the one described in the [above section](#app-name

This specifies which platform the current update is targeting, and can be either `ios` or `android` (case-insensitive).

#### Bundle name parameter

This specifies the file name that should be used for the generated JS bundle. If left unspecified, the standard bundle name will be used for the specified platform: `main.jsbundle` (iOS) and `index.android.bundle` (Android).

#### Deployment name parameter

This is the same parameter as the one described in the [above section](#deployment-name-parameter).
Expand All @@ -419,34 +415,38 @@ This is the same parameter as the one described in the [above section](#deployme

This is the same parameter as the one described in the [above section](#description-parameter).

#### Development parameter
#### Mandatory parameter

This specifies whether to generate a unminified, development JS bundle. If left unspecified, this defaults to `false` where warnings are disabled and the bundle is minified.
This is the same parameter as the one described in the [above section](#mandatory-parameter).

#### Rollout parameter

This is the same parameter as the one described in the [above section](#rollout-parameter). If left unspecified, the release will be made available to all users.

#### Target binary version parameter

This is the same parameter as the one described in the [above section](#target-binary-version-parameter). If left unspecified, this defaults to targeting the exact version specified in the app's `Info.plist` (for iOS) and `build.gradle` (for Android) files.

#### Disabled parameter

This is the same parameter as the one described in the [above section](#disabled-parameter).

#### Development parameter

This specifies whether to generate a unminified, development JS bundle. If left unspecified, this defaults to `false` where warnings are disabled and the bundle is minified.

#### Entry file parameter

This specifies the relative path to app's root/entry JavaScript file. If left unspecified, this defaults to `index.ios.js` (for iOS) or `index.android.js` (for Android) if that file exists, or `index.js` otherwise.

#### Mandatory parameter
#### Bundle name parameter

This is the same parameter as the one described in the [above section](#mandatory-parameter).
This specifies the file name that should be used for the generated JS bundle. If left unspecified, the standard bundle name will be used for the specified platform: `main.jsbundle` (iOS) and `index.android.bundle` (Android).

#### Sourcemap output parameter

This specifies the relative path to where the generated JS bundle's sourcemap file should be written. If left unspecified, sourcemaps will not be generated.

#### Target binary version parameter

This is the same parameter as the one described in the [above section](#target-binary-version-parameter). If left unspecified, this defaults to targeting the exact version specified in the app's `Info.plist` (for iOS) and `build.gradle` (for Android) files.

#### Rollout parameter

This is the same parameter as the one described in the [above section](#rollout-parameter). If left unspecified, the release will be made available to all users.

### Releasing Updates (Cordova)

```shell
Expand Down Expand Up @@ -495,25 +495,25 @@ This is the same parameter as the one described in the [above section](#deployme

This is the same parameter as the one described in the [above section](#description-parameter).

#### Disabled parameter

This is the same parameter as the one described in the [above section](#disabled-parameter).

#### Mandatory parameter

This is the same parameter as the one described in the [above section](#mandatory-parameter).

#### Rollout parameter

This is the same parameter as the one described in the [above section](#rollout-parameter). If left unspecified, the release will be made available to all users.

#### Target binary version parameter

This is the same parameter as the one described in the [above section](#target-binary-version-parameter). If left unspecified, the command defaults to targeting only the specified version in the project's metadata (`Info.plist` if this update is for iOS clients, and `build.gradle` for Android clients).

#### Rollout parameter
#### Disabled parameter

This is the same parameter as the one described in the [above section](#rollout-parameter). If left unspecified, the release will be made available to all users.
This is the same parameter as the one described in the [above section](#disabled-parameter).

## Patching Updates

After releasing an update, there may be scenarios where you need to modify one or more of the attributes associated with the release (e.g. you forgot to mark a critical bug fix as mandatory, you want to increase the rollout percentage of an update). You can easily do this by running the following command:
After releasing an update, there may be scenarios where you need to modify one or more of the attributes associated with it (e.g. you forgot to mark a critical bug fix as mandatory, you want to increase the rollout percentage of an update). You can easily do this by running the following command:

```shell
code-push patch <appName> <deploymentName>
Expand All @@ -525,9 +525,14 @@ code-push patch <appName> <deploymentName>

Aside from the `appName` and `deploymentName`, all parameters are optional, and therefore, you can use this command to update just a single attribute or all of them at once. Calling the `patch` command without specifying any attribute flag will result in a no-op.

```shell
code-push patch MyApp Production -m
code-push patch MyApp Production -l v23 -rollout 50%
```

#### Label Parameter

Indicates which release (e.g. `v23`) you want to update within the specified deployment. If ommitted, the requested changes will be applied to the latest release in the specified deployment.
Indicates which release (e.g. `v23`) you want to update within the specified deployment. If ommitted, the requested changes will be applied to the latest release in the specified deployment. In order to look up the label for the release you want to update, you can run the `code-push deployment history` command and refer to the `Label` column.

*NOTE: This parameter can be set using either `--label` or `-l`*

Expand Down