Skip to content

Commit

Permalink
Added contributing file
Browse files Browse the repository at this point in the history
  • Loading branch information
jorge-beauregard committed Apr 13, 2021
1 parent 6b640a4 commit ed83e98
Showing 1 changed file with 51 additions and 0 deletions.
51 changes: 51 additions & 0 deletions sdk/communication/CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
# Contributing Guide

The Azure Communication Services SDK for Python currently consists of 4 different packages. While each package has its own set of environment variables to make their tests run successfully, all of them follow a similar structure that allows a smooth onboarding process.

Let's get started with how to setup the repo itself.

## Installation process

To get started with any of the packages, change directory to the package you want to install and run the `pip install .` command. This will install all of the local files necessary for you to run the corresponding tests. It's important to note that if you made changes to the local files and want to run the tests again, you must run the `pip install .` command from the package root folder to update the files with your new changes.

Once you package has been installed on your machine, let's jump on how to run the tests to see that everything is in order.

## Testing

When you go inside the tests folder of the package you are working with, you will see a folder called `recordings`. This folder contains, as its name suggests, recordings of successful calls to the API that allow us to run the tests in PLAYBACK mode and remove the necessity of hitting the actual resources every time we may want to test.

### PLAYBACK

To run the tests in PLAYBACK mode, set an environment variable called `AZURE_TEST_RUN_LIVE` and set is value to `false` (If the variable if not set, the default will be `false`). After your variable has been set, change directory to the `tests` folder of the package you're working on and run the `pytest .` command.

If the tests are successful, we can proceed to run the tests in LIVE mode.

### LIVE

Because in LIVE mode we are hitting an actual resource, we must set the appropriate environment variable to make sure the code tests against the resource we want. Set up an env variable called `AZURE_COMMUNICATION_SERVICE_CONNECTION_STRING` and set it to the connection string of the resource you want to test against.

Depending on which package you are testing, it may need special environment variables to test succesfully. The names of these variables can be found inside each test file in the `setUp()` function. Make sure to set these variables before running the tests themselves. You may need to restart your development environment after creating or updating these environment variables.

You can run the `pytest .` command after setting the `AZURE_TEST_RUN_LIVE` variable to `true`.

### Managed Identity Tests

If you ran the tests in LIVE mode, you may have noticed that the files inside the recordings folder were updated. If any of the tests failed, you will see the error message right there in the recording file as well as in your terminal logs.

The most probable thing is that the managed identity tests will fail at first. This is because we haven't set up any managed identity credentials for the DefaultAzureCredential object inside the tests to reference to. There are multiple ways of creating a managed identity credential.

One of the easiest ways is to install the Azure CLI and run the `az login` command. If you are listed as a contributor of the resource you are testing against, this should be enough for the DefaultAzureCredential object to get the corresponding Azure Active Directory credentials you need.

Another way to authenticate is to set up 3 environment variables called `AZURE_CLIENT_ID`, `AZURE_TENANT_ID` and `AZURE_CLIENT_SECRET` and set their values to the ones from a registered Azure Active Directory application that is linked to the resource you are testing against.

For a more in-depth look on how to authenticate using managed identity, refer to the [Azure Identity client library for Python](https://docs.microsoft.com/python/api/overview/azure/identity-readme?view=azure-python) documentation. This document also has more ways for you to authenticate using the DefaultAzureCredential object besides the ones we discussed in this contributing file.

## Submitting a PR

The easiest way for you to test and not worry about any breaking changes you may cause is to create a fork from the [Python Azure SDK repo](https://github.com/Azure/azure-sdk-for-python). After downloading your repo, make sure to add the original repo as an upstream. To do this, use the `git remote add upstream` command followed by the repo's URL.

Create a branch for any new feature you may want to add and when your changes are ready, push your branch to the origin. Because the upstream was already set, if you go to the Python Azure SDK repo you will see a message saying that you pushed changes to your fork and give you the option to create a PR from your fork to the original repo.

Make sure to name your PR with the following format when you are ready to submit it: [Communication] - `package-you-are-updating` - `pr-description`.

Additionally, write a good description about what your PR does in the description section of the PR itself. This will help your reviewers have a better understanding of what you tried to accomplish in your PR.

0 comments on commit ed83e98

Please sign in to comment.