From ebbedb1659fd58621d77ff0e92ec011046417d5a Mon Sep 17 00:00:00 2001 From: Andrey Dubov Date: Tue, 24 Dec 2019 15:42:33 +0300 Subject: [PATCH] Update docs (#688) Co-authored-by: Alexander Goncharov --- sdk/README.md | 77 +++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 63 insertions(+), 14 deletions(-) diff --git a/sdk/README.md b/sdk/README.md index d0655c3..fc7445c 100644 --- a/sdk/README.md +++ b/sdk/README.md @@ -1,37 +1,84 @@ +UPDATE: Over the next few months, we will be working on a new version of CodePush that will address some of the most common performance issues our customers are facing. This updated version will allow a better experience, our team to better support CodePush moving forward and have a faster development cycle for new features. +We are prioritizing this work because we believe this to be the most valuable thing we can do for our CodePush customers in the long run. Starting June 11th 2019, support will slow down, bug fixes will be limited to critical bugs, and new feature development will pause until we finish this core update. + +--- + +[![appcenterbanner](https://user-images.githubusercontent.com/31293287/32969262-3cc5d48a-cb99-11e7-91bf-fa57c67a371c.png)](http://microsoft.github.io/code-push/) + +#### [Sign up With App Center](https://appcenter.ms/signup?utm_source=CodePush&utm_medium=Azure) to use CodePush + +# CodePush + +[CodePush](https://microsoft.github.io/code-push) is a cloud service that enables Cordova and React Native developers to deploy mobile app updates directly to their users' devices. It works by acting as a central repository that developers can publish updates to (JS, HTML, CSS and images), and that apps can query for updates from (using provided client SDK for [Cordova](https://github.com/Microsoft/cordova-plugin-code-push) and [React Native](https://github.com/Microsoft/react-native-code-push)). This allows you to have a more deterministic and direct engagement model with your userbase, when addressing bugs and/or adding small features that don't require you to re-build a binary and re-distribute it through the respective app stores. + +To get started using CodePush, refer to our [documentation](https://docs.microsoft.com/en-us/appcenter/distribution/codepush/), otherwise, read the following steps if you'd like to build/contribute to the project from source. + +*NOTE: If you need information about [code-push management CLI](https://github.com/microsoft/code-push/tree/v3.0.1/cli), you can find it in v3.0.1.* + +## Dev Setup + +* Install [Node.js](https://nodejs.org/) +* Install [Git](http://www.git-scm.com/) +* Clone the Repository: `git clone https://github.com/Microsoft/code-push.git` + +### Building + +* Run `npm setup` to install the NPM dependencies of management SDK. +* Run `npm run build` to build the management SDK for testing. +* Run `npm run build:release` to build the release version of management SDK. + +### Running Tests + +* To run tests, run `npm run test` from the root of the project. +* You can use debug mode for tests with `.vscode/launch.json` file. + +### Coding Conventions + +* Use double quotes for strings +* Use four space tabs +* Use `camelCase` for local variables and imported modules, `PascalCase` for types, and `dash-case` for file names + +This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments. + # CodePush Management SDK (Node.js) -A JavaScript library for programmatically managing your CodePush account (e.g. creating apps, promoting releases), which allows authoring Node.js-based build and/or deployment scripts, without needing to shell out to the [CLI](https://github.com/Microsoft/code-push/blob/master/cli/README.md). +A JavaScript library for programmatically managing your CodePush account (e.g. creating apps, promoting releases), which allows authoring Node.js-based build and/or deployment scripts, without needing to shell out to the [App Center CLI](https://github.com/microsoft/appcenter-cli). ## Getting Started -1. Create an access key to authenticate with the CodePush server using the following CodePush CLI command: +1. Create a token to authenticate with the CodePush server using the following [App Center CLI](https://github.com/microsoft/appcenter-cli) command: ```shell - code-push access-key add "DESCRIPTION_OF_THE_KEY" + appcenter tokens create -d "DESCRIPTION_OF_THE_TOKEN" ``` - - If you already created a key that you want to use here, then you can retrieve it by running `code-push access-key ls` and using the value of the `Key` column for the key you wish to use. - + Please copy your `API Token` and keep it secret. You won't be able to see it again. + 2. Install the management SDK by running `npm install code-push --save` -3. Import it using the following statement (using ES6 syntax as applicable): +3. Import it using one of the following statement: (using ES6 syntax as applicable): + * On commonjs environments: ```javascript - var CodePush = require("code-push"); + const CodePush = require("code-push"); + ``` + * Using ES6 syntax with tsconfig.json: + + ```javascript + import CodePush from "code-push"; ``` -4. Create an instance of the `CodePush` class, passing it the access key you created or retrieved in step #1: +4. Create an instance of the `CodePush` class, passing it the `API Token` you created or retrieved in step #1: ```javascript - var codePush = new CodePush("YOUR_ACCESS_KEY"); + const codePush = new CodePush("YOUR_API_TOKEN"); ``` 5. Begin automating the management of your account! For more details on what you can do with this `codePush` object, refer to the API reference section below. ## API Reference -The `code-push` module exports a single class (typically referred to as `CodePush`), which represents a proxy to the CodePush account management REST API. This class has a single constructor for authenticating with the CodePush service, and a collection of instance methods that correspond to the commands in the management [CLI](https://github.com/Microsoft/code-push/blob/master/cli/README.md), which allow you to programmatically control every aspect of your CodePush account. +The `code-push` module exports a single class (typically referred to as `CodePush`), which represents a proxy to the CodePush account management REST API. This class has a single constructor for authenticating with the CodePush service, and a collection of instance methods that correspond to the commands in the [App Center CLI](https://github.com/microsoft/appcenter-cli), which allow you to programmatically control every aspect of your CodePush account. ### Constructors @@ -39,9 +86,11 @@ The `code-push` module exports a single class (typically referred to as `CodePus ### Methods +*Note: `access key` here refers to an AppCenter API Token.* + - __addAccessKey(description: string): Promise<AccessKey>__ - Creates a new access key with the specified description (e.g. "VSTS CI"). -- __addApp(name: string, os: string, platform: string, manuallyProvisionDeployments: boolean = false): Promise<App>__ - Creates a new CodePush app with the specified name, os, and platform. If the default deployments of "Staging" and "Production" are not desired, pass a value of true for the manuallyProvisionDesployments parameter. +- __addApp(name: string, os: string, platform: string, manuallyProvisionDeployments: boolean = false): Promise<App>__ - Creates a new CodePush app with the specified name, os, and platform. If the default deployments of "Staging" and "Production" are not desired, pass a value of true for the manuallyProvisionDeployments parameter. - __addCollaborator(appName: string, email: string): Promise<void>__ - Adds the specified CodePush user as a collaborator to the specified CodePush app. @@ -65,7 +114,7 @@ The `code-push` module exports a single class (typically referred to as `CodePus - __getDeploymentMetrics(appName: string, deploymentName: string): Promise<DeploymentMetrics>__ - Retrieves the installation metrics for the specified app deployment. -- __getDeployments(appName: string): Promose<Deployment[]>__ - Retrieves the list of deployments associated with the specified app. +- __getDeployments(appName: string): Promise<Deployment[]>__ - Retrieves the list of deployments associated with the specified app. - __patchRelease(appName: string, deploymentName: string, label: string, updateMetadata: PackageInfo): Promise<void>__ - Updates the specified release's metadata with the given information. @@ -99,4 +148,4 @@ When an error occurs in any of the methods, the promise will be rejected with a - __CodePush.ERROR_INTERNAL_SERVER__: An error occurred internally on the CodePush server. - __CodePush.ERROR_NOT_FOUND__: The resource you are attempting to retrieve does not exist. - __CodePush.ERROR_CONFLICT__: The resource you are attempting to create already exists. - - __CodePush.ERROR_UNAUTHORIZED__: The access key you configured is invalid or expired. \ No newline at end of file + - __CodePush.ERROR_UNAUTHORIZED__: The access key you configured is invalid or expired.