1Contributing to the AWS SDK for Go
2
3We work hard to provide a high-quality and useful SDK, and we greatly value
4feedback and contributions from our community. Whether it's a bug report,
5new feature, correction, or additional documentation, we welcome your issues
6and pull requests. Please read through this document before submitting any
7issues or pull requests to ensure we have all the necessary information to
8effectively respond to your bug report or contribution.
9
10
11## Filing Bug Reports
12
13You can file bug reports against the SDK on the [GitHub issues][issues] page.
14
15If you are filing a report for a bug or regression in the SDK, it's extremely
16helpful to provide as much information as possible when opening the original
17issue. This helps us reproduce and investigate the possible bug without having
18to wait for this extra information to be provided. Please read the following
19guidelines prior to filing a bug report.
20
211. Search through existing [issues][] to ensure that your specific issue has
22   not yet been reported. If it is a common issue, it is likely there is
23   already a bug report for your problem.
24
252. Ensure that you have tested the latest version of the SDK. Although you
26   may have an issue against an older version of the SDK, we cannot provide
27   bug fixes for old versions. It's also possible that the bug may have been
28   fixed in the latest release.
29
303. Provide as much information about your environment, SDK version, and
31   relevant dependencies as possible. For example, let us know what version
32   of Go you are using, which and version of the operating system, and the
33   environment your code is running in. e.g Container.
34
354. Provide a minimal test case that reproduces your issue or any error
36   information you related to your problem. We can provide feedback much
37   more quickly if we know what operations you are calling in the SDK. If
38   you cannot provide a full test case, provide as much code as you can
39   to help us diagnose the problem. Any relevant information should be provided
40   as well, like whether this is a persistent issue, or if it only occurs
41   some of the time.
42
43
44## Submitting Pull Requests
45
46We are always happy to receive code and documentation contributions to the SDK.
47Please be aware of the following notes prior to opening a pull request:
48
491. The SDK is released under the [Apache license][license]. Any code you submit
50   will be released under that license. For substantial contributions, we may
51   ask you to sign a [Contributor License Agreement (CLA)][cla].
52
532. If you would like to implement support for a significant feature that is not
54   yet available in the SDK, please talk to us beforehand to avoid any
55   duplication of effort.
56
573. Wherever possible, pull requests should contain tests as appropriate.
58   Bugfixes should contain tests that exercise the corrected behavior (i.e., the
59   test should fail without the bugfix and pass with it), and new features
60   should be accompanied by tests exercising the feature.
61
624. Pull requests that contain failing tests will not be merged until the test
63   failures are addressed. Pull requests that cause a significant drop in the
64   SDK's test coverage percentage are unlikely to be merged until tests have
65   been added.
66
675. The JSON files under the SDK's `models` folder are sourced from outside the SDK.
68   Such as `models/apis/ec2/2016-11-15/api.json`. We will not accept pull requests
69   directly on these models. If you discover an issue with the models please
70   create a [GitHub issue][issues] describing the issue.
71
72### Testing
73
74To run the tests locally, running the `make unit` command will `go get` the
75SDK's testing dependencies, and run vet, link and unit tests for the SDK.
76
77```
78make unit
79```
80
81Standard go testing functionality is supported as well. To test SDK code that
82is tagged with `codegen` you'll need to set the build tag in the go test
83command. The `make unit` command will do this automatically.
84
85```
86go test -tags codegen ./private/...
87```
88
89See the `Makefile` for additional testing tags that can be used in testing.
90
91To test on multiple platform the SDK includes several DockerFiles under the
92`awstesting/sandbox` folder, and associated make recipes to execute
93unit testing within environments configured for specific Go versions.
94
95```
96make sandbox-test-go18
97```
98
99To run all sandbox environments use the following make recipe
100
101```
102# Optionally update the Go tip that will be used during the batch testing
103make update-aws-golang-tip
104
105# Run all SDK tests for supported Go versions in sandboxes
106make sandbox-test
107```
108
109In addition the sandbox environment include make recipes for interactive modes
110so you can run command within the Docker container and context of the SDK.
111
112```
113make sandbox-go18
114```
115
116### Changelog
117
118You can see all release changes in the `CHANGELOG.md` file at the root of the
119repository. The release notes added to this file will contain service client
120updates, and major SDK changes.
121
122[issues]: https://github.com/aws/aws-sdk-go/issues
123[pr]: https://github.com/aws/aws-sdk-go/pulls
124[license]: http://aws.amazon.com/apache2.0/
125[cla]: http://en.wikipedia.org/wiki/Contributor_License_Agreement
126[releasenotes]: https://github.com/aws/aws-sdk-go/releases
127
128