src

Go monorepo.
git clone git://code.dwrz.net/src
Log | Files | Refs

CONTRIBUTING.md (7618B)


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