|
| 1 | +# Contributor Onboarding |
| 2 | +Thank you for taking the time to contribute to Durable Functions in [Python](https://www.python.org/) |
| 3 | + |
| 4 | +## Table of Contents |
| 5 | + |
| 6 | +- [What should I know before I get started?](#what-should-i-know-before-i-get-started) |
| 7 | +- [Pre-requisites](#pre-requisites) |
| 8 | +- [Pull Request Change Flow](#pull-request-change-flow) |
| 9 | +- [Development Setup](#development-setup) |
| 10 | +- [Pre Commit Tasks](#pre-commit-tasks) |
| 11 | +- [Continuous Integration Guidelines & Conventions](#continuous-integration-guidelines-&-conventions) |
| 12 | +- [Getting Help](#getting-help) |
| 13 | + |
| 14 | +## What should I know before I get started |
| 15 | +- [Durable Functions Overview](https://docs.microsoft.com/en-us/azure/azure-functions/durable/durable-functions-overview) |
| 16 | +- [Durable Functions Application Patterns](https://docs.microsoft.com/en-us/azure/azure-functions/durable/durable-functions-overview?tabs=csharp#application-patterns) |
| 17 | +- [Azure Functions Python Overview](https://docs.microsoft.com/en-us/azure/azure-functions/functions-create-first-azure-function-azure-cli?tabs=bash%2Cbrowser&pivots=programming-language-python) |
| 18 | + |
| 19 | +## Pre-requisites |
| 20 | + |
| 21 | +- OS |
| 22 | + - MacOS (or) Windows10 Ubuntu WSL |
| 23 | +- Language Runtimes |
| 24 | + - .NET Core 2.0 |
| 25 | + - \>= Python 3.6.x |
| 26 | + |
| 27 | +Note: Some ML libraries may not be compatible with newer Python versions. Make sure the library is compatible with the Python version. |
| 28 | + |
| 29 | +- Editor |
| 30 | + - Visual Studio Code |
| 31 | +- Python 3 Tools (pip install) |
| 32 | + - [pytest](https://docs.pytest.org/en/latest/) |
| 33 | + - [nox](https://nox.thea.codes/en/stable/) |
| 34 | +- Azure Tools |
| 35 | + - [Azure Storage Emulator](https://docs.microsoft.com/en-us/azure/storage/common/storage-use-emulator) (or) [Create a storage account in Azure](https://docs.microsoft.com/en-us/azure/storage/common/storage-account-create?tabs=azure-portal) |
| 36 | + - [Azure Functions Core Tools](https://github.com/Azure/azure-functions-core-tools) v2.7.x and above. |
| 37 | + - [Azure Storage Explorer](https://azure.microsoft.com/en-us/features/storage-explorer/) |
| 38 | + |
| 39 | + |
| 40 | +## Pull Request Change flow |
| 41 | + |
| 42 | +The general flow for making a change to the library is: |
| 43 | + |
| 44 | +1. 🍴 Fork the repo (add the fork via `git remote add me <clone url here>` |
| 45 | +2. 🌳 Create a branch for your change (generally branch from dev) (`git checkout -b my-change`) |
| 46 | +3. 🛠 Make your change |
| 47 | +4. ✔️ Test your change |
| 48 | +5. ⬆️ Push your changes to your fork (`git push me my-change`) |
| 49 | +6. 💌 Open a PR to the dev branch |
| 50 | +7. 📢 Address feedback and make sure tests pass (yes even if it's an "unrelated" test failure) |
| 51 | +8. 📦 [Rebase](https://git-scm.com/docs/git-rebase) your changes into meaningful commits (`git rebase -i HEAD~N` where `N` is commits you want to squash) |
| 52 | +9. :shipit: Rebase and merge (This will be done for you if you don't have contributor access) |
| 53 | +10. ✂️ Delete your branch (optional) |
| 54 | + |
| 55 | +## Development Setup |
| 56 | + |
| 57 | +### Visual Studio Code Extensions |
| 58 | + |
| 59 | +The following extensions should be installed if using Visual Studio Code for debugging: |
| 60 | + |
| 61 | +- Python support for Visual Studio Code (Python for VSCode extension) |
| 62 | +- Azure Functions Extensions for Visual Studio Code v0.19.1 and above. |
| 63 | +- autoDocString to generate documentation strings for Python API definitions. |
| 64 | + |
| 65 | +### Python Virtual Environment |
| 66 | + |
| 67 | +- Make sure a Python virtual environment is setup. If you are using VS Code, the Azure Functions Extension project will set one up for you. Alternately, you can set it up through command line as well. |
| 68 | +Note: Conda based environments are not yet supported in Azure Functions. |
| 69 | + |
| 70 | +### Setting up durable-py debugging |
| 71 | + |
| 72 | + |
| 73 | +1. Git clone your fork and use any starter sample from this [folder] in your fork (https://github.com/Azure/azure-functions-durable-python/tree/dev/samples/) and open this folder in your VS Code editor. |
| 74 | + |
| 75 | +2. Initialize this folder as an Azure Functions project using the VS Code Extension using these [instructions](https://docs.microsoft.com/en-us/azure/azure-functions/functions-create-first-function-vs-code?pivots=programming-language-python). This step will create a Python virtual environment if one doesn't exist already. |
| 76 | + |
| 77 | +3. Add a local.settings.json file |
| 78 | + |
| 79 | +``` |
| 80 | +{ |
| 81 | + "IsEncrypted": false, |
| 82 | + "Values": { |
| 83 | + "AzureWebJobsStorage": "<your connection string>", |
| 84 | + "FUNCTIONS_WORKER_RUNTIME": "python" |
| 85 | + } |
| 86 | +} |
| 87 | +``` |
| 88 | + |
| 89 | +4. Add a host.json file that looks like this |
| 90 | + |
| 91 | +``` |
| 92 | +{ |
| 93 | + "version": "2.0", |
| 94 | + "extensionBundle": { |
| 95 | + "id": "Microsoft.Azure.Functions.ExtensionBundle", |
| 96 | + "version": "[1.*, 2.0.0)" |
| 97 | + } |
| 98 | +} |
| 99 | +``` |
| 100 | + |
| 101 | +5. Optionally, if you want to specify a custom task hub name, say MyTaskHub, you can add that in the host.json file like this: |
| 102 | + |
| 103 | +``` |
| 104 | +{ |
| 105 | + "version": "2.0", |
| 106 | + "extensions": { |
| 107 | + "durableTask": { |
| 108 | + "hubName": "MyTaskHub" |
| 109 | + } |
| 110 | + }, |
| 111 | + "extensionBundle": { |
| 112 | + ... |
| 113 | + } |
| 114 | +} |
| 115 | +``` |
| 116 | + |
| 117 | +6. For debugging, install the code using an editable pip install like this, in the VS Code Terminal: |
| 118 | + |
| 119 | +``` |
| 120 | +pip install -e $REPOSITORY_ROOT/ |
| 121 | +``` |
| 122 | +where REPOSITORY_ROOT is the root folder of the azure-functions-durable-python repository |
| 123 | + |
| 124 | +7. Set breakpoints and click Run -> Start Debugging in VS Code. This should internally start the Azure Function using `func host start` command. |
| 125 | + |
| 126 | +### Debugging end-to-end |
| 127 | + |
| 128 | +If you want to debug into the Durable Task or any of the .NET bits, follow instructions below: |
| 129 | + |
| 130 | +1. Open the Azure Storage Explorer and connect to the local storage emulator or the storage account you are using. |
| 131 | +2. Make sure the Durable Python debugging is setup already and the debugger has started the `func` process. |
| 132 | +3. In the VSCode editor for DurableTask, click Debug -> .NET Core Attach Process and search for `func host start` process and attach to it. |
| 133 | +4. Add a breakpoint in both editors and continue debugging. |
| 134 | + |
| 135 | +## Testing changes locally (Windows) |
| 136 | + |
| 137 | +Follow all the steps above, use the Azure Storage Emulator for windows to simulate the storage account, and use Visual Studio to debug the .NET Durable Extension. |
| 138 | + |
| 139 | +## Pre Commit Tasks |
| 140 | + |
| 141 | +This library uses nox tooling for running unit tests and linting. |
| 142 | + |
| 143 | +Make sure nox is pre-installed: |
| 144 | +`pip install nox` |
| 145 | + |
| 146 | +### Running unit tests |
| 147 | + |
| 148 | +1. Add your unit tests under ./tests folder |
| 149 | +2. Run: `nox --sessions tests` |
| 150 | + |
| 151 | +### Running flake8 and flake8-docstring |
| 152 | + |
| 153 | +Run: `nox --sessions lint` |
| 154 | + |
| 155 | +This library uses [numpy docstring convention](https://numpydoc.readthedocs.io/en/latest/format.html) for code documentation. |
| 156 | + |
| 157 | + |
| 158 | +## Continuous Integration Guidelines & Conventions |
| 159 | + |
| 160 | +This project uses a combination of Azure DevOps and GitHub Actions for CI/CD. |
| 161 | + |
| 162 | +- For each PR request/merge, a continuous integration pipeline will run internally that performs linting and running unit tests on your PR/merge. |
| 163 | +- A GitHub Action will also perform CI tasks against your PR/merge. This is designed to provide more control to the contributor. |
| 164 | +- Releases into PyPI will be curated and performed by a CD pipeline internally. See the Getting Help Section to request a release. |
| 165 | + |
| 166 | +## Getting help |
| 167 | + |
| 168 | + - Leave comments on your PR and @username for attention |
| 169 | + |
| 170 | +### Requesting a release |
| 171 | +- If you need a release into PyPI, request it by raising an issue and tagging @anthonychu or @davidmrdavid |
| 172 | + |
| 173 | + |
0 commit comments