add comments for build/depploy/create commands

cli/cmd/create.go

@@ -142,7 +142,7 @@ func init() {
 		&image,
 		"image",
 		"",
-		"if the source is \"registry\", the image to use, in image-path:tag format",
+		"if the source is \"registry\", the image to use, in repository:tag format",
 	)
 }
 

cli/cmd/deploy/build.go

@@ -8,6 +8,7 @@ import (
 	"github.com/porter-dev/porter/cli/cmd/pack"
 )
 
+// BuildAgent builds a new Docker container image for a new version of an application
 type BuildAgent struct {
 	*SharedOpts
 
@@ -17,6 +18,7 @@ type BuildAgent struct {
 	imageExists bool
 }
 
+// BuildDocker uses the local Docker daemon to build the image
 func (b *BuildAgent) BuildDocker(dockerAgent *docker.Agent, dst, tag string) error {
 	opts := &docker.BuildOpts{
 		ImageRepo:    b.imageRepo,
@@ -31,6 +33,7 @@ func (b *BuildAgent) BuildDocker(dockerAgent *docker.Agent, dst, tag string) err
 	)
 }
 
+// BuildPack uses the cloud-native buildpack client to build a container image
 func (b *BuildAgent) BuildPack(dockerAgent *docker.Agent, dst, tag string) error {
 	// retag the image with "pack-cache" tag so that it doesn't re-pull from the registry
 	if b.imageExists {

cli/cmd/deploy/create.go

@@ -18,6 +18,8 @@ type CreateAgent struct {
 	CreateOpts *CreateOpts
 }
 
+// CreateOpts are required options for creating a new application on Porter: the
+// "kind" (web, worker, job) and the name of the application.
 type CreateOpts struct {
 	*SharedOpts
 
@@ -25,11 +27,15 @@ type CreateOpts struct {
 	ReleaseName string
 }
 
+// GithubOpts are the options for linking a Github source to the app
 type GithubOpts struct {
 	Branch string
 	Repo   string
 }
 
+// CreateFromGithub uses the branch/repo to link the Github source for an application.
+// This function attempts to find a matching repository in the list of linked repositories
+// on Porter. If one is found, it will use that repository as the app source.
 func (c *CreateAgent) CreateFromGithub(
 	ghOpts *GithubOpts,
 	overrideValues map[string]interface{},
@@ -144,6 +150,7 @@ func (c *CreateAgent) CreateFromGithub(
 	return subdomain, nil
 }
 
+// CreateFromRegistry deploys a new application from an existing Docker repository + tag.
 func (c *CreateAgent) CreateFromRegistry(
 	image string,
 	overrideValues map[string]interface{},
@@ -200,6 +207,8 @@ func (c *CreateAgent) CreateFromRegistry(
 	return subdomain, nil
 }
 
+// CreateFromDocker uses a local build context and a local Docker daemon to build a new
+// container image, and then deploys it onto Porter.
 func (c *CreateAgent) CreateFromDocker(
 	overrideValues map[string]interface{},
 ) (string, error) {
@@ -327,10 +336,6 @@ func (c *CreateAgent) CreateFromDocker(
 	return subdomain, nil
 }
 
-type CreateConfig struct {
-	DockerfilePath string
-}
-
 // HasDefaultDockerfile detects if there is a dockerfile at the path `./Dockerfile`
 func (c *CreateAgent) HasDefaultDockerfile(buildPath string) bool {
 	dockerFilePath := filepath.Join(buildPath, "./Dockerfile")
@@ -340,6 +345,9 @@ func (c *CreateAgent) HasDefaultDockerfile(buildPath string) bool {
 	return err == nil && !os.IsNotExist(err) && !info.IsDir()
 }
 
+// GetImageRepoURL creates the image repository url by finding the first valid image
+// registry linked to Porter, and then generates a new name of the form:
+// `{registry}/{name}-{namespace}`
 func (c *CreateAgent) GetImageRepoURL(name, namespace string) (uint, string, error) {
 	// get all image registries linked to the project
 	// get the list of namespaces
@@ -369,6 +377,8 @@ func (c *CreateAgent) GetImageRepoURL(name, namespace string) (uint, string, err
 	return regID, imageURI, nil
 }
 
+// GetLatestTemplateVersion retrieves the latest template version for a specific
+// Porter template from the chart repository.
 func (c *CreateAgent) GetLatestTemplateVersion(templateName string) (string, error) {
 	templates, err := c.Client.ListTemplates(
 		context.Background(),
@@ -394,6 +404,8 @@ func (c *CreateAgent) GetLatestTemplateVersion(templateName string) (string, err
 	return version, nil
 }
 
+// GetLatestTemplateDefaultValues gets the default config (`values.yaml`) set for a specific
+// template.
 func (c *CreateAgent) GetLatestTemplateDefaultValues(templateName, templateVersion string) (map[string]interface{}, error) {
 	chart, err := c.Client.GetTemplate(
 		context.Background(),

cli/cmd/deploy/deploy.go

@@ -139,10 +139,13 @@ func NewDeployAgent(client *api.Client, app string, opts *DeployOpts) (*DeployAg
 	return deployAgent, nil
 }
 
+// GetBuildEnv retrieves the build env from the release config and returns it
 func (d *DeployAgent) GetBuildEnv() (map[string]string, error) {
 	return GetEnvFromConfig(d.release.Config)
 }
 
+// SetBuildEnv sets the build env vars in the process so that other commands can
+// use them
 func (d *DeployAgent) SetBuildEnv(envVars map[string]string) error {
 	d.env = envVars
 
@@ -162,6 +165,7 @@ func (d *DeployAgent) SetBuildEnv(envVars map[string]string) error {
 	return nil
 }
 
+// WriteBuildEnv writes the build env to either a file or stdout
 func (d *DeployAgent) WriteBuildEnv(fileDest string) error {
 	// join lines together
 	lines := make([]string, 0)
@@ -185,6 +189,8 @@ func (d *DeployAgent) WriteBuildEnv(fileDest string) error {
 	return nil
 }
 
+// Build uses the deploy agent options to build a new container image from either
+// buildpack or docker.
 func (d *DeployAgent) Build() error {
 	// if build is not local, fetch remote source
 	var dst string
@@ -247,10 +253,15 @@ func (d *DeployAgent) Build() error {
 	return buildAgent.BuildPack(d.agent, dst, d.tag)
 }
 
+// Push pushes a local image to the remote repository linked in the release
 func (d *DeployAgent) Push() error {
 	return d.agent.PushImage(fmt.Sprintf("%s:%s", d.imageRepo, d.tag))
 }
 
+// UpdateImageAndValues updates the current image for a release, along with new
+// configuration passed in via overrrideValues. If overrideValues is nil, it just
+// reuses the configuration set for the application. If overrideValues is not nil,
+// it will merge the overriding values with the existing configuration.
 func (d *DeployAgent) UpdateImageAndValues(overrideValues map[string]interface{}) error {
 	mergedValues := utils.CoalesceValues(d.release.Config, overrideValues)
 
@@ -279,7 +290,8 @@ func (d *DeployAgent) UpdateImageAndValues(overrideValues map[string]interface{}
 	)
 }
 
-// HELPER METHODS
+// GetEnvFromConfig gets the env vars for a standard Porter template config. These env
+// vars are found at `container.env.normal`.
 func GetEnvFromConfig(config map[string]interface{}) (map[string]string, error) {
 	envConfig, err := getNestedMap(config, "container", "env", "normal")
 

cli/cmd/deploy/shared.go

@@ -1,5 +1,6 @@
 package deploy
 
+// SharedOpts are common options for build, create, and deploy agents
 type SharedOpts struct {
 	ProjectID       uint
 	ClusterID       uint