-
Notifications
You must be signed in to change notification settings - Fork 3.3k
[Communication] - SDK - Added contributing file #18018
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
jbeauregardb
merged 4 commits into
Azure:master
from
jbeauregardb:communication-contributing-file
Apr 20, 2021
Merged
Changes from 1 commit
Commits
Show all changes
4 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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 the package has been installed on your machine, let's jump on how to run the tests to see that everything is in order. | ||
|
|
||
| ## Testing | ||
|
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. We should have a reference to the general doc for live tests here |
||
|
|
||
| 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 | ||
|
jbeauregardb marked this conversation as resolved.
Outdated
|
||
|
|
||
| To run the tests in PLAYBACK mode, set an environment variable called `AZURE_TEST_RUN_LIVE` and set its 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 | ||
|
JoshuaLai marked this conversation as resolved.
Outdated
|
||
|
|
||
| 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. | ||
|
JoshuaLai marked this conversation as resolved.
Outdated
|
||
|
|
||
| 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. | ||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.