docs: Add sam publish command design doc #844

paoptu023 · 2018-12-07T18:19:48Z

Description of changes:
Design doc for adding a new command sam publish.

Checklist:

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

… app

designs/sam_publish_app_cmd.rst

…cept string

paoptu023 · 2018-12-12T00:53:32Z

Currently, when an app is first created by sam publish app it will be private by default. If no --acount-ids option is specified, the subsequent publish command runs don't change permissions. However, the following workflow may be confusing:

Run sam publish app -t template.yaml - app is created as private
Run sam publish app -t template.yaml --acount-ids '*' - app is updated and made public
Run sam publish app -t template.yaml - app is public

The permission state is different between 1 and 3.

jlhood

Overall, looks really good! Only blocker for me is the change in design around sharing (1 option instead of 3)

designs/sam_publish_app_cmd.rst

jlhood

Need to remove mention of permissions in a few places, but other than that, this looks solid!

designs/sam_publish_app_cmd.rst

heitorlessa · 2018-12-17T13:58:59Z

designs/sam_publish_app_cmd.rst

+              ...
+
+Build Lambda source code
+  Run ``sam build -t template.yaml -b ./build -o built-template.yaml`` to build all functions in the template and output


For the future: sam app publish could trigger a build if there's none so one could have the following ideal workflow:

sam init

make changes to SAM and define a app locally

sam deploy and test whether that works

sam publish

This is improvement outside of this command scope and something we are thinking about wider (invoke, package, etc) doing this build if not there.

heitorlessa · 2018-12-17T13:59:58Z

designs/sam_publish_app_cmd.rst

+  to upload code artifacts, readme and license files to S3 and generate the packaged template.
+
+Create new application in SAR
+  Run ``sam publish app -t ./packaged.yaml`` to publish a new application named my-app in SAR with the first version


It'd be great to have packaged.yaml as a default similarly to sam deploy does it today as it's less to remember and more straightforward from a CLI UX :)

We should cover this when doing the migration of package.

Note: sam deploy doesn't have a default value for the template Option.

heitorlessa · 2018-12-17T14:01:30Z

designs/sam_publish_app_cmd.rst

+
+  >>> sam publish app -t ./packaged.yaml
+  Publish Succeeded
+  Created new application with the following metadata:


Instead of giving metadata of the published app (e.g. sam app info instead) it'd be great to leave a AWS::Serverless::Application resource filled out with the information about this app newly published so one can go copy/paste into somewhere (slack, template, etc.).

Thanks for the suggestion! This can be added in a follow-up iteration to output CFN resource of the published app.

designs/sam_publish_app_cmd.rst

sthulb · 2018-12-17T13:50:19Z

designs/sam_publish_app_cmd.rst

+  created as 0.0.1. The app will be created as private by default. SAM CLI prints application created message, metadata
+  used to create application and link to the console details page.
+
+  >>> sam publish app -t ./packaged.yaml


For integration purposes, it would be cool if we printed a sample CFN resource that a user could copy & paste.

Thanks, please see comment above: #844 (comment)

sthulb · 2018-12-17T13:51:44Z

designs/sam_publish_app_cmd.rst

+   :depth: 2
+   :local:
+
+``sam publish app`` command


Are we ever expecting a different type to publish?

If not, perhaps the command structure should be sam app <publish|remove|foo|bar>

This would the main change I would implement for this doc. It would give a more structured feel and would pave the way to richer functionality in the future.

As Jacob has commented, the command itself should be an action instead of an entity to remain consistent with other sam commands.

sthulb · 2018-12-17T13:57:44Z

designs/sam_publish_app_cmd.rst

+
+1. SAM specification updates:
+
+  - Add "AWS::ServerlessRepo::Application" sepc in `SAM specification`.


typo sepc -> spec

Nice catch!

sthulb · 2018-12-17T14:02:32Z

designs/sam_publish_app_cmd.rst

+              CodeUri: ./source-code1
+              ...
+
+Build Lambda source code


This could be something sam app publish could do out of the box. Detect the last build date or diff the prebuild app in $PROJECT_DIR/.aws-sam/build against the $PROJECT_DIR

Out of scope for this command currently. This should be handled when we address this in other commands. Currently no command 'auto builds'.

sthulb · 2018-12-17T14:03:18Z

designs/sam_publish_app_cmd.rst

+====================================
+
+This is the design for a command to publish an application to `AWS Serverless Application Repository (SAR)`_ with a SAM
+template. It can be used to create a new application w/ its first version, update existing application's metadata, and


This could be something we could auto suggest, or implement flags for --bump-minor/patch

We thought about doing this like npm version, but this is out of scope for publish currently.

sthulb · 2018-12-17T14:05:31Z

designs/sam_publish_app_cmd.rst

+    To publish an application
+    $ sam publish app -t packaged.yaml --region <region>
+
+  Options:


Could we add the ability to share account IDs or chose to make the app completely public?

See comment above: #844 (comment)

paoptu023 · 2018-12-17T20:59:10Z

Removed the app subcommand from the design. Since we only support Serverless App Repo as the destination for now, app seems redundant and ambiguous. A destination option can be added in the future if we are going to support other destinations.

paoptu023 · 2018-12-21T22:38:56Z

Closing as released in v0.10.0 🎉

jfuss · 2018-12-22T00:47:08Z

@paoptu023 We want this merged. Designs are meant to be apart of the feature and exist to help understand past desicions and what is in or out of scope. Please resubmit the content that was in this PR. I can’t reopen since you deleted the branch.

paoptu023 · 2018-12-22T01:23:07Z

Reopen the PR

Vicky Wang added 4 commits November 30, 2018 14:01

