diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 75b4b647fb5..ed2b9f28e51 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,14 +1,42 @@ -Contributing to the AWS SDK for Go +# 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 +[issues] or [pull requests][pr] to ensure we have all the necessary information to effectively respond to your bug report or contribution. +Jump To: -## Filing Bug Reports +* [Bug Reports](_#Bug-Reports_) +* [Code Contributions](_#Code-Contributions_) + +## How to contribute + +*Before you send us a pull request, please be sure that:* + +1. You're working from the latest source on the master 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 master branch. +3. Commit the change to your fork, using a clear and descriptive commit message. +4. Create 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][issues] page. @@ -40,11 +68,11 @@ guidelines prior to filing a bug report. as well, like whether this is a persistent issue, or if it only occurs some of the time. +## Code Contributions -## Submitting Pull Requests - -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: +We are always happy to receive code and documentation contributions to the SDK. +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 +same set of guidelines that the core contributors use when submitting changes, and we ask the same of all community contributions as well: 1. The SDK is released under the [Apache license][license]. Any code you submit will be released under that license. For substantial contributions, we may @@ -113,11 +141,21 @@ so you can run command within the Docker container and context of the SDK. make sandbox-go18 ``` -### Changelog +### Changelog Documents You can see all release changes in the `CHANGELOG.md` file at the root of the repository. The release notes added to this file will contain service client -updates, and major SDK changes. +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. + +#### Changelog Types + +* `SDK Features` - For major additive features, internal changes that have +outward impact, or updates to the SDK foundations. This will result in a minor +version change. +* `SDK Enhancements` - For minor additive features or incremental sized changes. +This will result in a patch version change. +* `SDK Bugs` - For minor changes that resolve an issue. This will result in a +patch version change. [issues]: https://github.com/aws/aws-sdk-go/issues [pr]: https://github.com/aws/aws-sdk-go/pulls diff --git a/README.md b/README.md index 0aa926ed199..acf8e8e93ee 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ -[![API Reference](https://img.shields.io/badge/api-reference-blue.svg)](https://docs.aws.amazon.com/sdk-for-go/api) [![Join the chat at https://gitter.im/aws/aws-sdk-go](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/aws/aws-sdk-go?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) [![Build Status](https://img.shields.io/travis/aws/aws-sdk-go.svg)](https://travis-ci.org/aws/aws-sdk-go) [![Apache V2 License](https://img.shields.io/badge/license-Apache%20V2-blue.svg)](https://github.com/aws/aws-sdk-go/blob/master/LICENSE.txt) - # AWS SDK for Go +[![API Reference](https://img.shields.io/badge/api-reference-blue.svg)](https://docs.aws.amazon.com/sdk-for-go/api) [![Join the chat at https://gitter.im/aws/aws-sdk-go](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/aws/aws-sdk-go?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) [![Build Status](https://img.shields.io/travis/aws/aws-sdk-go.svg)](https://travis-ci.org/aws/aws-sdk-go) [![Apache V2 License](https://img.shields.io/badge/license-Apache%20V2-blue.svg)](https://github.com/aws/aws-sdk-go/blob/master/LICENSE.txt) + aws-sdk-go is the official AWS SDK for the Go programming language. Checkout our [release notes](https://github.com/aws/aws-sdk-go/releases) for @@ -9,8 +9,16 @@ information about the latest bug fixes, updates, and features added to the SDK. We [announced](https://aws.amazon.com/blogs/developer/aws-sdk-for-go-2-0-developer-preview/) the Developer Preview for the [v2 AWS SDK for Go](https://github.com/aws/aws-sdk-go-v2). The v2 SDK source is available at https://github.com/aws/aws-sdk-go-v2, and add it to your project with `go get github.com/aws/aws-sdk-go-v2`. Check out the v2 SDK's [changes and updates](https://github.com/aws/aws-sdk-go-v2/blob/master/CHANGELOG.md), and let us know what you think. We want your feedback. -## Installing +Jump To: +* [Getting Started](_#Getting-Started_) +* [Quick Examples](_#Quick-Examples_) +* [Getting Help](_#Getting-Help_) +* [Contributing](_#Contributing_) +* [More Resources](_#Resources_) +## Getting Started + +### Installing Use `go get` to retrieve the SDK to add it to your `GOPATH` workspace, or project's Go module dependencies. @@ -50,57 +58,102 @@ if not used by your environment. rm -rf $GOPATH/src/github.com/aws/aws-sdk-go/vendor -## Getting Help -Please use these community resources for getting help. We use the GitHub issues -for tracking bugs and feature requests. +## Quick Examples -* Ask a question on [StackOverflow](http://stackoverflow.com/) and tag it with the [`aws-sdk-go`](http://stackoverflow.com/questions/tagged/aws-sdk-go) tag. -* Come join the AWS SDK for Go community chat on [gitter](https://gitter.im/aws/aws-sdk-go). -* Open a support ticket with [AWS Support](http://docs.aws.amazon.com/awssupport/latest/user/getting-started.html). -* If you think you may have found a bug, please open an [issue](https://github.com/aws/aws-sdk-go/issues/new). +### Complete SDK Example -## Opening Issues +This example shows a complete working Go file which will upload a file to S3 +and use the Context pattern to implement timeout logic that will cancel the +request if it takes too long. This example highlights how to use sessions, +create a service client, make a request, handle the error, and process the +response. -If you encounter a bug with the AWS SDK for Go we would like to hear about it. -Search the [existing issues](https://github.com/aws/aws-sdk-go/issues) and see -if others are also experiencing the issue before opening a new issue. Please -include the version of AWS SDK for Go, Go language, and OS you’re using. Please -also include reproduction case when appropriate. +```go + package main -The GitHub issues are intended for bug reports and feature requests. For help -and questions with using AWS SDK for GO please make use of the resources listed -in the [Getting Help](https://github.com/aws/aws-sdk-go#getting-help) section. -Keeping the list of open issues lean will help us respond in a timely manner. + import ( + "context" + "flag" + "fmt" + "os" + "time" -## Reference Documentation + "github.com/aws/aws-sdk-go/aws" + "github.com/aws/aws-sdk-go/aws/awserr" + "github.com/aws/aws-sdk-go/aws/request" + "github.com/aws/aws-sdk-go/aws/session" + "github.com/aws/aws-sdk-go/service/s3" + ) -[`Getting Started Guide`](https://aws.amazon.com/sdk-for-go/) - This document -is a general introduction on how to configure and make requests with the SDK. -If this is your first time using the SDK, this documentation and the API -documentation will help you get started. This document focuses on the syntax -and behavior of the SDK. The [Service Developer -Guide](https://aws.amazon.com/documentation/) will help you get started using -specific AWS services. + // Uploads a file to S3 given a bucket and object key. Also takes a duration + // value to terminate the update if it doesn't complete within that time. + // + // The AWS Region needs to be provided in the AWS shared config or on the + // environment variable as `AWS_REGION`. Credentials also must be provided + // Will default to shared config file, but can load from environment if provided. + // + // Usage: + // # Upload myfile.txt to myBucket/myKey. Must complete within 10 minutes or will fail + // go run withContext.go -b mybucket -k myKey -d 10m < myfile.txt + func main() { + var bucket, key string + var timeout time.Duration -[`SDK API Reference -Documentation`](https://docs.aws.amazon.com/sdk-for-go/api/) - Use this -document to look up all API operation input and output parameters for AWS -services supported by the SDK. The API reference also includes documentation of -the SDK, and examples how to using the SDK, service client API operations, and -API operation require parameters. + flag.StringVar(&bucket, "b", "", "Bucket name.") + flag.StringVar(&key, "k", "", "Object key name.") + flag.DurationVar(&timeout, "d", 0, "Upload timeout.") + flag.Parse() -[`Service Developer Guide`](https://aws.amazon.com/documentation/) - Use this -documentation to learn how to interface with AWS services. These guides are -great for getting started with a service, or when looking for more -information about a service. While this document is not required for coding, -services may supply helpful samples to look out for. + // All clients require a Session. The Session provides the client with + // shared configuration such as region, endpoint, and credentials. A + // Session should be shared where possible to take advantage of + // configuration and credential caching. See the session package for + // more information. + sess := session.Must(session.NewSession()) -[`SDK Examples`](https://github.com/aws/aws-sdk-go/tree/master/example) - -Included in the SDK's repo are several hand crafted examples using the SDK -features and AWS services. + // Create a new instance of the service's client with a Session. + // Optional aws.Config values can also be provided as variadic arguments + // to the New function. This option allows you to provide service + // specific configuration. + svc := s3.New(sess) + + // Create a context with a timeout that will abort the upload if it takes + // more than the passed in timeout. + ctx := context.Background() + var cancelFn func() + if timeout > 0 { + ctx, cancelFn = context.WithTimeout(ctx, timeout) + } + // Ensure the context is canceled to prevent leaking. + // See context package for more information, https://golang.org/pkg/context/ + if cancelFn != nil { + defer cancelFn() + } + + // Uploads the object to S3. The Context will interrupt the request if the + // timeout expires. + _, err := svc.PutObjectWithContext(ctx, &s3.PutObjectInput{ + Bucket: aws.String(bucket), + Key: aws.String(key), + Body: os.Stdin, + }) + if err != nil { + if aerr, ok := err.(awserr.Error); ok && aerr.Code() == request.CanceledErrorCode { + // If the SDK can determine the request or retry delay was canceled + // by a context the CanceledErrorCode error code will be returned. + fmt.Fprintf(os.Stderr, "upload canceled due to timeout, %v\n", err) + } else { + fmt.Fprintf(os.Stderr, "failed to upload object, %v\n", err) + } + os.Exit(1) + } -## Overview of SDK's Packages + fmt.Printf("successfully uploaded file to %s/%s\n", bucket, key) + } +``` + +### Overview of SDK's Packages The SDK is composed of two main components, SDK core, and service clients. The SDK core packages are all available under the aws package at the root of @@ -138,7 +191,7 @@ package under the service folder at the root of the SDK. * service - Clients for AWS services. All services supported by the SDK are available under this folder. -## How to Use the SDK's AWS Service Clients +### How to Use the SDK's AWS Service Clients The SDK includes the Go types and utilities you can use to make requests to AWS service APIs. Within the service folder at the root of the SDK you'll find @@ -154,7 +207,7 @@ configuration. Once the service's client is created you can use it to make API requests the AWS service. These clients are safe to use concurrently. -## Configuring the SDK +### Configuring the SDK In the AWS SDK for Go, you can configure settings for service clients, such as the log level and maximum number of retries. Most settings are optional; @@ -284,7 +337,7 @@ options such as setting the Endpoint, and other service client configuration opt [endpoints_pkg]: https://docs.aws.amazon.com/sdk-for-go/api/aws/endpoints/ -## Making API Requests +### Making API Requests Once the client is created you can make an API request to the service. Each API method takes a input parameter, and returns the service response @@ -399,102 +452,68 @@ be request.WaiterResourceNotReadyErrorCode. panic(fmt.Errorf("failed to wait for bucket to exist, %v", err)) } fmt.Println("Bucket", myBucket, "exists") -``` +``` -## Complete SDK Example +## Getting Help -This example shows a complete working Go file which will upload a file to S3 -and use the Context pattern to implement timeout logic that will cancel the -request if it takes too long. This example highlights how to use sessions, -create a service client, make a request, handle the error, and process the -response. +Please use these community resources for getting help. We use the GitHub issues +for tracking bugs and feature requests. -```go - package main +* Ask a question on [StackOverflow](http://stackoverflow.com/) and tag it with the [`aws-sdk-go`](http://stackoverflow.com/questions/tagged/aws-sdk-go) tag. +* Come join the AWS SDK for Go community chat on [gitter](https://gitter.im/aws/aws-sdk-go). +* Open a support ticket with [AWS Support](http://docs.aws.amazon.com/awssupport/latest/user/getting-started.html). +* If you think you may have found a bug, please open an [issue](https://github.com/aws/aws-sdk-go/issues/new/choose). - import ( - "context" - "flag" - "fmt" - "os" - "time" +This SDK implements AWS service APIs. For general issues regarding the AWS services and their limitations, you may also take a look at the [Amazon Web Services Discussion Forums](https://forums.aws.amazon.com/). - "github.com/aws/aws-sdk-go/aws" - "github.com/aws/aws-sdk-go/aws/awserr" - "github.com/aws/aws-sdk-go/aws/request" - "github.com/aws/aws-sdk-go/aws/session" - "github.com/aws/aws-sdk-go/service/s3" - ) +### Opening Issues - // Uploads a file to S3 given a bucket and object key. Also takes a duration - // value to terminate the update if it doesn't complete within that time. - // - // The AWS Region needs to be provided in the AWS shared config or on the - // environment variable as `AWS_REGION`. Credentials also must be provided - // Will default to shared config file, but can load from environment if provided. - // - // Usage: - // # Upload myfile.txt to myBucket/myKey. Must complete within 10 minutes or will fail - // go run withContext.go -b mybucket -k myKey -d 10m < myfile.txt - func main() { - var bucket, key string - var timeout time.Duration +If you encounter a bug with the AWS SDK for Go we would like to hear about it. +Search the [existing issues](https://github.com/aws/aws-sdk-go/issues) and see +if others are also experiencing the issue before opening a new issue. Please +include the version of AWS SDK for Go, Go language, and OS you’re using. Please +also include reproduction case when appropriate. - flag.StringVar(&bucket, "b", "", "Bucket name.") - flag.StringVar(&key, "k", "", "Object key name.") - flag.DurationVar(&timeout, "d", 0, "Upload timeout.") - flag.Parse() +The GitHub issues are intended for bug reports and feature requests. For help +and questions with using AWS SDK for Go please make use of the resources listed +in the [Getting Help](https://github.com/aws/aws-sdk-go#getting-help) section. +Keeping the list of open issues lean will help us respond in a timely manner. - // All clients require a Session. The Session provides the client with - // shared configuration such as region, endpoint, and credentials. A - // Session should be shared where possible to take advantage of - // configuration and credential caching. See the session package for - // more information. - sess := session.Must(session.NewSession()) +## Contributing - // Create a new instance of the service's client with a Session. - // Optional aws.Config values can also be provided as variadic arguments - // to the New function. This option allows you to provide service - // specific configuration. - svc := s3.New(sess) +We work hard to provide a high-quality and useful SDK for our AWS services, and we greatly value feedback and contributions from our community. Please review our [contributing guidelines](./CONTRIBUTING.md) before submitting any [issues] or [pull requests][pr] to ensure we have all the necessary information to effectively respond to your bug report or contribution. - // Create a context with a timeout that will abort the upload if it takes - // more than the passed in timeout. - ctx := context.Background() - var cancelFn func() - if timeout > 0 { - ctx, cancelFn = context.WithTimeout(ctx, timeout) - } - // Ensure the context is canceled to prevent leaking. - // See context package for more information, https://golang.org/pkg/context/ - if cancelFn != nil { - defer cancelFn() - } +## Resources - // Uploads the object to S3. The Context will interrupt the request if the - // timeout expires. - _, err := svc.PutObjectWithContext(ctx, &s3.PutObjectInput{ - Bucket: aws.String(bucket), - Key: aws.String(key), - Body: os.Stdin, - }) - if err != nil { - if aerr, ok := err.(awserr.Error); ok && aerr.Code() == request.CanceledErrorCode { - // If the SDK can determine the request or retry delay was canceled - // by a context the CanceledErrorCode error code will be returned. - fmt.Fprintf(os.Stderr, "upload canceled due to timeout, %v\n", err) - } else { - fmt.Fprintf(os.Stderr, "failed to upload object, %v\n", err) - } - os.Exit(1) - } +[Developer guide](https://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/welcome.html/) - This document +is a general introduction on how to configure and make requests with the SDK. +If this is your first time using the SDK, this documentation and the API +documentation will help you get started. This document focuses on the syntax +and behavior of the SDK. The [Service Developer Guide](https://aws.amazon.com/documentation/) +will help you get started using specific AWS services. - fmt.Printf("successfully uploaded file to %s/%s\n", bucket, key) - } -``` +[SDK API Reference Documentation](https://docs.aws.amazon.com/sdk-for-go/api/) - Use this +document to look up all API operation input and output parameters for AWS +services supported by the SDK. The API reference also includes documentation of +the SDK, and examples how to using the SDK, service client API operations, and +API operation require parameters. + +[Service Documentation](https://aws.amazon.com/documentation/) - Use this +documentation to learn how to interface with AWS services. These guides are +great for getting started with a service, or when looking for more +information about a service. While this document is not required for coding, +services may supply helpful samples to look out for. + +[SDK Examples](https://github.com/aws/aws-sdk-go/tree/master/example) - +Included in the SDK's repo are several hand crafted examples using the SDK +features and AWS services. + +[Forum](https://forums.aws.amazon.com/forum.jspa?forumID=293) - Ask questions, get help, and give feedback + +[Issues][issues] - Report issues, submit pull requests, and get involved + (see [Apache 2.0 License][license]) -## License -This SDK is distributed under the -[Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0), -see LICENSE.txt and NOTICE.txt for more information. +[issues]: https://github.com/aws/aws-sdk-go/issues +[pr]: https://github.com/aws/aws-sdk-go/pulls +[license]: http://aws.amazon.com/apache2.0/ \ No newline at end of file