CONTRIBUTING.md (7618B)
1 # Contributing to the AWS SDK for Go 2 3 Thank you for your interest in contributing to the AWS SDK for Go! 4 We work hard to provide a high-quality and useful SDK, and we greatly value 5 feedback and contributions from our community. Whether it's a bug report, 6 new feature, correction, or additional documentation, we welcome your issues 7 and pull requests. Please read through this document before submitting any 8 [issues] or [pull requests][pr] to ensure we have all the necessary information to 9 effectively respond to your bug report or contribution. 10 11 Jump To: 12 13 * [Bug Reports](#bug-reports) 14 * [Feature Requests](#feature-requests) 15 * [Code Contributions](#code-contributions) 16 17 18 ## How to contribute 19 20 *Before you send us a pull request, please be sure that:* 21 22 1. You're working from the latest source on the master branch. 23 2. You check existing open, and recently closed, pull requests to be sure 24 that someone else hasn't already addressed the problem. 25 3. You create an issue before working on a contribution that will take a 26 significant amount of your time. 27 28 *Creating a Pull Request* 29 30 1. Fork the repository. 31 2. In your fork, make your change in a branch that's based on this repo's master branch. 32 3. Commit the change to your fork, using a clear and descriptive commit message. 33 4. Create a pull request, answering any questions in the pull request form. 34 35 For contributions that will take a significant amount of time, open a new 36 issue to pitch your idea before you get started. Explain the problem and 37 describe the content you want to see added to the documentation. Let us know 38 if you'll write it yourself or if you'd like us to help. We'll discuss your 39 proposal with you and let you know whether we're likely to accept it. 40 41 ## Bug Reports 42 43 You can file bug reports against the SDK on the [GitHub issues][issues] page. 44 45 If you are filing a report for a bug or regression in the SDK, it's extremely 46 helpful to provide as much information as possible when opening the original 47 issue. This helps us reproduce and investigate the possible bug without having 48 to wait for this extra information to be provided. Please read the following 49 guidelines prior to filing a bug report. 50 51 1. Search through existing [issues][] to ensure that your specific issue has 52 not yet been reported. If it is a common issue, it is likely there is 53 already a bug report for your problem. 54 55 2. Ensure that you have tested the latest version of the SDK. Although you 56 may have an issue against an older version of the SDK, we cannot provide 57 bug fixes for old versions. It's also possible that the bug may have been 58 fixed in the latest release. 59 60 3. Provide as much information about your environment, SDK version, and 61 relevant dependencies as possible. For example, let us know what version 62 of Go you are using, which and version of the operating system, and the 63 the environment your code is running in. e.g Container. 64 65 4. Provide a minimal test case that reproduces your issue or any error 66 information you related to your problem. We can provide feedback much 67 more quickly if we know what operations you are calling in the SDK. If 68 you cannot provide a full test case, provide as much code as you can 69 to help us diagnose the problem. Any relevant information should be provided 70 as well, like whether this is a persistent issue, or if it only occurs 71 some of the time. 72 73 ## Feature Requests 74 75 Open an [issue][issues] with the following: 76 77 * A short, descriptive title. Ideally, other community members should be able 78 to get a good idea of the feature just from reading the title. 79 * A detailed description of the the proposed feature. 80 * Why it should be added to the SDK. 81 * If possible, example code to illustrate how it should work. 82 * Use Markdown to make the request easier to read; 83 * If you intend to implement this feature, indicate that you'd like to the issue to be assigned to you. 84 85 ## Code Contributions 86 87 We are always happy to receive code and documentation contributions to the SDK. 88 Please be aware of the following notes prior to opening a pull request: 89 90 1. The SDK is released under the [Apache license][license]. Any code you submit 91 will be released under that license. For substantial contributions, we may 92 ask you to sign a [Contributor License Agreement (CLA)][cla]. 93 94 2. If you would like to implement support for a significant feature that is not 95 yet available in the SDK, please talk to us beforehand to avoid any 96 duplication of effort. 97 98 3. Wherever possible, pull requests should contain tests as appropriate. 99 Bugfixes should contain tests that exercise the corrected behavior (i.e., the 100 test should fail without the bugfix and pass with it), and new features 101 should be accompanied by tests exercising the feature. 102 103 4. Pull requests that contain failing tests will not be merged until the test 104 failures are addressed. Pull requests that cause a significant drop in the 105 SDK's test coverage percentage are unlikely to be merged until tests have 106 been added. 107 108 5. The JSON files under the SDK's `models` folder are sourced from outside the SDK. 109 Such as `models/apis/ec2/2016-11-15/api.json`. We will not accept pull requests 110 directly on these models. If you discover an issue with the models please 111 create a [GitHub issue][issues] describing the issue. 112 113 ### Testing 114 115 To run the tests locally, running the `make unit` command will `go get` the 116 SDK's testing dependencies, and run vet, link and unit tests for the SDK. 117 118 ``` 119 make unit 120 ``` 121 122 Standard go testing functionality is supported as well. To test SDK code that 123 is tagged with `codegen` you'll need to set the build tag in the go test 124 command. The `make unit` command will do this automatically. 125 126 ``` 127 go test -tags codegen ./private/... 128 ``` 129 130 See the `Makefile` for additional testing tags that can be used in testing. 131 132 To test on multiple platform the SDK includes several DockerFiles under the 133 `awstesting/sandbox` folder, and associated make recipes to to execute 134 unit testing within environments configured for specific Go versions. 135 136 ``` 137 make sandbox-test-go18 138 ``` 139 140 To run all sandbox environments use the following make recipe 141 142 ``` 143 # Optionally update the Go tip that will be used during the batch testing 144 make update-aws-golang-tip 145 146 # Run all SDK tests for supported Go versions in sandboxes 147 make sandbox-test 148 ``` 149 150 In addition the sandbox environment include make recipes for interactive modes 151 so you can run command within the Docker container and context of the SDK. 152 153 ``` 154 make sandbox-go18 155 ``` 156 157 ### Changelog Documents 158 159 You can see all release changes in the `CHANGELOG.md` file at the root of the 160 repository. The release notes added to this file will contain service client 161 updates, and major SDK changes. When submitting a pull request please include an entry in `CHANGELOG_PENDING.md` under the appropriate changelog type so your changelog entry is included on the following release. 162 163 #### Changelog Types 164 165 * `SDK Features` - For major additive features, internal changes that have 166 outward impact, or updates to the SDK foundations. This will result in a minor 167 version change. 168 * `SDK Enhancements` - For minor additive features or incremental sized changes. 169 This will result in a patch version change. 170 * `SDK Bugs` - For minor changes that resolve an issue. This will result in a 171 patch version change. 172 173 [issues]: https://github.com/aws/aws-sdk-go/issues 174 [pr]: https://github.com/aws/aws-sdk-go/pulls 175 [license]: http://aws.amazon.com/apache2.0/ 176 [cla]: http://en.wikipedia.org/wiki/Contributor_License_Agreement 177 [releasenotes]: https://github.com/aws/aws-sdk-go/releases 178