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