|
| 1 | +# Contributing Guidelines |
| 2 | + |
| 3 | +Thank you for your interest in contributing to our project. Whether it's a bug report, new feature, correction, or additional |
| 4 | +documentation, we greatly value feedback and contributions from our community. |
| 5 | + |
| 6 | +Please read through this document before submitting any issues or pull requests to ensure we have all the necessary |
| 7 | +information to effectively respond to your bug report or contribution. |
| 8 | + |
| 9 | + |
| 10 | +## Table of Contents |
| 11 | + |
| 12 | +* [Table of Contents](#table-of-contents) |
| 13 | +* [Reporting Bugs/Feature Requests](#reporting-bugsfeature-requests) |
| 14 | +* [Contributing via Pull Requests (PRs)](#contributing-via-pull-requests-prs) |
| 15 | + * [Pulling Down the Code](#pulling-down-the-code) |
| 16 | + * [Running the Unit Tests](#running-the-unit-tests) |
| 17 | + * [Running the Integration Tests](#running-the-integration-tests) |
| 18 | + * [Making and Testing Your Change](#making-and-testing-your-change) |
| 19 | + * [Committing Your Change](#committing-your-change) |
| 20 | + * [Sending a Pull Request](#sending-a-pull-request) |
| 21 | +* [Finding Contributions to Work On](#finding-contributions-to-work-on) |
| 22 | +* [Code of Conduct](#code-of-conduct) |
| 23 | +* [Security Issue Notifications](#security-issue-notifications) |
| 24 | +* [Licensing](#licensing) |
| 25 | + |
| 26 | +## Reporting Bugs/Feature Requests |
| 27 | + |
| 28 | +We welcome you to use the GitHub issue tracker to report bugs or suggest features. |
| 29 | + |
| 30 | +When filing an issue, please check [existing open](https://github.com/aws/aws-step-functions-data-science-sdk-python/issues) and [recently closed](https://github.com/aws/aws-step-functions-data-science-sdk-python/issues?utf8=%E2%9C%93&q=is%3Aissue%20is%3Aclosed%20) issues to make sure somebody else hasn't already |
| 31 | +reported the issue. Please try to include as much information as you can. Details like these are incredibly useful: |
| 32 | + |
| 33 | +* A reproducible test case or series of steps. |
| 34 | +* The version of our code being used. |
| 35 | +* Any modifications you've made relevant to the bug. |
| 36 | +* A description of your environment or deployment. |
| 37 | + |
| 38 | + |
| 39 | +## Contributing via Pull Requests (PRs) |
| 40 | + |
| 41 | +Contributions via pull requests are much appreciated. |
| 42 | + |
| 43 | +Before sending us a pull request, please ensure that: |
| 44 | + |
| 45 | +* You are working against the latest source on the *master* branch. |
| 46 | +* You check the existing open and recently merged pull requests to make sure someone else hasn't already addressed the problem. |
| 47 | +* You open an issue to discuss any significant work - we would hate for your time to be wasted. |
| 48 | + |
| 49 | +### Pulling Down the Code |
| 50 | + |
| 51 | +1. If you do not already have one, create a GitHub account by following the prompts at [Join Github](https://github.com/join). |
| 52 | +1. Create a fork of this repository on GitHub. You should end up with a fork at `https://github.com/<username>/aws-step-functions-data-science-sdk-python`. |
| 53 | + 1. Follow the instructions at [Fork a Repo](https://help.github.com/en/articles/fork-a-repo) to fork a GitHub repository. |
| 54 | +1. Clone your fork of the repository: `git clone https://github.com/<username>/aws-step-functions-data-science-sdk-python` where `<username>` is your github username. |
| 55 | + |
| 56 | + |
| 57 | +### Running the Unit Tests |
| 58 | + |
| 59 | +1. Install tox using `pip install tox` |
| 60 | +1. Install test dependencies, including coverage, using `pip install .[test]` |
| 61 | +1. cd into the aws-step-functions-data-science-sdk-python folder: `cd aws-step-functions-data-science-sdk-python` or `cd /environment/aws-step-functions-data-science-sdk-python` |
| 62 | +1. Run the following tox command and verify that all code checks and unit tests pass: `tox tests/unit` |
| 63 | + |
| 64 | +You can also run a single test with the following command: `tox -e py36 -- -s -vv <path_to_file><file_name>::<test_function_name>` |
| 65 | + * Note that the coverage test will fail if you only run a single test, so make sure to surround the command with `export IGNORE_COVERAGE=-` and `unset IGNORE_COVERAGE` |
| 66 | + * Example: `export IGNORE_COVERAGE=- ; tox -e py36 -- -s -vv tests/unit/test_sagemaker_steps.py::test_training_step_creation_with_model ; unset IGNORE_COVERAGE` |
| 67 | + |
| 68 | + |
| 69 | +### Running the Integration Tests |
| 70 | + |
| 71 | +Our CI system runs integration tests (the ones in the `tests/integ` directory), in parallel, for every Pull Request. |
| 72 | +You should only worry about manually running any new integration tests that you write, or integration tests that test an area of code that you've modified. |
| 73 | + |
| 74 | +1. Follow the instructions at [Set Up the AWS Command Line Interface (AWS CLI)](https://docs.aws.amazon.com/polly/latest/dg/setup-aws-cli.html). |
| 75 | +1. To run a test, specify the test file and method you want to run per the following command: `tox -e py36 -- -s -vv <path_to_file><file_name>::<test_function_name>` |
| 76 | + * Note that the coverage test will fail if you only run a single test, so make sure to surround the command with `export IGNORE_COVERAGE=-` and `unset IGNORE_COVERAGE` |
| 77 | + * Example: `export IGNORE_COVERAGE=- ; tox -e py36 -- -s -vv tests/integ/test_state_machine_definition.py::test_wait_state_machine_creation ; unset IGNORE_COVERAGE` |
| 78 | + |
| 79 | +### Making and Testing Your Change |
| 80 | + |
| 81 | +1. Create a new git branch: |
| 82 | + ```shell |
| 83 | + git checkout -b my-fix-branch master |
| 84 | + ``` |
| 85 | +1. Make your changes, **including unit tests** and, if appropriate, integration tests. |
| 86 | + 1. Include unit tests when you contribute new features or make bug fixes, as they help to: |
| 87 | + 1. Prove that your code works correctly. |
| 88 | + 1. Guard against future breaking changes to lower the maintenance cost. |
| 89 | + 1. Please focus on the specific change you are contributing. If you also reformat all the code, it will be hard for us to focus on your change. |
| 90 | +1. Run all the unit tests as per [Running the Unit Tests](#running-the-unit-tests), and verify that all checks and tests pass. |
| 91 | + 1. Note that this also runs tools that may be necessary for the automated build to pass (ex: code reformatting by 'black'). |
| 92 | + |
| 93 | + |
| 94 | +### Committing Your Change |
| 95 | + |
| 96 | +We use commit messages to update the project version number and generate changelog entries, so it's important for them to follow the right format. Valid commit messages include a prefix, separated from the rest of the message by a colon and a space. Here are a few examples: |
| 97 | +
|
| 98 | +``` |
| 99 | +feature: support VPC config for hyperparameter tuning |
| 100 | +fix: fix flake8 errors |
| 101 | +documentation: add MXNet documentation |
| 102 | +``` |
| 103 | +
|
| 104 | +Valid prefixes are listed in the table below. |
| 105 | +
|
| 106 | +| Prefix | Use for... | |
| 107 | +|----------------:|:-----------------------------------------------------------------------------------------------| |
| 108 | +| `breaking` | Incompatible API changes. | |
| 109 | +| `deprecation` | Deprecating an existing API or feature, or removing something that was previously deprecated. | |
| 110 | +| `feature` | Adding a new feature. | |
| 111 | +| `fix` | Bug fixes. | |
| 112 | +| `change` | Any other code change. | |
| 113 | +| `documentation` | Documentation changes. | |
| 114 | +
|
| 115 | +Some of the prefixes allow abbreviation ; `break`, `feat`, `depr`, and `doc` are all valid. If you omit a prefix, the commit will be treated as a `change`. |
| 116 | +
|
| 117 | +For the rest of the message, use imperative style and keep things concise but informative. See [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/) for guidance. |
| 118 | +
|
| 119 | +
|
| 120 | +### Sending a Pull Request |
| 121 | +
|
| 122 | +GitHub provides additional document on [Creating a Pull Request](https://help.github.com/articles/creating-a-pull-request/). |
| 123 | +
|
| 124 | +Please remember to: |
| 125 | +* Use commit messages (and PR titles) that follow the guidelines under [Committing Your Change](#committing-your-change). |
| 126 | +* Send us a pull request, answering any default questions in the pull request interface. |
| 127 | +* Pay attention to any automated CI failures reported in the pull request, and stay involved in the conversation. |
| 128 | +
|
| 129 | +
|
| 130 | +## Finding Contributions to Work On |
| 131 | +
|
| 132 | +Looking at the existing issues is a great way to find something to contribute on. As our projects, by default, use the default GitHub issue labels ((enhancement/bug/duplicate/help wanted/invalid/question/wontfix), looking at any ['help wanted'](https://github.com/aws/aws-step-functions-data-science-sdk-python/labels/help%20wanted) issues is a great place to start. |
| 133 | +
|
| 134 | +
|
| 135 | +## Code of Conduct |
| 136 | +
|
| 137 | +This project has adopted the [Amazon Open Source Code of Conduct](https://aws.github.io/code-of-conduct). |
| 138 | +For more information see the [Code of Conduct FAQ](https://aws.github.io/code-of-conduct-faq) or contact |
| 139 | +opensource-codeofconduct@amazon.com with any additional questions or comments. |
| 140 | +
|
| 141 | +
|
| 142 | +## Security Issue Notifications |
| 143 | +
|
| 144 | +If you discover a potential security issue in this project we ask that you notify AWS/Amazon Security via our [vulnerability reporting page](http://aws.amazon.com/security/vulnerability-reporting/). Please do **not** create a public github issue. |
| 145 | +
|
| 146 | +
|
| 147 | +## Licensing |
| 148 | +
|
| 149 | +See the [LICENSE](https://github.com/aws/aws-step-functions-data-science-sdk-python/blob/master/LICENSE) file for our project's licensing. We will ask you to confirm the licensing of your contribution. |
| 150 | + |
| 151 | +We may ask you to sign a [Contributor License Agreement (CLA)](http://en.wikipedia.org/wiki/Contributor_License_Agreement) for larger changes. |
0 commit comments