Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
173 lines (131 loc) · 7.63 KB

CONTRIBUTING.md

File metadata and controls

173 lines (131 loc) · 7.63 KB

Contributing to the AWS SDK for Go

Thank you for your interest in contributing to the AWS SDK for Go! We work hard to provide a high-quality and useful SDK, and we greatly value feedback and contributions from our community. Whether it's a bug report, new feature, correction, or additional documentation, we welcome your issues and pull requests. Please read through this document before submitting any issues or pull requests to ensure we have all the necessary information to effectively respond to your bug report or contribution.

Jump To:

How to contribute

Before you send us a pull request, please be sure that:

  1. You're working from the latest source on the main branch.
  2. You check existing open, and recently closed, pull requests to be sure that someone else hasn't already addressed the problem.
  3. You create an issue before working on a contribution that will take a significant amount of your time.

Creating a Pull Request

  1. Fork the repository.
  2. In your fork, make your change in a branch that's based on this repo's main branch.
  3. Commit the change to your fork, using a clear and descriptive commit message.
  4. Open a pull request, answering any questions in the pull request form.

For contributions that will take a significant amount of time, open a new issue to pitch your idea before you get started. Explain the problem and describe the content you want to see added to the documentation. Let us know if you'll write it yourself or if you'd like us to help. We'll discuss your proposal with you and let you know whether we're likely to accept it.

Bug Reports

You can file bug reports against the SDK on the GitHub issues page.

If you are filing a report for a bug or regression in the SDK, it's extremely helpful to provide as much information as possible when opening the original issue. This helps us reproduce and investigate the possible bug without having to wait for this extra information to be provided. Please read the following guidelines prior to filing a bug report.

  1. Search through existing issues to ensure that your specific issue has not yet been reported. If it is a common issue, it is likely there is already a bug report for your problem.

  2. Ensure that you have tested the latest version of the SDK. Although you may have an issue against an older version of the SDK, we cannot provide bug fixes for old versions. It's also possible that the bug may have been fixed in the latest release.

  3. Provide as much information about your environment, SDK version, and relevant dependencies as possible. For example, let us know what version of Go you are using, which and version of the operating system, and the the environment your code is running in. e.g Container.

  4. Provide a minimal test case that reproduces your issue or any error information you related to your problem. We can provide feedback much more quickly if we know what operations you are calling in the SDK. If you cannot provide a full test case, provide as much code as you can to help us diagnose the problem. Any relevant information should be provided as well, like whether this is a persistent issue, or if it only occurs some of the time.

Feature Requests

Open an issue with the following:

  • A short, descriptive title. Ideally, other community members should be able to get a good idea of the feature just from reading the title.
  • A detailed description of the the proposed feature.
    • Why it should be added to the SDK.
    • If possible, example code to illustrate how it should work.
  • Use Markdown to make the request easier to read;
  • If you intend to implement this feature, indicate that you'd like to the issue to be assigned to you.

Code Contributions

We are always happy to receive code and documentation contributions to the SDK. Please be aware of the following notes prior to opening a pull request:

  1. The SDK is released under the Apache license. Any code you submit will be released under that license. For substantial contributions, we may ask you to sign a Contributor License Agreement (CLA).

  2. If you would like to implement support for a significant feature that is not yet available in the SDK, please talk to us beforehand to avoid any duplication of effort.

  3. Wherever possible, pull requests should contain tests as appropriate. Bugfixes should contain tests that exercise the corrected behavior (i.e., the test should fail without the bugfix and pass with it), and new features should be accompanied by tests exercising the feature.

  4. Pull requests that contain failing tests will not be merged until the test failures are addressed. Pull requests that cause a significant drop in the SDK's test coverage percentage are unlikely to be merged until tests have been added.

Automated Tools

The use of AI tooling for assisted development work is accepted and encouraged in this repository, but due to the volume of submissions we ask that you observe the following rules:

  • All issue and pull request submissions to this repository that are sourced by AI must first be reviewed by a human before submitting to the repository. Items reviewed in this way must include a statement like "generated by AI tools, and reviewed by "
  • Please ensure that your submissions are actually improvements. While we are grateful for any proposed fixes, even if they are very small, behavior that looks like creating nuisance PRs or artificially inflating submission counts is not acceptable.
  • We may close issues or pull requests, or limit your ability to interact with this repository, for behavior that in our estimation violates these rules or any of the other rules in this repository's Code of Conduct

Generated source / API models

There are several components of the SDK that we cannot accept direct changes to:

  1. Many source files in the SDK are code-generated. You can tell when a file is code-generated because it will contain a header comment at the top indicating as such: // Code generated by smithy-go-codegen DO NOT EDIT.. Any manual edits to these files will be overwritten next time the source is regenerated. As such we cannot accept pull requests directly on generated source files. If you identify an issue within code-generated source please create a GitHub issue.

  2. The JSON files under codegen/sdk-codegen/aws-models folder (e.g. s3.json) are sourced from outside the SDK and are automatically updated as part of daily SDK releases. As such we cannot accept pull requests that modify these files. If you discover an issue with the models please create a GitHub issue.

Changelog

DO NOT add a .changelog entry, we will do that for you.

Testing

To run the tests locally, running the make unit command will go get the SDK's testing dependencies, and run vet, link and unit tests for the SDK.

make unit

Standard go testing functionality is supported as well. To test SDK code that is tagged with codegen you'll need to set the build tag in the go test command. The make unit command will do this automatically.

go test -tags codegen ./private/...

See the Makefile for additional testing tags that can be used in testing.