Adds `--token 1` to all `pnpm turbo build` (and related `pnpm build` / ` px turbo build`) commands in documentation to enable remote cache reads. This re-does #36964 on top of the latest `main`. ## Files changed - `CONTRIBUTING.md` — build example, dev-workflows section, command table, eslint plugin note - `documentation/linting.md` — eslint plugin build command - `documentation/RLC-Swagger-quickstart.md` — build and test commands - `documentation/steps-after-generations.md` — build and test commands - `documentation/Quickstart-on-how-to-write-tests.md` — build and test commands --------- Co-authored-by: Copilot <[email protected]> Copilot-Session: a2e59a5d-f7c8-4cb9-b71c-0c86ed6ecdc7
16 KiB
Getting Started - Generate the RLC REST-level client libraries with Swagger
Before you start
Please refer to this link for the environment set up prerequisites in azure-sdk-for-js repository. We highly recommend to read this blog to get familiar with REST libraries for JavaScript.
⚠️ Note: if you’re generating from TypeSpec with RLC, please read this doc for TypeSpec specific details.
Project folder and name convention
If you are the first time to prepare the SDK, please follow the Azure SDK guidance and discuss with architects to decide the project folder and name convention for RLC libraries.
- Project Folder Structure.
normally, the folder structure would be something like
sdk/{servicename}/{servicename}-{modulename}-rest. For example, we havesdk/agrifood/agrifood-farming-restfolder for Farmbeats account modules. That folder will be your ${PROJECT_ROOT} folder. - Package Name Convention.
The package name for RLC is something like
@azure-rest/{servicename}-{modulename}. For example, the package name for Farmbeats module is@azure-rest/agrifood-farming.
How to generate RLC
We are working on to automatically generate everything right now, but currently, we still need some manual work to get a releasable package. Here're the steps of how to get the package.
-
Create a swagger/README.md file under ${PROJECT_ROOT} folder We are using autorest to generate the code, but there's a lot of command options and in order to make the regenerate process easier in the cases of refresh the rest api input or change the code generator version, you need to document the generate command parameters. Here's an example of the
swagger/README.md:# Azure Farmbeats TypeScript Protocol Layer > see https://aka.ms/autorest ## Configuration ```yaml package-name: "@azure-rest/agrifood-farming" title: Farmbeats description: Farmbeats Client generate-metadata: true generate-test: true generate-sample: true license-header: MICROSOFT_MIT_NO_VERSION output-folder: ../ source-code-folder-path: ./src input-file: https://raw.githubusercontent.com/Azure/azure-rest-api-specs/683e3f4849ee1d84629d0d0fa17789e80a9cee08/specification/agfood/data-plane/Microsoft.AgFoodPlatform/preview/2021-03-31-preview/agfood.json package-version: 1.0.0-beta.2 rest-level-client: true security: AADToken security-scopes: https://farmbeats.azure.net/.default use-extension: "@autorest/typescript": "6.0.0-rc.10" ```Here, we need to replace the value in
package-name,title,description,input-file,package-version,security,security-scopesinto your own service'spackage-name,title,descriptionetc.How to configure authentication
Autorest only support two types of authentication: Azure Key Credential(AzureKey) and Token credential(AADToken), any other will need to be handled manually.
This could be either configured in OpenAPI spec or configuration file e.g
README.md. You could learn more in Authentication in AutoRest.Here are the details if we configure in README.md file.
- Support AAD token authentication
security: AADToken security-scopes: https://yourendpoint.azure.com/.default- Support key authentication
security: AzureKey security-header-name: Your-Subscription-Key- Support both credentials
security: - AADToken - AzureKey security-header-name: Your-Subscription-Key security-scopes: https://yourendpoint.azure.com/.default- Disable neither authentications
add-credentials: false
NOTE
It's always recommended to replace the version of code generator @autorest/typescript with the latest version you can find in npmjs.com in latest tag.
If the
input-fileis followed by an.mdfile, you need to replace theinput-filewithrequire. If it is aJSONfile, do not change it.We enable the samples generation by default, this may fail the generation due to the example quality or codegen issue. You could turn this option off by
generate-sample: falseto non-block your process.After the first generation, you need to switch
generate-metadata: falseas we have some manual changes in this file and don't want them get overwritten by generated ones.
-
Run autorest to generate the SDK
Now, you can run this command in swagger folder you just created.
autorest --typescript ./README.mdAfter this finishes, you will see the generated code in
${PROJECT_ROOT}/srcfolder. After that, you can get a workable package, and run the following commands to get a artifact if you like.pnpm install pnpm turbo build --filter=<your-package-name>... --token 1 cd <your-sdk-folder> pnpm packBut, we still need to add some tests for it.
Improve README.md document
A minimal README.md is generated by our codegen and you could improve README.md file per your service. To learn more about README, see an example README.md here.
How to write test for RLC
In order to release your RLC library, we need to add some tests for it to make sure we are delivering high quality packages. But before adding the test, we need to enable the option generate-test: true to generate the necessary change in package.json and tsconfig.json so that test framework can work. Once the generation finished, 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.
-
Prerequisites
To be able to leverage the asset-sync workflow
- Install Powershell
- Make sure
pwshcommand works at this step (If you follow the above link,pwshis typically added to the system environment variables by default)
- Make sure
- Add
dev-toolto thedevDependenciesin thepackage.json.
The package needs to use the current version of the recorder that uses the test proxy (
@azure-tools/test-recorder@^4.0.0).Then, we need to generate a
assets.jsonfile. If your package is new or has never been pushed before, you could use below commands:npx dev-tool test-proxy init # this will generate assets.json file, you will get some info in this file. - Install Powershell
-
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 the test of MapsRouteClient for more cases.
-
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_MODEtorecord. This will generate recordings for your test they could be used inplaybackmode.On Linux, you could use
exportto set env variable:pnpm turbo build --filter=${PACKAGE_NAME}... --token 1 export TEST_MODE=record && pnpm 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:pnpm turbo build --filter=${PACKAGE_NAME}... --token 1 SET TEST_MODE=record&& pnpm 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
playbackmode test if your apis don't have breaking changes and you've already done the recording before.On Linux, you could use below commands:
pnpm turbo build --filter=${PACKAGE_NAME}... --token 1 export TEST_MODE=playback && pnpm 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:
pnpm turbo build --filter=${PACKAGE_NAME}... --token 1 SET TEST_MODE=playback&& pnpm test # this will run live test and generate a recordings folder, you will need to submit it in the PR. -
Push recording to assets repo
Notice:-
the tests have to be recorded using the
TEST_MODE=record, then the recording files will be generate. -
Before push your recording file, you must confirm that you are able to push recordings to the
azure-sdk-assetsrepo, you need write-access to the assets repo. Permissions toAzure/azure-sdk-assets
Here is the command to push:
npx dev-tool test-proxy pushAfter above command finished, you can find your local recording files in
./azure-sdk-for-js/.assets.And if you want to find your recording on
assets repo, you can get the tag inassets.jsonin your package root, which is a tag pointing to your recordings in the Azure/azure-sdk-assets repo.Example
assets.jsonfromkeyvault-certificatesSDK.{ "AssetsRepo": "Azure/azure-sdk-assets", "AssetsRepoPrefixPath": "js", "TagPrefix": "js/keyvault/keyvault-certificates", "Tag": "js/keyvault/keyvault-certificates_43821e21b3" }And the recordings are located at here.
-
How to write samples
If you enable generate-sample: true option, the codegen would do two things for you:
- Add samples metadata in
tsconfig.jsonandpackage.json. - Generate a collection of TypeScript sample files (based on
x-ms-examplesin OpenAPI specs) undersamples-devfolder.
Please notice that the generated samples might not be directly usable as runnable codes, however, we could get the basic idea on how code works, and update them to be more valuable samples.
And the errors may come from two kinds, the codegen issue or swagger example issue. For the former one, we need to report them with codegen owner while as for the latter one we need to fix our swagger examples.
Now, you can generate both JavaScript and TypeScript workable samples with the following commands.
cd ${PROJECT_ROOT}
npx dev-tool samples publish -f
You will see the workable samples in the ${PROJECT_ROOT}/samples folder.
Besides the generated samples, we also recommend you to add your HERO sample scenarios per your services to guide customers on how to use your library. You could refer to the samples of MapsRouteClient here as an example.
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} && pnpm format
Also we'll recommend you to run lint command to analyze your code and quickly find any problems.
cd ${PROJECT_ROOT} && pnpm lint
And we could use lint:fix if there are any errors.
cd ${PROJECT_ROOT} && pnpm lint:fix
How to do customizations
You may want to do your customizations based on generated code. We collect some common customization cases and you can read Customization on the RLC rest-level client libraries for more details.
How to create package
Now, we can use the exact same steps to build an releasable artifact.
pnpm install
pnpm turbo build --filter=<your-package-name>... --token 1
cd <your-sdk-folder>
export TEST_MODE=record && pnpm test
pnpm 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-rest-agrifood-farming
safeName: azurerestagrifoodfarming
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-rest/agrifood-farming, so the relevant Artifacts name is azure-rest-agrifood-farming.
Prepare PR
The codegen 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
Please ensure that your test recordings are committed together with your code.
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. 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.