You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Interested in contributing to the AWS Serverless Application Model (AWS SAM)?
4
4
Awesome! Read this document to understand how to report issues, contribute
5
-
features and the participate in development process. We want to create a
5
+
features and participate in the development process. We want to create a
6
6
transparent and open process for evolving AWS SAM.
7
7
8
+
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.
9
+
8
10
## Integrating AWS SAM into your tool
9
-
Are you building a new tool that will support AWS SAM? File an issue and let us
10
-
know what you are working on. We will support you however we can.
11
+
12
+
We encourage you to modify SAM to integrate it with other frameworks and deployment providers from the community for building serverless applications. If you're building a new tool that will use AWS SAM, let us know how we can help!
11
13
12
14
## Submitting feature requests
13
-
If you think of a cool feature that will greatly help hundreds of developers
14
-
like you, we would love to hear about it. Follow these steps to submit your
15
-
feature request:
15
+
16
+
We love features that help developers build serverless applications faster and further simplify development of serverless applications. If you have ideas for new event sources, new resource types, and new parameters within SAM, follow these steps to submit your feature request:
If you find your feature there, mark it +1. This is a good indication of
21
22
interest from the community.
22
23
2. If you don't find your feature in our backlog, create a new issue and assign
@@ -25,85 +26,109 @@ feature request:
25
26
Keep in mind that features should be driven by real use cases. Answer the
26
27
following questions in the issue that you create:
27
28
28
-
- Does this feature simplify creating and deploying some aspect of a Serverless
29
-
application?
30
-
- Is this feature solving a problem faced by other Serverless application
31
-
developers?
29
+
- Does this feature simplify creating and deploying some aspect of a serverless application?
30
+
- Is this feature solving a problem faced by other serverless application developers?
32
31
- How do developers work around this problem today?
33
32
- How is the proposed feature better than the work around?
34
33
35
34
## Adding features to AWS SAM
36
35
37
36
We welcome pull requests to add new features to AWS SAM. Take a look at the
38
-
backlog
39
-
of
40
-
[Feature Requests](https://github.com/awslabs/serverless-application-specification/labels/feature-request) and
41
-
pick an item that you find interesting. If the requirements have been
42
-
well-scoped, feel free to make the change and send a pull request.
37
+
backlog of [Feature Requests](https://github.com/awslabs/serverless-application-specification/labels/feature-request) and pick an item that you find interesting. If the requirements have been well-scoped, feel free to make the change and send a pull request.
43
38
44
-
Otherwise, start a conversation in the thread with your plan for implementing
39
+
If you don't find an item tracking what you have in mind, start a conversation with your plan for implementing
45
40
the feature. When defining your feature, keep in mind that one of the core
46
41
tenets of AWS SAM is to keep it easy to use while allowing customers access to
47
-
use more advanced components, should they so choose. Here are some questions
48
-
that you should answer in your plan:
42
+
use more advanced components, should they so choose.
43
+
44
+
This repository contains the SAM specification, the code that translates SAM templates into AWS CloudFormation stacks, general information about the model, and examples of common applications. Make enhancements to all of SAM: if you make a change to the specification, please also make the corresponding change to the implementation.
49
45
50
-
-**What is the problem you are solving?**
51
-
Example: Creating API endpoints require 24 steps, most of which are
52
-
boilerplate and repetitive.
46
+
Here are some questions that you should answer in your plan:
47
+
48
+
-**What is the problem you are solving?**
49
+
50
+
Example: Creating API endpoints require 24 steps, most of which are boilerplate and repetitive.
53
51
54
52
-**Describe persona of someone who is facing this problem? This will give you
55
-
an understanding of how big of a problem it actually is.** Example: John
56
-
just finished coding bootcamp and wants to create a Serverless app. He has
53
+
an understanding of how big of a problem it actually is.**
54
+
55
+
Example: John just finished coding bootcamp and wants to create a Serverless app. He has
57
56
basic coding skills and will be comfortable understanding infrastructure
58
57
concepts, but probably be intimidated by the 24 steps required to create an
59
58
API endpoint.
60
59
61
-
-**How do developers work around this problem today?**
60
+
-**How do developers work around this problem today?**
61
+
62
62
Example: Manually click through every step on the website while refering to
63
63
"How To" resources on the internet.
64
64
65
-
-**Describe your proposed solution?**
65
+
-**Describe your proposed solution?**
66
+
66
67
Example: We are creating a new AWS SAM resource called "API". Here is how it
67
68
will look:
68
69
69
-
Type: 'AWS::Serverless::Api'
70
-
Properties:
71
-
# Name of API endpoint
72
-
Name: <string>
73
-
# Path to their endpoint. Example: /hello
74
-
Path: <string>
75
-
# HTTP Method for their endpoint. Example: GET, POST etc
76
-
Method: <string>
70
+
```yaml
71
+
Type: 'AWS::Serverless::Api'
72
+
Properties:
73
+
# Name of API endpoint
74
+
Name: <string>
75
+
# Path to their endpoint. Example: /hello
76
+
Path: <string>
77
+
# HTTP Method for their endpoint. Example: GET, POST etc
78
+
Method: <string>
79
+
```
77
80
81
+
- **How is the proposed feature better than what the work around?**
78
82
79
-
-**How is the proposed feature better than what the work around?**
80
-
Example: Developers can write a simple AWS SAM resource which will handle
83
+
Example: Developers can write a simple AWS SAM resource which will handle
81
84
generating the boilerplate for them.
82
85
83
-
## Administrivia
84
-
85
-
*Conversations*:
86
-
87
-
- Use GitHub Issues for conversation on model design, feature requests, bugs
88
-
etc.
89
-
- For more real-time conversations, use Gitter.
90
-
91
-
*Versioning and Branching*:
92
-
93
-
- As with the 2016-10-31 version, the **human readable** document is the source
94
-
of truth. If using a JSON schema again to document the spec, it is secondary
95
-
to the human documentation. The documentation should live in a *.md file, in
96
-
parallel to the 2016-10-31 document.
97
-
- The `master` branch shall remain the current, released AWS SAM (i.e.
98
-
2016-10-31). We will work in a `development` branch for new features and merge
99
-
them to `master` when they are ready.
100
-
101
-
*Labels*:
102
-
Here are some labels we will use to keep issues organized. Core contributors can
103
-
add new labels as they see fit:
104
-
-`Feature Request`: Marks an issue as a feature request.
105
-
-`Needs Documentation`: Used in conjunction with the Feature Request label to
106
-
indicate that the feature needs documentation.
107
-
-`Needs Tooling`: Used in conjunction with the Feature Request label to
108
-
indicate that feature needs tooling support in the transformation.
109
-
-`Bug`: Marks an issue as a bug.
86
+
## Reporting Bugs/Feature Requests
87
+
88
+
We welcome you to use the GitHub issue tracker to report bugs or suggest features.
89
+
90
+
When filing an issue, please check [existing open](https://github.com/awslabs/PRIVATE-aws-sam-development/issues), or [recently closed](https://github.com/awslabs/PRIVATE-aws-sam-development/issues?utf8=%E2%9C%93&q=is%3Aissue%20is%3Aclosed%20), issues to make sure somebody else hasn't already
91
+
reported the issue. Please try to include as much information as you can. Details like these are incredibly useful:
92
+
93
+
- A reproducible test case or series of steps
94
+
- The version of our code being used
95
+
- Any modifications you've made relevant to the bug
96
+
- Anything unusual about your environment or deployment
97
+
98
+
## Contributing via Pull Requests
99
+
100
+
Contributions via pull requests are much appreciated. Before sending us a pull request, please ensure that:
101
+
102
+
1. You are working against the latest source on the *master* branch.
103
+
2. You check existing open, and recently merged, pull requests to make sure someone else hasn't addressed the problem already.
104
+
3. You open an issue to discuss any significant work - we would hate for your time to be wasted.
105
+
4. You propose complete changes - if you make a change to the specification, please also make the corresponding change to the implementation.
106
+
107
+
To send us a pull request, please:
108
+
109
+
1. Fork the repository.
110
+
2. Modify the source; please focus on the specific change you are contributing. If you also reformat all the code, it will be hard for us to focus on your change.
111
+
3. Ensure local tests pass.
112
+
4. Commit to your fork using clear commit messages.
113
+
5. Send us a pull request, answering any default questions in the pull request interface.
114
+
6. Pay attention to any automated CI failures reported in the pull request, and stay involved in the conversation.
115
+
116
+
GitHub provides additional document on [forking a repository](https://help.github.com/articles/fork-a-repo/) and [creating a pull request](https://help.github.com/articles/creating-a-pull-request/).
117
+
118
+
## Finding contributions to work on
119
+
120
+
Looking at the existing issues is a great way to find something to contribute on. As our projects, by default, use the default GitHub issue labels ((enhancement/bug/duplicate/help wanted/invalid/question/wontfix), looking at any ['help wanted'](https://github.com/awslabs/PRIVATE-aws-sam-development/labels/help%20wanted) issues is a great place to start.
121
+
122
+
## Code of Conduct
123
+
124
+
This project has adopted the [Amazon Open Source Code of Conduct](https://aws.github.io/code-of-conduct). For more information see the [Code of Conduct FAQ](https://aws.github.io/code-of-conduct-faq) or contact opensource-codeofconduct@amazon.com with any additional questions or comments.
125
+
126
+
## Security issue notifications
127
+
128
+
If you discover a potential security issue in this project we ask that you notify AWS/Amazon Security via our [vulnerability reporting page](http://aws.amazon.com/security/vulnerability-reporting/). Please do **not** create a public github issue.
129
+
130
+
## Licensing
131
+
132
+
See the [LICENSE](https://github.com/awslabs/PRIVATE-aws-sam-development/blob/master/LICENSE) file for our project's licensing. We will ask you to confirm the licensing of your contribution.
133
+
134
+
We may ask you to sign a [Contributor License Agreement (CLA)](http://en.wikipedia.org/wiki/Contributor_License_Agreement) for larger changes.
For now we have decided `LogGroupName` should be a required property for simplicity. A future enhancement could make this optional and create a new CloudWatch Log Group when not provided. Users could `Ref` the resource if we exposed/documented the resource naming convention.
10
+
11
+
### FilterPattern
12
+
13
+
Decided `FilterPattern` should be a required property so as not to provide a footgun to users. If this were to default to `""`, noisy logs could invoke hundreds/thousands of Lambda functions in short periods of time.
You can use SAM to define serverless applications in simple and clean syntax.
5
+
6
+
This GitHub project is the starting point for AWS SAM. It contains the SAM specification, the code that translates SAM templates into AWS CloudFormation stacks, general information about the model, and examples of common applications.
3
7
4
-
The goal of AWS SAM is to define a standard application model for serverless
5
-
applications.
8
+
The SAM specification and implementation are open sourced under the Apache 2.0 license. The current version of the SAM specification is available at [AWS SAM 2016-10-31](versions/2016-10-31.md).
6
9
7
-
This GitHub project is the starting point for AWS SAM, and contains general
8
-
information, information about the model, and examples of common applications.
9
10
10
-
## Current version
11
+
## Creating a serverless application using SAM
12
+
To creating a serverless application using SAM, first, you create a SAM template: a JSON or YAML configuration file that describes your Lambda functions, API endpoints and the other resources in your application. Then, you test, upload, and deploy your application using the [SAM Local CLI](https://github.com/awslabs/aws-sam-local). During deployment, SAM automatically translates your application’s specification into CloudFormation syntax, filling in default values for any unspecified properties and determining the appropriate mappings and invocation permissions to setup for any Lambda functions.
11
13
12
-
**The current version is available
13
-
at [AWS SAM 2016-10-31](versions/2016-10-31.md).**
14
+
[Read the How-To Guide](HOWTO.md) and see [examples](examples/) to learn how to define & deploy serverless applications using SAM.
14
15
15
-
This repository contains the existing model as well as proposals for the next
16
-
version.
17
16
18
-
## Structure
17
+
## Contributing new features and enhancements to SAM
18
+
You can build serverless applications faster and further simplify your development of serverless applications by defining new event sources, new resource types, and new parameters within SAM. Additionally, you can modify SAM to integrate it with other frameworks and deployment providers from the community for building serverless applications.
19
19
20
-
Each section should contain folders named per version to avoid confusion between
21
-
the versions.
20
+
[Read the Development Guide](DEVELOPMENT_GUIDE.rst) for in-depth information on how to start making changes.
22
21
23
-
## Usage and Examples
24
-
Checkout the [How-To Guide](HOWTO.md) and [examples folder](examples/) for
25
-
detailed instructions on how to write AWS SAM templates and deploy them
26
-
to AWS CloudFormation
22
+
[Join the SAM developers channel (#samdev) on Slack](https://awssamopensource.splashthat.com/) to collaborate with fellow community members and the AWS SAM team.
After your CloudFormation Stack has completed creation, log an event to your CloudWatch Log Group + Stream. To see it in action, modify and run the command below:
14
+
15
+
```bash
16
+
# Replace YOUR_LOG_GROUP_NAME with the name generated by CloudFormation (e.g. example-logs-processor-CloudWatchLambdaLogsGroup-XXXXXX)
17
+
UNIX_TIME=$(date +%s) LOG_TIME=$((UNIX_TIME*1000))&& aws logs put-log-events --log-group-name "YOUR_LOG_GROUP_NAME" --log-stream-name "sam-log-stream" --log-events "[{\"message\": \"This won't be processed since it doesn't match the FilterPattern.\", \"timestamp\": $LOG_TIME}, {\"message\": \"This will be processed since it says Hello log processor.\", \"timestamp\": $LOG_TIME}]"
18
+
# NOTE: Subsequent logs will require adding `--sequence-token SEQUENCE_TOKEN` to the command
0 commit comments