Contributing to autorest.python

Contributing to autorest.python

First off, we want to thank all of the autorest.python contributors. We are an open-source project, so all are welcome to contribute, and we greatly appreciate the help we receive from contributors!

In this doc, we outline all the steps needed to create a PR and contribute to this repo

1. Cloning and Setting Up the Repo
2. Writing Code
3. Generating AutoRest with your code changes
4. Testing your generated code
5. Making your PR

Cloning and Setting Up the Repo

1. Run npm install -g autorest to install autorest on your computer if you don't have it.
2. Make sure your Python version is 3.6 and above.
3. Clone our autorest.python repo. You may choose to fork the autorest.python repo and clone your fork instead. Our default branch, and the branch that contains the code we publish is autorestv3.
4. Run npm install at the root of your cloned repo.
5. Activate the virtual environment venv that the previous step created at the root of your repo. This virtual environment has all of the dependencies needed to write and generate code in the repo code.

Writing Code

1. Make sure the venv virtual environment is activated
2. Create your own feature branch from the default autorestv3 branch and put all of your code in here.
3. There are 6 submodules in the autorest folder. However, you are almost guaranteed to be writing code in the codegen submodule. This handles all of the code that generates an SDK. There is a small chance you may be also writing code in the multiapi submodule, which handles the multiapiscript we run to generate a MultiApi SDK.
4. Make sure all of the new files you add have the Microsoft MIT license header

Generating AutoRest with your code changes

You have a couple options when generating code. We use the invoke library to generate

Command	Output Description	Output Folder
inv regenerate	Regenerates all test swaggers with both our legacy (current published) generator and our low level generator.	All of the Expected/AcceptanceTests folders in the test folder. For example: Vanilla low level generates in test/vanilla/llc/Expected/AcceptanceTests
inv regenerate --version-tolerant	Regenerate all of the test swaggers with our version tolerant generator.	test/azure/version-tolerant/Expected/AcceptanceTests etc
inv regenerate --legacy	Regenerate all of the test swaggers with our legacy (current published) generator.	test/azure/legacy/Expected/AcceptanceTests, test/vanilla/legacy/Expected/AcceptanceTests and test/multiapi/Expected/AcceptanceTests
inv regenerate --llc	Regenerate all of the test swaggers with our LLC generation	test/azure/llc/Expected/AcceptanceTests, test/vanilla/llc/Expected/AcceptanceTests

Debugging Generation

These flags can also be added to your command for debugging and more specialized generation

Flag	Output
--swagger-name={}	Regenerate only a specific swagger. For example, if you only want to generate the BodyComplex swagger, include --swagger-name=BodyComplex to your command line
--debug	Debug your generation. If debugging in VSCode, add this to your launch configuration first

Testing your generated code

You can find all of our tests of the generated code in folders that start with Acceptance.

Test Type	Folder
Vanilla Legacy	test/vanilla/legacy/AcceptanceTests
Vanilla Low Level	test/vanilla/llc/AcceptanceTests
Azure Legacy	test/azure/legacy/AcceptanceTests
Azure Low Level	test/azure/llc/AcceptanceTests
Multiapi	test/multiapi/AcceptanceTests
Unittests	test/unittests

Writing your Tests

1. If adding a new test file, make sure you mark it with the Microsoft MIT license header
2. In vast majority of cases, if you are adding a test, you will need to add it's async counterpart as well. Sync tests reside at the root of the AcceptanceTests folder, whil async tests reside in AcceptanceTests/asynctests
3. Use fixtures where possible to decompose and organize your test work

Running your Tests

1. Create a new and activate a virtual environment inside every test folder. For example, create virtual environment vanilla_legacy_test_venv in test/vanilla/legacy. Note: Do not use the root venv as your test virtual environment. You should be creating a new virtual environment for every test folder. Each virtual environment should only have the requirements for testing.
2. pip install -r requirements.txt to get all of the specific requirements for that test folder
3. Run with pytest
4. You can also debug with your editor of choice. Just make sure your python interpreter is the virtual environment you created in step 1

Making your PR

1. Run pylint autorest and mypy autorest from the root folder, to make sure your code is linted and typed well
2. Run inv regenerate again to make sure all of the test swaggers are regenerated with your fix
3. Run the tests in our various test folders
4. If your change is a bug fix / new feature, add it to the Changelog. Please include the PR number in your description, and make sure the min version table is present. Additionally, tag yourself as fixing this issue! You deserve all the credit!
5. If you have to bump any of the dependencies of the generator or the generated code, please edit the min version table, and the Minimum Dependencies of Your Client documentation
6. Push to either autorest.python or your fork of autorest.python and create your PR! Tag @iscai-msft, @lmazuel, and / or @msyyc for review
7. Once pushed, our CI will start running. If you have to make any changes to fix the CI or because of PR comments, make sure you repeat steps 1-3 before pushing you changes.

And on a final note, thank you so much again for your contribution! It really means a lot to us!