Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add scripts for publishing to VS Code Marketplace #12

Merged
merged 11 commits into from
Jul 21, 2017
Prev Previous commit
Next Next commit
Add instructions on how to publish
Also, reorder some of the commands in publish.js so that they make logical sense together.

@W-4162004@
Nick Chen committed Jul 21, 2017

Verified

This commit was signed with the committer’s verified signature. The key has expired.
binghe Chun Tian
commit 6ebb82df2219b309abc374dd92f53e36deb2b0c6
89 changes: 89 additions & 0 deletions docs/publishing.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,89 @@
# Introduction

This is a guide for publishing to the Visual Studio Code Marketplace. Most
contributors will not need to worry about publishing. However, it might be
worthwhile familiaring yourself with the steps in case you need to share the
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

familiarizing?

extensions through the .vsix files.

# Goal

The goal of publishing is to take the extensions under /packages, bundle them as
.vsix files, and push them to the [Visual Studio Code
Marketplace](https://marketplace.visualstudio.com/vscode).

For more information about publishing take a look at

* [Publishing VS Code Extensions](https://code.visualstudio.com/docs/extensions/publish-extension)
* [Managing Extensions](https://code.visualstudio.com/docs/editor/extension-gallery)

# Steps

The scripts/publish.js contains the end-to-end flow. It is possible to run each step manually.

The files under scripts use [shelljs/shx](https://github.com/shelljs/shx) and
[shelljs/shelljs](https://github.com/shelljs/shelljs) to write scripts in a
portable manner across platforms.

## Packaging as .vsix

### Prerequisite

* Lerna is properly installed.

### Steps

1. `npm run bootstrap` to install all the dependencies and to symlink interdependent local modules.
1. `npm run compile` to compile all the TypeScript files.
1. `npm run test` to run all the tests.
1. `lerna publish ...` will increment the version in the individual package.json
to prepare for publication. **This also commits the changes to git and adds a
tag.**
1. `npm run vscode:package` packages _each_ extension as a .vsix.

**At this stage, it is possible to share the .vsix directly for manual installation.**

## Generating SHA256

Due to [vscode-vsce#191](https://github.com/Microsoft/vscode-vsce/issues/191)
the .vsix are neither signed nor verified. To ensure that they have not been
tampered with, we generate a SHA256 of the contents and publish that to
https://developer.salesforce.com/media/vscode/SHA256

### Prequisite

* You have access to our S3 bucket at s3://dfc-data-production/media/vscode
* You have the [AWS CLI](https://aws.amazon.com/cli/) installed and configured
via `aws configure` or have the `AWS_ACCESS_KEY_ID` and
`AWS_SECRET_ACCESS_KEY` exported as environment variables.

### Steps

1. `npm run vscode:sha256` will compute the SHA256 for the .vsix generated in
the previous stage.
1. The SHA256 are appended to the top-level SHA256 file.
1. This file is then copied over to our S3 bucket.
1. Finally the file is added to git so that it can be committed.

## Pushing .vsix to Visual Studio Marketplace

### Prequisite

* You have a personal access token that for the salesforce publisher id that is
exported as `VSCE_PERSONAL_ACCESS_TOKEN`.
* Or, you have vsce installed and configured with the salesforce publisher id.

### Steps

1. `npm run vscode:publish` takes the .vsix that you had _before_ and uploads
it to the Visual Studio Code Marketplace.

It's **crucial** that you publish the .vsix that you had before so that the
SHA256 match. If you were to repackage, the SHA256 woudl be different.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

woudl -> would


# Tips

1. After publishing, you will need to run `npm run bootstrap` again to continue
development. This is because the `npm run vscode:package` step does a `npm
prune --production`. This is required due to the way Lerna does symlinking.
See [vscode-vsce#52](https://github.com/Microsoft/vscode-vsce/issues/52) for
more information.
6 changes: 3 additions & 3 deletions scripts/publish.js
Original file line number Diff line number Diff line change
@@ -38,15 +38,15 @@ shell.exec(`npm run vscode:package`);
// Generate the SHA256 and append to the file
shell.exec(`npm run vscode:sha256`);

// Publish to VS Code Marketplace
shell.exec(`npm run vscode:publish`);

// Push the SHA256 to AWS
shell.exec('aws s3 cp SHA256 s3://dfc-data-production/media/vscode/SHA256');

// Add SHA256 to git
shell.exec(`git add SHA256`);

// Publish to VS Code Marketplace
shell.exec(`npm run vscode:publish`);

// Perform these steps manually for now
// Git commit
// shell.exec(`git commit -m "Updated SHA256"`);