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