Skip to content

What to do after generating the SDK code with codegen

Jump to bottom
Darren Cohen edited this page Dec 13, 2023 · 4 revisions

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

How to write README.md

README.md is very useful doc for customers to learn more about your service, which appeals to users to use your service and SDK. After generation, please write more info in README.md and you could refer to webpubsub

How to add convenience code

Usually, we don't advise to add convenience code. Instead, we hope you change swagger definition or use directives. But if you have to, please see the following guidance:

How to write tests

You should write tests that ensure all APIs fulfil their contract and algorithms work as specified. This is a requirement of the Azure SDK Guidelines.

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

How to write sample

Samples can make it quicker and easier for customers to use the package. It could be simple which just shows how to use the package; Or it could be a complex scenario example for customers to create their own service quickly.

You should add samples in the samples directory under ${PROJECT_ROOT}. Each sample should have its own folder and contain a Readme.md(example) which introduces simply how to run the sample.

If you want to run sample with dev mode, just run pip install -e .(detail doc) under ${PROJECT_ROOT} instead of pip install azure.myservice.

How to create package

If you want to create a private package, go to ${PROJECT_ROOT} folder and run:

pip install wheel
python setup.py bdist_wheel

Create/Update the ci.yml

Now, if everything looks good to you, you can submit a PR in azure-sdk-for-python 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 sdk/{servicename} folder.

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

# DO NOT EDIT THIS FILE
# This file is generated automatically and any changes will be lost.

trigger:
  branches:
    include:
    - main
    - hotfix/*
    - release/*
    - restapi*
  paths:
    include:
    - sdk/{service_name}/

pr:
  branches:
    include:
    - main
    - feature/*
    - hotfix/*
    - release/*
    - restapi*
  paths:
    include:
    - sdk/{service_name}/

extends:
  template: ../../eng/pipelines/templates/stages/archetype-sdk-client.yml
  parameters:
    ServiceDirectory: {service_name}
    Artifacts:
    - name: { package_name }
      safeName: { safeName }

Please change the {service_name}, {package_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 package_name and safeName of yours into that ci.yml.

Usually, safeName is derived from package name by removing all -. For example: webpubwub, purview

Configuring CODEOWNERS

If a new module group is being added, which requires adding a new sub-folder directory under sdk, you'll want to add a new entry to CODEOWNERS. This allows GitHub to automatically assign the specified users as reviewers to all PRs opened against the new module group.

Release

Here is the Release Checklist you should know before release. Once ready, make the PR to https://github.com/Azure/azure-sdk-for-python. After the PR is merged, it is time to release package.

Make PR

DPG 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 quicky, so you need to update the it according to the change of this new version. It is also necessary to update release date like 1.0.0b1 (2022-02-02)(rough time is fine and no need to be very accurate)

Version Number

You shall update the version number according to package version rule

Test recordings

To check whether the new content works well, it is better to run live test. If the result is successful, there shall be recording files(*.yml) updated. Please commit them together with your code.

Fix CI for PR

You may meet the CI failures after submitting the PR, so please refer to How-to-fix-CI to fix it

CC dpg-devs for review

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

cc @Azure/dpg-devs for awareness
Clone this wiki locally