Add sam publish app design doc

683a61e

Address comments

a1bfa61

Remove --meta-data flag, include updating app metadata in sam publish…

977fe04

… app

Minor modifications

08b5daf

paoptu023 mentioned this pull request Dec 7, 2018

[WIP] sam publish app design doc #819

Closed

6 tasks

paoptu023 requested a review from jfuss December 7, 2018 18:22

paoptu023 assigned jfuss Dec 7, 2018

jfuss requested changes Dec 7, 2018

View reviewed changes

Vicky Wang added 2 commits December 7, 2018 20:56

Address comments

adbcec9

Add examples in help text

94d0cec

paoptu023 requested a review from jlhood December 10, 2018 19:59

Clarify default private, add CLI output example

7171465

paoptu023 force-pushed the qwang-patch branch from d515ee9 to 7171465 Compare December 10, 2018 20:04

sriram-mv reviewed Dec 11, 2018

View reviewed changes

Minor changes

9454409

sriram-mv reviewed Dec 11, 2018

View reviewed changes

designs/sam_publish_app_cmd.rst Outdated Show resolved Hide resolved

Remove make-public and make-private options

10eb646

paoptu023 force-pushed the qwang-patch branch from 3098f83 to 10eb646 Compare December 11, 2018 22:54

Vicky Wang added 2 commits December 11, 2018 15:02

Clarify about not managing permisison without --acount-ids

cddb013

Remove use case for making an app private, change --account-ids to ac…

fefb085

…cept string

jlhood suggested changes Dec 12, 2018

View reviewed changes

designs/sam_publish_app_cmd.rst Outdated Show resolved Hide resolved

designs/sam_publish_app_cmd.rst Outdated Show resolved Hide resolved

designs/sam_publish_app_cmd.rst Outdated Show resolved Hide resolved

designs/sam_publish_app_cmd.rst Outdated Show resolved Hide resolved

Vicky Wang and others added 3 commits December 11, 2018 17:20

Fix typos

1f51100

Remove managing application permissions from scope

dd18e87

Merge branch 'develop' into qwang-patch

94d749a

This was referenced Dec 12, 2018

Create interface for sam publish app command paoptu023/aws-sam-cli#1

Closed

Implement sam publish app command #852

Merged

jlhood approved these changes Dec 12, 2018

View reviewed changes

designs/sam_publish_app_cmd.rst Outdated Show resolved Hide resolved

Vicky Wang added 2 commits December 12, 2018 11:07

Remove mention of permissions

841e846

Update documentation changes needed

a1a5f85

paoptu023 force-pushed the qwang-patch branch from 333c0b7 to a1a5f85 Compare December 13, 2018 21:30

heitorlessa reviewed Dec 17, 2018

View reviewed changes

sthulb reviewed Dec 17, 2018

View reviewed changes

Remove subcommand app

f990b6c

paoptu023 changed the title ~~[WIP] sam publish app design doc~~ [WIP] sam publish design doc Dec 17, 2018

paoptu023 closed this Dec 21, 2018

paoptu023 deleted the qwang-patch branch December 21, 2018 22:50

paoptu023 restored the qwang-patch branch December 22, 2018 01:18

Change doc link

508efb9

paoptu023 reopened this Dec 22, 2018

paoptu023 and others added 2 commits December 21, 2018 17:23

Merge branch 'develop' into qwang-patch

894c8ca

Change doc link in helper text

38562a7

paoptu023 changed the title ~~[WIP] sam publish design doc~~ docs: Add sam publish command design doc Dec 22, 2018

Vicky Wang added 2 commits December 25, 2018 13:02

Rename sam publish design doc

3ca187c

Fix HomePageUrl typo

4c19f8e

jfuss approved these changes Jan 8, 2019

View reviewed changes

Merge branch 'develop' into qwang-patch

703f40d

jfuss added the stage/accepted Accepted and will be fixed label Jan 8, 2019

jfuss merged commit 5558447 into aws:develop Jan 8, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: Add sam publish command design doc #844

docs: Add sam publish command design doc #844

paoptu023 commented Dec 7, 2018 •

edited

Loading

paoptu023 commented Dec 12, 2018

jlhood left a comment

jlhood left a comment

heitorlessa Dec 17, 2018

jfuss Dec 17, 2018

heitorlessa Dec 17, 2018

jfuss Dec 17, 2018

heitorlessa Dec 17, 2018

paoptu023 Dec 17, 2018

sthulb Dec 17, 2018

paoptu023 Dec 17, 2018

sthulb Dec 17, 2018

paoptu023 Dec 17, 2018

sthulb Dec 17, 2018

paoptu023 Dec 17, 2018

sthulb Dec 17, 2018

jfuss Dec 17, 2018

sthulb Dec 17, 2018

paoptu023 Dec 17, 2018

sthulb Dec 17, 2018

jfuss Dec 17, 2018

paoptu023 commented Dec 17, 2018

paoptu023 commented Dec 21, 2018

jfuss commented Dec 22, 2018

paoptu023 commented Dec 22, 2018


		1. SAM specification updates:

		- Add "AWS::ServerlessRepo::Application" sepc in `SAM specification`.

docs: Add sam publish command design doc #844

docs: Add sam publish command design doc #844

Conversation

paoptu023 commented Dec 7, 2018 • edited Loading

paoptu023 commented Dec 12, 2018

jlhood left a comment

Choose a reason for hiding this comment

jlhood left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

paoptu023 commented Dec 17, 2018

paoptu023 commented Dec 21, 2018

jfuss commented Dec 22, 2018

paoptu023 commented Dec 22, 2018

paoptu023 commented Dec 7, 2018 •

edited

Loading