xref: /aosp_15_r20/external/aws-sdk-java-v2/CONTRIBUTING.md (revision 8a52c7834d808308836a99fc2a6e0ed8db339086)
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