Skip to content

Latest commit

 

History

History
237 lines (149 loc) · 11.8 KB

CONTRIBUTING.md

File metadata and controls

237 lines (149 loc) · 11.8 KB

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct.For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments

How to contribute to the Azure TypeScript SDK generator project

There are many ways that you can contribute to the Azure TypeScript SDK generator project:

  • Submit a bug
  • Submit a code fix for a bug
  • Submit additions or modifications to the documentation
  • Submit a feature request

All code submissions will be reviewed and tested by the team, and those that meet a high bar for both quality and design/roadmap appropriateness will be merged into the source. Be sure to follow the existing file/folder structure when adding new boards or sensors.

If you encounter any bugs please file an issue in the Issues section of the project.

Things to keep in mind when contributing

Some guidance for when you make a contribution:

  • Add/update unit tests and code as required by your change
  • Make sure you run all the unit tests on the affected platform(s)/languages. If the change is in common code, generally running on one platform would be acceptable.
  • Run end-to-end tests or simple sample code to make sure the lib works in an end-to-end scenario.

Big contributions

If your contribution is significantly big it is better to first check with the project developers in order to make sure the change aligns with the long term plans. This can be done simply by submitting a question via the GitHub Issues section.

Want to get started hacking on the code? Great! Keep reading. This contributing guide helps you to start working with and contributing to the Azure Typescript/Javascript SDK Generator.

General Autorest generation design

TBA

Typescript/Javascript SDK generator Design

The generated Typescript/Javascript SDK has the following structure:

  1. Client (Handled by clientFileGenerator.ts)
  2. Client Context (Handled by clientContextFileGenerator.ts)
  3. Operation Interfaces (Handled by operationInterfaceGenerator.ts)
  4. Operations (Handled by operationGenerator.ts)
  5. Models (Handled by modelsGenerator.ts)
  6. Parameters (Handled by parametersGenerator.ts)
  7. Index File (Handled by indexGenerator.ts)
  8. Metadata (Handled here)

The entry point for this design is at main.ts which invokes the typescriptGenerator.ts and starts the entire generation process. You could find all the options that could be sent to the generator at autorestOptions.ts

On a high level, the entire SDK generation process would be:

Swagger Input -> Autorest Core & Modeler -> CodeModel -> TS/JS SDK Generator -> Generated SDK

Within the TS/JS SDK Generator, it has the following stages:

CodeModel + User Options -> Transform CodeModel -> Generate Client -> Generate Client Context -> Generate Operations/Interfaces -> Generate Models -> Generate Parameters -> Generate Index -> Format & Output Generated SDK

Steps to clone, build & test

  1. Use the following command to clone the Typescript/Javascript SDK generator repository:
git clone https://github.com/Azure/autorest.typescript.git
  1. Use the following commands to build the SDK generator:
