Skip to content

Files

Latest commit

 

History

History
203 lines (138 loc) · 5.17 KB

root_help_text_design.md

File metadata and controls

203 lines (138 loc) · 5.17 KB

AWS SAM CLI: Root command help test Design

What is the problem?

Currently AWS SAM CLI's root command help text does not showcase a coherent story on how to develop a serverless application.

Current state of the world as of v1.71.0

Usage: sam [OPTIONS] COMMAND [ARGS]...

  AWS Serverless Application Model (SAM) CLI

  The AWS Serverless Application Model extends AWS CloudFormation to provide a
  simplified way of defining the Amazon API Gateway APIs, AWS Lambda
  functions, and Amazon DynamoDB tables needed by your serverless application.
  You can find more in-depth guide about the SAM specification here:
  https://github.com/awslabs/serverless-application-model.

Options:
  --debug     Turn on debug logging to print debug message generated by SAM
              CLI and display timestamps.
  --version   Show the version and exit.
  --info
  -h, --help  Show this message and exit.

Commands:
  init      Init an AWS SAM application.
  validate  Validate an AWS SAM template.
  build     Build your Lambda function code
  local     Run your Serverless application locally for quick development...
  package   Package an AWS SAM application.
  deploy    Deploy an AWS SAM application.
  delete    Delete an AWS SAM application and the artifacts created by sam
            deploy.
  logs      Fetch logs for a function
  publish   Publish a packaged AWS SAM template to the AWS Serverless
            Application Repository.
  traces    Fetch AWS X-Ray traces
  sync      Sync a project to AWS
  pipeline  Manage the continuous delivery of the application

What will be changed?

The help text should showcase the stages in the lifecycle of development in a serverless application.

Usage: sam [OPTIONS] COMMAND [ARGS]...

  AWS Serverless Application Model (SAM) CLI

  The AWS Serverless Application Model extends AWS CloudFormation to provide a
  simplified way of defining the Amazon API Gateway APIs, AWS Lambda
  functions, and Amazon DynamoDB tables needed by your serverless application.
  You can find more in-depth guide about the SAM specification here:
  https://github.com/awslabs/serverless-application-model.


Commands:

  *Create an App!*

      init            Init an AWS SAM application

  *Develop your app!*

      build           Build your Lambda Function code
      local           Run your serverless function locally
      validate        Validate an AWS SAM template
      sync (NEW)      Sync a project to AWS

  *Deploy your app!*

      package         Package an AWS SAM application
      deploy          Deploy an AWS SAM application

  *Monitor your app!*

      logs            Fetch logs for a function
      traces          Fetch AWS X-Ray traces

  *And More!*

      delete          Delete an AWS SAM application and the artifacts created by sam deploy.
      list (NEW)      Get local and deployed state of serverless application.
      pipeline        Manage the continuous delivery of the application
      publish         Publish a packaged AWS SAM template to AWS Serverless Application Repository for sharing.


Global Options:
    --debug     Turn on debug logging to print debug message generated by SAM
                CLI and display timestamps.
    --version   Show the version and exit.
    --info
    -h, --help  Show this message and exit.

Success criteria for the change

  • 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.
  • Increased confidence that the tool will help the user move in the right direction for their application.

Out-of-Scope

  • Changes in the sub-command help text.

User Experience Walkthrough

Implementation

CLI Changes

CLI interface will remain the same.

Breaking Change

N/A

Design

There will be a separate implementation PR to showcase the changes, but it will use click to override commands options and help text.

samconfig.toml Changes

N/A

Security

What new dependencies (libraries/cli) does this change require?

  • No new dependencies

What other Docker container images are you using?

N/A

Are you creating a new HTTP endpoint? If so explain how it will be created & used

N/A

Are you connecting to a remote API? If so explain how is this connection secured

N/A

Are you reading/writing to a temporary folder? If so, what is this used for and when do you clean up?

N/A

How do you validate new samconfig.toml configuration?

N/A

What is your Testing Plan (QA)?

Goal

Pre-requesites

Test Scenarios/Cases

Expected Results

Pass/Fail

Documentation Changes

Open Issues

Task Breakdown

  • Send a Pull Request with this design document
  • Build the command line interface
  • Build the underlying library
  • Unit tests
  • Functional Tests
  • Integration tests
  • Run all tests on Windows
  • Update documentation