| 1 |
# Contribute Code or Provide Feedback for Azure Data Lake Store Filesystem SDK for Python |
| 2 |
|
| 3 |
This repository contains The Azure Data Lake Store Filesystem SDK for Python that can be consumed for Microsoft Azure applications. |
| 4 |
|
| 5 |
## Basics |
| 6 |
|
| 7 |
If you would like to become an active contributor to this project, please follow the instructions provided in [Microsoft Azure Projects Contribution Guidelines](http://azure.github.io/guidelines/). |
| 8 |
|
| 9 |
## Table of Contents |
| 10 |
|
| 11 |
[Before Starting](#before-starting) |
| 12 |
- [Onboarding](#onboarding) |
| 13 |
- [GitHub Basics](#github-basics) |
| 14 |
- [GitHub Workflow](#github-workflow) |
| 15 |
- [Forking the Azure/azure-data-lake-store-python repository](#forking-the-azureazure-data-lake-store-python-repository) |
| 16 |
- [Code of Conduct](#code-of-conduct) |
| 17 |
|
| 18 |
[Filing Issues](#filing-issues) |
| 19 |
|
| 20 |
[Making Changes](#making-changes) |
| 21 |
- [Pull Requests](#pull-requests) |
| 22 |
- [Pull Request Guidelines](#pull-request-guidelines) |
| 23 |
- [Cleaning up commits](#cleaning-up-commits) |
| 24 |
- [Breaking changes](#breaking-changes) |
| 25 |
- [General guidelines](#general-guidelines) |
| 26 |
- [Testing guidelines](#testing-guidelines) |
| 27 |
|
| 28 |
## Before Starting |
| 29 |
|
| 30 |
### Onboarding |
| 31 |
|
| 32 |
Before cloning this repository, please make sure you have started in our [documentation repository](https://github.com/Azure/adx-documentation-pr) (you will only have access to that page if you are part of the Azure organization). |
| 33 |
|
| 34 |
### GitHub Basics |
| 35 |
|
| 36 |
#### GitHub Workflow |
| 37 |
|
| 38 |
If you don't have experience with Git and GitHub, some of the terminology and process can be confusing. [Here is a guide to understanding the GitHub flow](https://guides.github.com/introduction/flow/) and [here is a guide to understanding the basic Git commands](https://services.github.com/kit/downloads/github-git-cheat-sheet.pdf). |
| 39 |
|
| 40 |
### Forking the Azure/azure-data-lake-store-python repository |
| 41 |
|
| 42 |
Unless you are working with multiple contributors on the same file, we ask that you fork the repository and submit your pull request from there. [Here is a guide to forks in GitHub](https://guides.github.com/activities/forking/). |
| 43 |
|
| 44 |
### Code of Conduct |
| 45 |
|
| 46 |
This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [[email protected]](mailto:[email protected]) with any additional questions or comments. |
| 47 |
|
| 48 |
## Filing Issues |
| 49 |
|
| 50 |
You can find all of the issues that have been filed in the [Issues](https://github.com/Azure/azure-data-lake-store-python/issues) section of the repository. |
| 51 |
|
| 52 |
If you encounter any bugs with Azure Data Lake Store Filesystem SDK for Python, or would like to request a feature, please file an issue [here](https://github.com/Azure/azure-data-lake-store-python/issues/new). |
| 53 |
|
| 54 |
You can find the dates for the next three sprints for Azure Data Lake Store Filesystem SDK for Python in the [Milestones](https://github.com/Azure/azure-data-lake-store-python/milestones) section of the Issue page. Each milestone will display the issues that are being worked on for each corresponding sprint. |
| 55 |
|
| 56 |
## Making Changes |
| 57 |
|
| 58 |
### Pull Requests |
| 59 |
|
| 60 |
You can find all of the pull requests that have been opened in the [Pull Request](https://github.com/Azure/azure-data-lake-store-python/pulls) section of the repository. |
| 61 |
|
| 62 |
To open your own pull request, click [here](https://github.com/Azure/azure-data-lake-store-python/compare). When creating a pull request, keep the following in mind: |
| 63 |
- Make sure you are pointing to the fork and branch that your changes were made in |
| 64 |
- Choose the correct branch you want your pull request to be merged into |
| 65 |
- The **AutoRest** branch is for code generated from AutoRest |
| 66 |
- The **master** branch is for code generated from Hyak; code in this branch is in support mode only |
| 67 |
- The **Fluent** branch is for the next generation of Azure SDK Management libraries that implement Fluent interfaces |
| 68 |
- The pull request template that is provided **should be filled out**; this is not something that should just be deleted or ignored when the pull request is created |
| 69 |
- Deleting or ignoring this template will elongate the time it takes for your pull request to be reviewed |
| 70 |
- The SLA for reviewing pull requests is **two business days** |
| 71 |
|
| 72 |
### Pull Request Guidelines |
| 73 |
|
| 74 |
A pull request template will automatically be included as a part of your PR. Please fill out the checklist as specified. Pull requests **will not be reviewed** unless they include a properly completed checklist. |
| 75 |
|
| 76 |
#### Cleaning up Commits |
| 77 |
|
| 78 |
If you are thinking about making a large change to your SDK, **break up the change into small, logical, testable chunks, and organize your pull requests accordingly**. |
| 79 |
|
| 80 |
Often when a pull request is created with a large number of files changed and/or a large number of lines of code added and/or removed, GitHub will have a difficult time opening up the changes on their site. This forces the Azure Data Lake Store Filesystem SDK for Python team to use separate software to do a code review on the pull request. |
| 81 |
|
| 82 |
If you find yourself creating a pull request and are unable to see all the changes on GitHub, we recommend **splitting the pull request into multiple pull requests that are able to be reviewed on GitHub**. |
| 83 |
|
| 84 |
If splitting up the pull request is not an option, we recommend **creating individual commits for different parts of the pull request, which can be reviewed individually on GitHub**. |
| 85 |
|
| 86 |
For more information on cleaning up the commits in a pull request, such as how to rebase, squash, and cherry-pick, click [here](https://github.com/Azure/azure-powershell/blob/dev/documentation/cleaning-up-commits.md). |
| 87 |
|
| 88 |
#### Breaking Changes |
| 89 |
|
| 90 |
Breaking changes should **not** be introduced into the repository without giving customers at least six months notice. For a description of breaking changes in Azure Data Lake Store Filesystem SDK for Python, see [here](https://github.com/Azure/azure-data-lake-store-python/blob/master/.github/breaking-changes.md) |
| 91 |
|
| 92 |
#### General guidelines |
| 93 |
|
| 94 |
The following guidelines must be followed in **EVERY** pull request that is opened. |
| 95 |
|
| 96 |
- Title of the pull request is clear and informative |
| 97 |
- There are a small number of commits that each have an informative message |
| 98 |
- A description of the changes the pull request makes is included |
| 99 |
- All files have the Microsoft copyright header |
| 100 |
- The pull request does not introduce [breaking changes](https://github.com/Azure/azure-data-lake-store-python/blob/master/.github/breaking-changes.md) |
| 101 |
|
| 102 |
#### Testing Guidelines |
| 103 |
|
| 104 |
The following guidelines must be followed in **EVERY** pull request that is opened. |
| 105 |
|
| 106 |
- Pull request includes test coverage for the included changes |