Skip to content

Latest commit

 

History

History
141 lines (97 loc) · 6.07 KB

CONTRIBUTING.md

File metadata and controls

141 lines (97 loc) · 6.07 KB
Raw

Contributing to Azure AI Samples

This repository is entirely open source and welcomes contributions! These are official examples for Azure AI used throughout documentation. Please read through the contributing guide below to avoid frustration!

Contributor License Agreement

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.

Code of Conduct

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Help us keep this project open and inclusive. Please read and follow our Code of Conduct.

Submitting a Pull Request (PR)

Before Making Code Changes

  1. Search the repository for an open or closed PR that relates to your submission. You don't want to duplicate effort.

  2. Determine whether this repository is the best place for the contribution.

    Goals: This repository contains notebooks and sample code that demonstrate how to develop and manage AI workflows using Azure AI. The samples in this repository should allow users to try out Azure AI scenarios from their local machine.

    Non-goals: This repository is not the place for long-form textual documentation. Documentation resources containing minimal or no code should be added in the azure-docs repository.

Making your Code Changes

Set up your development environment (one time setup)

1. Make a fork

This repository follows a fork-based workflow. You should make your changes on your own fork, and make a PR to contribute your changes.

  1. Make a fork of this repository.

  2. Clone your fork

  3. Add the original repository as a remote:

    git remote add upstream https://github.com/Azure-Samples/azureai-samples.git
2. Install Dev Dependencies

From the root of your local repository, run:

python -m pip install -r dev-requirements.txt
3. Set up pre-commit

pre-commit is a tool that enables us to run code when committing to a local repository. We use this to automate running code formatters, linters, etc...

To install pre-commit in the repository, run the following from the root of the repository:

pre-commit install

pre-commit will run automatically when you commit changes, but you can also manually run it using pre-commit run --all-files.

Write your contribution

If you are writing/updating a sample, please follow this guidance on how the samples should be structured.

Note that samples are organized by scenario, find the one best-suited for your sample or propose a new one for consideration.

  • Please create a separate directory for each authored sample, making sure to create it under the appropriate top-level scenario directory. Each sample's directory should contain:
    • A descriptive README in the root folder of your sample following the README template.
    • Your sample
    • Any other supporting files for your sample (datasets, scripts, etc...). Samples should ideally only depend on files within their directory.

Submit your pull request

  • Commit your changes using a descriptive commit message
  • Push your changes to your fork.
  • Create a pull request
  • Review the checklist in the PR.
  • If we suggest changes then:

    • Make the required updates.

    • Rebase your fork and force push to your GitHub repository (this will update your Pull Request):

      git rebase master -i
git push -f

That's it! Thank you for your contribution!

Important

You should expect to budget time to engage with reviewers (responding to comments, fixing PR checks) before your PR is merged in. This is especially relevant if your contribution is time-sensitive.

Adhering to the guidance in this document (i.e using pre-commit, using provided templates) will help expedite the review process.

Discoverability

Examples in this repository can be indexed in the Microsoft code samples browser, enabling organic discoverability. To accomplish this, add the required YAML frontmatter at the top of the README.md

The YAML frontmatter format looks like this:

---
page_type: sample
languages:
- language1
- language2
products:
- ai-services
description: Example description.
---

Edit the product, description, and languages as needed.

  • You can find all valid product options here.
  • You can find valid language options here.

The Code Samples browser content is updated twice a week, so it may take a few days for your changes to be reflected.