development.md

How to develop openshift-vsts

• Prerequisites
• npm build tasks
  • Transpile
  • Test
  • Create extension
  • Publish extension
    • To staging
    • To production
  • Write docs
• CI
• References

Prerequisites

• Install Node.js

• Run npm setup script

  > npm run setup

npm build tasks

The various build tasks are driven via npm. Check package.json for the defined run scripts. To get a list of all available tasks run:

> npm run

Transpile

To transpile TypeScript to JavaScript:

> npm run build

To watch your TypeScript files for changes and transpile on the fly:

> npm run build:watch

Test

Test are written using mocha and live in the test directory of the checkout. You can run the tests via:

> npm test

There are a couple of test which go over the network and access the GitHub API. You can exclude them by setting the MOCHA_TAG environment variable like so:

MOCHA_TAG='--grep @network --invert' npm run test

For more information regarding test tagging refer to Mocha's Tagging documenttion.

You can get an HTML version of the test results into the out directory by running:

> npm test:report

If you are running the tests a lot, you might reach the GitHub API rate limit. In this case you can create a GitHub access token and export it under the environment variable GITHUB_ACCESS_TOKEN.

Create extension

To create the extension (vsix file):

> npm run extension:create

To create the extension for a deploy to a staging publisher:

> npm run extension:create:dev

During development it can be handy to push patch releases to a test publisher. The following command will create the extension bumping the version of the extension as well as all as the versions of all tasks:

> npm run extension:create:patch

Publish extension

Prerequisite for publishing from the command line is a personal access token. Once you have setup your token, you can chose to publish to a test/staging publisher or the production publisher 'redhat'.

To staging

Do do a staging deploy you can specify a staging publisher by setting the DEV_PUBLISHER environment variable:

> export TOKEN=<token>
> export DEV_PUBLISHER=<publisher>
> npm run clean
> npm run build
> npm run extension:create:dev
> npm run extension:publish:dev

The OpenShift VSTS (OpenShiftVSTS) can be used as a shared development publisher.

Once the extension is installed, you can share it with a given user:

> export EXT_SHARES=<comma seperated list of users to share with>
> export DEV_PUBLISHER=<stage/test publisher>
> npm run extension:share:dev

To unshare:

> export EXT_SHARES=<comma seperated list of users to share with>
> export DEV_PUBLISHER=<stage/test publisher>
> npm run extension:unshare:dev

To production

Do do a production deploy under the Red Hat publisher follow these steps. They need to be executed from the master branch.

> export TOKEN=<token>
> npm run clean
> npm install
> npm run test
> EXT_VERSION=<version> npm run extension:version:set
> npm run extension:create
> npm run extension:publish
> npm run extension:publish:commit

You need to be member of this publisher!

Write docs

To write on the docs you can leverage markserv npm, rendering and updating the docs as you go. Just run:

> npm run docs

CI

There is one CI system configured for this project and it uses GitHub Actions.

References

• Microsoft's Develop Extensions guide
• Getting Started
• Tutorials
  • Available pipeline environment variables
  • Publish from the command line
• vsts-task-lib TypeScript API
• Microsoft's Azure Pipelines tasks
• Step by Step: Node Task with Typescript API
• How to Use npm as a Build Tool
• Use Git within a pipeline script task
• Custom authentication schemes