azure-sdk-for-js/documentation/steps-after-generations.md

What to do after generating the SDK code

The generated code is not enough to release at once and you need to update it for better user experience. Please follow the steps to check the code:

Build your project

After this finishes, you will see the generated code in src folder in your {PROJECT_ROOT}. Refer the development workflows guide for more details if you'd like to know more.

rush update
rush build -t <your-package-name>

Improve README.md document

A minimal README.md is generated by TypeScript emitter and you could improve README.md file per your service. To learn more about README, see below example README file.

• RLC example: Maps Route README.md
• DPG example: OpenAI README.md

How to write test for DPG/RLC

In order to release it, we need to add some tests for it to make sure we are delivering high quality packages. After generation you will see a sampleTest.spec.ts file in your {PROJECT_ROOT}/test/public folder, which has an empty test and you could add/update test cases against your own services.

See the Javascript Codegen Quick Start for Test for information on how to write and run tests for the Javascript SDK.

1. Write the test

   You could follow the basic RLC test interaction and recording example to write your test step by step.

   Also, you could refer to the below examples for more cases:

   • RLC example: OpenAI Testing
   • DPG example: Maps Route Testing

2. Run the test

   Now, you can run the test like this. If you are the first time to run test, you need to set the environment variable TEST_MODE to record. This will generate recordings for your test they could be used in playback mode.

   On Linux, you could use export to set env variable:

   rush build -t ${PACKAGE_NAME}
   export TEST_MODE=record && rushx test # this will run live test and generate a recordings folder, you will need to submit it in the PR.
   

   On Windows, you could use SET:

   rush build -t ${PACKAGE_NAME}
   SET TEST_MODE=record&& rushx test # this will run live test and generate a recordings folder, you will need to submit it in the PR.
   

   You can also run the playback mode test if your apis don't have breaking changes and you've already done the recording before.

   On Linux, you could use below commands:

   rush build -t ${PACKAGE_NAME}
   export TEST_MODE=playback && rushx test # this will run live test and generate a recordings folder, you will need to submit it in the PR.
   

   On Windows, you can use:

   rush build -t ${PACKAGE_NAME}
   SET TEST_MODE=playback&& rushx test # this will run live test and generate a recordings folder, you will need to submit it in the PR.
   

How to write samples

We highly encourage you to write some valid samples for your customer to get start your service with libraries. You may author TypeScript samples under the samples-dev folder. For quick start, you can use sample-dev template as reference and update the relevant information for your service such as package-name, sample code, description, etc.

To learn more, you could refer to the below samples:

• DPG sample: the samples of OpenAIClient
• RLC sample: the samples of MapsRouteClient

After the samples-dev folder change is finished, you will need to change the tsconfig.json to make sure the dev samples can be compiled and build correctly.

You will need to add this part to the compilerOptions of your tsconfig.json file so that the Samples engine could resolve the sample-dev package against the source code of the SDK.

    "paths": { "@azure/agrifood-farming": ["./src/index"] }

And change the "include" part to

  "include": ["./src/**/*.ts", "./test/**/*.ts", "samples-dev/**/*.ts"],

Then, we provide tools to automatically change it into workable samples in both TypeScript and JavaScript. And, you just need to add a sampleConfiguration in your package.json.

You will need to add a sample configuration section in your package.json file and put the following content into it.

  "//sampleConfiguration": {
    "productName": "A description of your services",
    "productSlugs": ["azure"],
    "disableDocsMs": true,
    "apiRefLink": "<the-link-to-your-service-on-docs.microsoft.com>"
  }

Now, you can generate both JavaScript and TypeScript workable samples with the following commands.

npm install -g common/tools/dev-tool # make sure you are in the azure-sdk-for-js repo root directory
cd ${PROJECT_ROOT}
npx dev-tool samples publish -f

You will see the workable samples in the ${PROJECT_ROOT}/samples folder.

Format both the generated code and manual code

After you have finished the generation and added your own tests or samples, you can use the following command to format the code.

cd ${PROJECT_ROOT} && rushx format

Also, we'll recommand you to run lint command to analyze your code and quickly find any problems.

cd ${PROJECT_ROOT} && rushx lint

And we could use lint:fix if there are any errors.

cd ${PROJECT_ROOT} && rushx lint:fix

How to create package

Now, we can use the exact same steps to build a releasable artifact.

rush update
rush build -t <your-package-name>
cd <your-sdk-folder>
export TEST_MODE=record && rushx test
rushx pack

You may send this artifact to your customer if your services are still in private preview and some customers want to try it out.

Create/Update the ci.yaml

Now, if everything looks good to you, you can submit a PR in azure-sdk-for-js repo with all the changes you made above. Before you do that, you need to add/update the ci.yml file. Depends on whether there's already one in your package folder.

If there's no such file, then you can add the following template.

# NOTE: Please refer to https://aka.ms/azsdk/engsys/ci-yaml before editing this file.
trigger:
  branches:
    include:
      - main
      - release/*
      - hotfix/*
  paths:
    include:
      - sdk/purview/
pr:
  branches:
    include:
      - main
      - feature/*
      - release/*
      - hotfix/*
    exclude:
      - feature/v4
  paths:
    include:
      - sdk/purview/
extends:
  template: ../../eng/pipelines/templates/stages/archetype-sdk-client.yml
  parameters:
    ServiceDirectory: purview
    Artifacts:
      - name: azure-agrifood-farming # azure-agrifood-farming for DPG; azure-rest-agrifood-farming for RLC
        safeName: azureagrifoodfarming # azureagrifoodfarming for DPG; azurerestagrifoodfarming for RLC

Please change the paths.include value as your own project path, and change the Artifacts name and safeName into yours.

If there's already a ci.yml file in your project path, then the only thing you need to do is to add the Artifacts name and safeName of yours into that ci.yml.

Please notice the Artifacts name should align with your package name. Here, the package name is @azure/agrifood-farming so the relevant Artifacts name is azure-agrifood-farming.

Prepare PR

TypeScript emitter can only help you generate SDK code, there is something you need to update manually.

CHANGELOG.md

CHANGELOG can help customers know the change of new version quickly, so you need to update it according to the change of this new version. It is also necessary to update release date like 1.0.0-beta.1 (2022-11-11) (rough time is fine and no need to be very accurate).

Version Number

You shall update the version number according to semantic versioning rule.

Test recordings

After writing and running test cases, you need to push the recordings to assets repo. Please refer to push recording guide to push recordings.

Fix CI for PR

You may meet the CI failures after submitting the PR, so please refer to Troubleshoot CI Failure to fix it.

CC dpg-devs for review

Please add below comment in your PR to include dpg-devs to review your PR timely.

cc @Azure/dpg-devs for awareness

Create API View

When submitting a PR our pipeline would automatically prepare the API view in API View Website. You could see an example link here. Then, you could click the API view link in that comment to know more details.

Release

After the PR is merged, it is time to release package. Here is the Release Checklist you should know before release.