npm install -g @autorest/autorest
cd autorest.typescript
npm install
npm run build
  1. There are 3 test-suites in the generator:
    1. Unit tests (which could be found at test/unit/*)
    2. Integration tests (which could be found at test/integration/*)
    3. Smoke tests
    4. Version Tolerence Tests
  2. You can run the Unit tests & Integration tests using the following command:
npm run test

Running the command above will do the following things:

  • Start TestServer
  • Build Autorest.Typescript
  • Generate all scenarios in parallel (i.e. BodyString, BodyComplex, Url, CustomUrl, Header, XmlService
  • Run all the tests under test/integration
  • Stop TestServer

Note: If your development environment is Windows, then run the command npm run start-test-server:v2(in a seperate window) before running npm run test and run the command npm run stop-test-server after. (In non windows machines, we could run the test-server in the background automatically. But, in Windows machines, it has to be done manually.)

  1. You can run the Smoke tests using the following command:
npm run clone:specs
npm run smoke-test

Note: If the command npm run clone:specs errors out with the following error:

fatal: destination path './.tmp/specs' already exists and is not an empty directory.

delete the .tmp folder and then try again.

Version Tolerence Tests

Version tolerance tests provide coverage against unexpected breaking changes when generating a newer version of a swagger. RLCs are not expected to produce breaking changes unless the swagger itself has an API breaking change.

Version Tolerance tests would generate 2 clients one from an initial Swagger and a second from the updated swagger that contains changes that are not expected to generate breaking changes. The same set of tests is run against both generated clients to make sure no breaking changes resulted.

Version Tolerance tests have the following npm scripts:

  • npm run validate-version-tolerance: generates SDKs and tests for breaking changes between swagger versions
  • generate-version-tolerance: Generates version tolerance before and after sdks
  • generate-version-tolerance:tests: generates updated spec.ts based on hand written tests against the initial SDK
  • test-version-tolerance: executes all .spec.ts tests under test/version-tolerance/

In CI we'll run npm run validate-version-tolerance which calls all the other npm scripts. The other individual npm scripts are useful for development.

For more details on the implementation see #1268

How to add an integration test case

Whenever you work on adding a feature/fixing a bug, this would probably be your first step. You create a test case and then run it through the generator, see the result, modify the generator, run it again and so on, until you get the desired output.

  1. Create your test input. Below are some examples
    1. A simple Swagger/OpenAPI file)
    2. A standalone configuration markup file (pointing to Swagger file somewhere else)
    3. A combination of configuration markup file and Swagger/OpenAPI file.

Let us say your test input will be called testUserCase.json.

  1. Now add the test input to the integration test suite to the file test-swagger-gen.ts. In the file, add the following to the array testSwaggers:
testUserCase: {
    swaggerOrConfig: "test/integration/swaggers/testUserCase.json",
    clientName: "TestUserCaseClient",
    packageName: "test-user-case",
    licenseHeader: true,
    useCoreV2: true,
    allowInsecureConnection: true,
    addCredentials: false
},
  1. Now, You can generate the SDK only for your test case with the following command: (Initially, during your development, you do not want to run all the cases during every step of your development. But, once your code changes are complete for your case, then you need to run the entire suite to ensure that your changes did not cause any unwanted changes.)
npm run generate-swaggers -- -b -i testUserCase
  1. Once you are satisfied with the generated code, you can add a spec file such as testUserCase.spec.ts file here. You can find several examples in the same place.

How to debug an integration test case

generate-swaggers step

If you would like to debug the generate-swaggers step for our test input, use the following command:

npm run generate-swaggers -- -b -i testUserCase --debug

Now, the code will wait for the debugger to be attached. Open the repository in VS Code -> Select Run and Debug section -> Click Attach.

Spec file

If you would like to debug the testUserCase.spec.ts file (after the SDK is generated), Open the repository in VS Code -> Open the testUserCase.spec.ts file -> Select Run and Debug section -> Click IntegrationTests - Current File.

How to debug an unit test case

  • In VS Code, We have created a Debugging profile for UnitTests to start debugging:

    1. Go to the debugger tab
    2. Select the "Unit Test" Profile
    3. Click the "Play" button

  • Your breakpoints will start hitting, you can set breakpoints in either Test or Generator code

Integration Tests

  • In order to debug integration tests you need to start the test server, by running:

    npm run start-test-server:v1

  • Once the Test Server is running

    1. In VSCode go to the debugger tab
    2. Select the "IntegrationTests" profile from the drop down
    3. Click the "Play" button

  • **IMPORTANT**: Running Integration Tests for debugging, does not re-generate the test clients so make sure that after each change you do:

    • Re-generate all the test swaggers

      npm run generate-swaggers -- --build

    • Re-generate a specific swagger

      npm run generate-swaggers -- -i bodyComplex -b

Before investing more time investigating

  • Make sure to reset autorest, this will ensure that the versions used by Auotrest Core are the correct ones. This will solve many problems

    autorest --reset

Things to keep in mind when contributing

If your test case is working fine as expected, now you are ready to create the PR. But, before that, make sure you run all the tests (Unit/Integration/Smoke) and ensure there are no unintentional changes. And if there are any changes (intentional) in any of the test cases, include those files also in your PR.

I've made changes to Autorest.Typescript, however when re-generating the library my changes don't seem to have been picked up

  • Make sure to re-build autorest.typescript after any changes you want to test

    npm run build

How to update dependencies in generated package.json files?

Our generated SDKs take dependency on various packages which you can see in the generated package.json files. These will need to be upgraded from time to time to stay on the latest major version so that we get bug fixes automatically due to semver.

  • Update the version of the dependency you are looking for in the methods restLevelPackage and/or regularAutorestPackage in the packageFileGenerator.ts file.
  • Run npm run build && npm run generate-swaggers && npm run smoke-tests to update the generated files in the repo and run smoke tests before creating the PR.

For example, see the PR 1271 that updates the version of prettier that the generated SDKs depend on.