1# Contributing to the AWS SDK for Java 2Thank you for your interest in contributing the AWS SDK for Java! We work hard 3to provide a high quality and useful SDK for our customers, and we appreciate 4your interest in helping us and the rest of our community of users. We welcome 5bug reports, feature requests, and code contributions. 6 7__Jump To:__ 8* [Bug Reports](#bug-reports) 9* [Feature Requests](#feature-requests) 10* [Code Contributions](#code-contributions) 11* [Additional Resources](#additional-resources) 12 13## Bug Reports 14Bug reports are accepted through the [this][bug-report] page. 15 16The following labels are used to track bug related issues: [Bug][label-bug], 17[Documentation Issue][label-doc-issue]. 18 19### Before Submitting a Bug Report 20Before submitting a bug report, please do the following: 21 221. Do a search through the existing issues to make sure it has not already been 23 reported. If there's an existing one, be sure give a �� reaction which will 24 help us prioritize which issues to address first. 25 262. If possible, upgrade to the latest release of the SDK. The SDK has a near 27 daily release cadence so it's possible the bug has already been fixed in the 28 latest version. We maintain a strong backwards compatibility guarantee 29 between patch version releases so you can be confident that your application 30 will continue to work as expected with the newer version. 31 32If, after doing the above steps, you determine that you need to submit a bug 33report, refer to the next section. 34 35### Submitting a Bug Report 36So that we are able to assist you as effectively as possible with the issue, 37please ensure that your bug report has the following: 38 39* A short, descriptive title. Ideally, other community members should be able 40 to get a good idea of the issue just from reading the title. 41* A succint, detailed description of the problem you're experiencing. This 42 should include: 43 * Expected behavior of the SDK and the actual behavior exhibited. 44 * Any details of your application environment that may be relevant. At 45 minimum, this should include the __SDK version__ and __JRE version__. 46 * If applicable, the exception stacktrace. 47 * If you are able to create one, include a [Minimal Working Example][mwe] 48 that reproduces the issue. 49* [Markdown][markdown] formatting as appropriate to make the report easier to 50 read; for example use code blocks when pasting a code snippet and exception 51 stacktraces. 52 53## Feature Requests 54Feature requests are submitted through the [this][feature-request] page. 55 56As with Bug Reports, please do a search of the open requests first before 57submitting a new one to avoid duplicates. If you find an existing one, give it 58a +1. 59 60__NOTE:__ If this is a feature you intend to implement, please be sure to 61submit the feature request *before* working on any code changes. This will 62allow members on the SDK team to have a discussion with you to ensure that it's 63the right design and that it makes sense to include in the SDK. Keep in mind 64that other concerns like source and binary compatibility will also play a 65deciding factor. 66 67Feature requests are labeled with [feature-request][label-feature-request]. 68 69### Submitting a Feature Request 70Open an [issue][issues] with the following: 71 72* A short, descriptive title. Ideally, other community members should be able 73 to get a good idea of the feature just from reading the title. 74* A detailed description of the the proposed feature. Include justification for 75 why it should be added to the SDK, and possibly example code to illustrate 76 how it should work. 77* [Markdown][markdown] formatting as appropriate to make the request easier to 78 read. 79* If you intend to implement this feature, indicate that you'd like to the 80 issue to be assigned to you 81 82## Code Contributions 83Code contributions to the SDK are done through [Pull Requests][pull-requests]. 84Please keep the following in mind when considering a code contribution: 85 86* The SDK is released under the [Apache 2.0 License][license]. 87 88 Any code you submit will be released under this license. If you are 89 contributing a large/substantial feature, you may be asked to sign a 90 Contributor License Agreement (CLA). 91* For anything but very small or quick changes, you should always start by 92 checking the [Issues][issues] page to see if the work is already being done 93 by another person. 94 95 If you're working on a bug fix, check to see if the bug has already been 96 reported. If it has but no one is assigned to it, ask one of the maintainers 97 to assign it to you before beginning work. If you're confident the bug 98 hasn't been reported yet, create a new [Bug Report](#bug-reports) then ask to 99 be assigned to it. 100 101 If you are thinking about adding entirely new functionality, open a [Feature 102 Request](#feature-requests) or [ping][gitter] the maintainers to ask for 103 feedback first before beginning work; again this is to make sure that no one 104 else is already working on it, and also that it makes sense to be included in 105 the SDK. 106* All code contributions must be accompanied with new or modified tests that 107 verify that the code works as expected; i.e. that the issue has been fixed or 108 that the functionality works as intended. 109 110### Your First Code Change 111For detailed information on getting started building and making code changes to 112the SDK, refer to our [Working on the SDK](./docs/GettingStarted.md) doc 113 114### Pull Request Readiness 115Before submitting your pull request, refer to the pull request readiness 116checklist below: 117 118* [ ] Includes tests to exercise the new behavior 119* [ ] Code is documented, especially public and user-facing constructs 120* [ ] Local run of `./mvnw package`(Linux) or `./mvnw.cmd package`(Windows) succeeds 121* [ ] Git commit message is detailed and includes context behind the change 122* [ ] If the change is related to an existing Bug Report or Feature Request, 123 the issue number is referenced 124* [ ] A short description of the change added to 125 [CHANGELOG.md](./CHANGELOG.md). Adding a new entry must be accomplished by 126 running the `scripts/new-change` script and following the instructions. 127 Commit the new file created by the script in `.changes/next-release` with 128 your changes. 129 130__Note__: Some changes have additional requirements. Refer to the section below 131to see if your change will require additional work to be accepted. 132 133#### Additional Pull Request Requirements 134##### Reactive Streams 135If the change includes implementations of the [Reactive Streams 136interfaces](https://github.com/reactive-streams/reactive-streams-jvm), the 137change must also contain verification tests using the [Reactive Streams 138Technology Compatibility 139Kit](https://github.com/reactive-streams/reactive-streams-jvm/tree/master/tck) 140to ensure specificiation compliance. 141 142### Getting Your Pull Request Merged 143All Pull Requests must be approved by at least one member of the SDK team 144before it can be merged in. The members only have limited bandwitdth to review 145Pull Requests so it's not unusual for a Pull Request to go unreviewed for a few 146days, especially if it's a large or complex one. If, after a week, your Pull 147Request has not had any engagement from the SDK team, feel free to ping a 148member to ask for a review. 149 150## Additional Resources 151We maintain [docs](docs/README.md) where information like design decisions, internal 152architecture, and style conventions are documented that you may find helpful 153when contributing to the SDK. 154 155 156[license]: ./LICENSE.txt 157[mwe]: https://en.wikipedia.org/wiki/Minimal_Working_Example 158[markdown]: https://guides.github.com/features/mastering-markdown/ 159[issues]: https://github.com/aws/aws-sdk-java-v2/issues 160[pull-requests]: https://github.com/aws/aws-sdk-java-v2/pulls 161[label-bug]: https://github.com/aws/aws-sdk-java-v2/labels/bug 162[label-doc-issue]: https://github.com/aws/aws-sdk-java-v2/labels/documentation 163[label-feature-request]: https://github.com/aws/aws-sdk-java-v2/labels/feature-request 164[git-rewriting-history]: https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History 165[gitter]: https://gitter.im/aws/aws-sdk-java-v2 166[bug-report]: https://github.com/aws/aws-sdk-java-v2/issues/new?assignees=&labels=bug%2Cneeds-triage&template=bug-report.yml&title=%28short+issue+description%29 167[feature-request]: https://github.com/aws/aws-sdk-java-v2/issues/new?assignees=&labels=feature-request%2Cneeds-triage&template=feature-request.yml&title=%28short+issue+description%29 168