Skip to content

Commit 4de254c

Browse files
sriram-mvsriram-mv
authored
design: New root command help text for sam (#4628)
* design: New root command help text for `sam` * feedback: address design feedback
1 parent fa6d837 commit 4de254c

File tree

2 files changed

+206
-3
lines changed

2 files changed

+206
-3
lines changed

‎designs/_template.md

+3-3
Original file line numberDiff line numberDiff line change
@@ -53,11 +53,11 @@ Design
5353
of your implementation, relationships* *between components, constraints,
5454
etc.*
5555

56-
`.samrc` Changes
56+
``samconfig.toml`` Changes
5757
----------------
5858

5959
*Explain the new configuration entries, if any, you want to add to
60-
.samrc*
60+
`samconfig.toml`*
6161

6262
Security
6363
--------
@@ -78,7 +78,7 @@ connection secured**
7878
**Are you reading/writing to a temporary folder? If so, what is this
7979
used for and when do you clean up?**
8080

81-
**How do you validate new .samrc configuration?**
81+
**How do you validate new `samconfig.toml` configuration?**
8282

8383
What is your Testing Plan (QA)?
8484
===============================

‎designs/root_help_text_design.md

+203
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,203 @@
1+
AWS SAM CLI: Root command help test Design
2+
==========================================
3+
4+
What is the problem?
5+
--------------------
6+
7+
Currently AWS SAM CLI's root command help text does not showcase a coherent story on how to develop a serverless application.
8+
9+
Current state of the world as of v1.71.0
10+
11+
```
12+
Usage: sam [OPTIONS] COMMAND [ARGS]...
13+
14+
AWS Serverless Application Model (SAM) CLI
15+
16+
The AWS Serverless Application Model extends AWS CloudFormation to provide a
17+
simplified way of defining the Amazon API Gateway APIs, AWS Lambda
18+
functions, and Amazon DynamoDB tables needed by your serverless application.
19+
You can find more in-depth guide about the SAM specification here:
20+
https://github.com/awslabs/serverless-application-model.
21+
22+
Options:
23+
--debug Turn on debug logging to print debug message generated by SAM
24+
CLI and display timestamps.
25+
--version Show the version and exit.
26+
--info
27+
-h, --help Show this message and exit.
28+
29+
Commands:
30+
init Init an AWS SAM application.
31+
validate Validate an AWS SAM template.
32+
build Build your Lambda function code
33+
local Run your Serverless application locally for quick development...
34+
package Package an AWS SAM application.
35+
deploy Deploy an AWS SAM application.
36+
delete Delete an AWS SAM application and the artifacts created by sam
37+
deploy.
38+
logs Fetch logs for a function
39+
publish Publish a packaged AWS SAM template to the AWS Serverless
40+
Application Repository.
41+
traces Fetch AWS X-Ray traces
42+
sync Sync a project to AWS
43+
pipeline Manage the continuous delivery of the application
44+
```
45+
46+
What will be changed?
47+
---------------------
48+
49+
The help text should showcase the stages in the lifecycle of development in a serverless application.
50+
51+
```
52+
Usage: sam [OPTIONS] COMMAND [ARGS]...
53+
54+
AWS Serverless Application Model (SAM) CLI
55+
56+
The AWS Serverless Application Model extends AWS CloudFormation to provide a
57+
simplified way of defining the Amazon API Gateway APIs, AWS Lambda
58+
functions, and Amazon DynamoDB tables needed by your serverless application.
59+
You can find more in-depth guide about the SAM specification here:
60+
https://github.com/awslabs/serverless-application-model.
61+
62+
63+
Commands:
64+
65+
*Create an App!*
66+
67+
init Init an AWS SAM application
68+
69+
*Develop your app!*
70+
71+
build Build your Lambda Function code
72+
local Run your serverless function locally
73+
validate Validate an AWS SAM template
74+
sync (NEW) Sync a project to AWS
75+
76+
*Deploy your app!*
77+
78+
package Package an AWS SAM application
79+
deploy Deploy an AWS SAM application
80+
81+
*Monitor your app!*
82+
83+
logs Fetch logs for a function
84+
traces Fetch AWS X-Ray traces
85+
86+
*And More!*
87+
88+
delete Delete an AWS SAM application and the artifacts created by sam deploy.
89+
list (NEW) Get local and deployed state of serverless application.
90+
pipeline Manage the continuous delivery of the application
91+
publish Publish a packaged AWS SAM template to AWS Serverless Application Repository for sharing.
92+
93+
94+
Global Options:
95+
--debug Turn on debug logging to print debug message generated by SAM
96+
CLI and display timestamps.
97+
--version Show the version and exit.
98+
--info
99+
-h, --help Show this message and exit.
100+
```
101+
102+
103+
Success criteria for the change
104+
-------------------------------
105+
106+
* The success criteria for the change is less time spent on the help text to understand which part of the lifecycle a particular command operates in.
107+
* Increased confidence that the tool will help the user move in the right direction for their application.
108+
109+
Out-of-Scope
110+
------------
111+
* Changes in the sub-command help text.
112+
113+
114+
User Experience Walkthrough
115+
---------------------------
116+
117+
Implementation
118+
==============
119+
120+
CLI Changes
121+
-----------
122+
123+
CLI interface will remain the same.
124+
125+
### Breaking Change
126+
127+
N/A
128+
129+
Design
130+
------
131+
132+
There will be a separate implementation PR to showcase the changes, but it will use `click` to override commands options and help text.
133+
134+
`samconfig.toml` Changes
135+
----------------
136+
137+
N/A
138+
139+
Security
140+
--------
141+
142+
**What new dependencies (libraries/cli) does this change require?**
143+
144+
* No new dependencies
145+
146+
**What other Docker container images are you using?**
147+
148+
N/A
149+
150+
**Are you creating a new HTTP endpoint? If so explain how it will be
151+
created & used**
152+
153+
N/A
154+
155+
**Are you connecting to a remote API? If so explain how is this
156+
connection secured**
157+
158+
N/A
159+
160+
**Are you reading/writing to a temporary folder? If so, what is this
161+
used for and when do you clean up?**
162+
163+
N/A
164+
165+
**How do you validate new samconfig.toml configuration?**
166+
167+
N/A
168+
169+
What is your Testing Plan (QA)?
170+
===============================
171+
172+
Goal
173+
----
174+
175+
Pre-requesites
176+
--------------
177+
178+
Test Scenarios/Cases
179+
--------------------
180+
181+
Expected Results
182+
----------------
183+
184+
Pass/Fail
185+
---------
186+
187+
Documentation Changes
188+
=====================
189+
190+
Open Issues
191+
============
192+
193+
Task Breakdown
194+
==============
195+
196+
- \[x\] Send a Pull Request with this design document
197+
- \[ \] Build the command line interface
198+
- \[ \] Build the underlying library
199+
- \[ \] Unit tests
200+
- \[ \] Functional Tests
201+
- \[ \] Integration tests
202+
- \[ \] Run all tests on Windows
203+
- \[ \] Update documentation

0 commit comments

Comments
 (0)