github.com/aavshr/aws-sdk-go@v1.41.3/CONTRIBUTING.md (about)

     1  # Contributing to the AWS SDK for Go
     2  
     3  Thank you for your interest in contributing to the AWS SDK for Go!
     4  We work hard to provide a high-quality and useful SDK, and we greatly value
     5  feedback and contributions from our community. Whether it's a bug report,
     6  new feature, correction, or additional documentation, we welcome your issues
     7  and 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
     9  effectively respond to your bug report or contribution.
    10  
    11  Jump 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  
    20  1. You're working from the latest source on the main branch.
    21  2. You check existing open, and recently closed, pull requests to be sure 
    22     that someone else hasn't already addressed the problem.
    23  3. 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  
    28  1. Fork the repository.
    29  2. In your fork, make your change in a branch that's based on this repo's main branch.
    30  3. Commit the change to your fork, using a clear and descriptive commit message.
    31  4. Create a pull request, answering any questions in the pull request form.
    32  
    33  For contributions that will take a significant amount of time, open a new 
    34  issue to pitch your idea before you get started. Explain the problem and 
    35  describe the content you want to see added to the documentation. Let us know 
    36  if you'll write it yourself or if you'd like us to help. We'll discuss your 
    37  proposal with you and let you know whether we're likely to accept it.   
    38  
    39  ## Bug Reports
    40  
    41  You can file bug reports against the SDK on the [GitHub issues][issues] page.
    42  
    43  If you are filing a report for a bug or regression in the SDK, it's extremely
    44  helpful to provide as much information as possible when opening the original
    45  issue. This helps us reproduce and investigate the possible bug without having
    46  to wait for this extra information to be provided. Please read the following
    47  guidelines prior to filing a bug report.
    48  
    49  1. 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  
    53  2. 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  
    58  3. 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  
    63  4. 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  
    73  We are always happy to receive code and documentation contributions to the SDK. 
    74  Code contributions to the SDK are done through [Pull Requests][pr]. The list below are guidelines to use when submitting pull requests. These are the 
    75  same set of guidelines that the core contributors use when submitting changes, and we ask the same of all community contributions as well:
    76  
    77  1. 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  
    81  2. 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  
    85  3. 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  
    90  4. 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  
    95  5. 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  
   102  To run the tests locally, running the `make unit` command will `go get` the
   103  SDK's testing dependencies, and run vet, link and unit tests for the SDK.
   104  
   105  ```
   106  make unit
   107  ```
   108  
   109  Standard go testing functionality is supported as well. To test SDK code that
   110  is tagged with `codegen` you'll need to set the build tag in the go test
   111  command. The `make unit` command will do this automatically.
   112  
   113  ```
   114  go test -tags codegen ./private/...
   115  ```
   116  
   117  See the `Makefile` for additional testing tags that can be used in testing.
   118  
   119  To test on multiple platform the SDK includes several DockerFiles under the
   120  `awstesting/sandbox` folder, and associated make recipes to execute
   121  unit testing within environments configured for specific Go versions.
   122  
   123  ```
   124  make sandbox-test-go18
   125  ```
   126  
   127  To 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
   131  make update-aws-golang-tip
   132  
   133  # Run all SDK tests for supported Go versions in sandboxes
   134  make sandbox-test
   135  ```
   136  
   137  In addition the sandbox environment include make recipes for interactive modes
   138  so you can run command within the Docker container and context of the SDK.
   139  
   140  ```
   141  make sandbox-go18
   142  ```
   143  
   144  ### Changelog Documents
   145  
   146  You can see all release changes in the `CHANGELOG.md` file at the root of the
   147  repository. The release notes added to this file will contain service client
   148  updates, 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
   153  outward impact, or updates to the SDK foundations. This will result in a minor
   154  version change.
   155  * `SDK Enhancements` - For minor additive features or incremental sized changes.
   156  This will result in a patch version change.
   157  * `SDK Bugs` - For minor changes that resolve an issue. This will result in a
   158  patch version change.
   159  
   160  [issues]: https://github.com/aavshr/aws-sdk-go/issues
   161  [pr]: https://github.com/aavshr/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/aavshr/aws-sdk-go/releases
   165