chore(docs): update docs and prompt to emphasize pushing of necessary files (#1981)

Previously, only the buildspec.yml needed to be added to the source repo in order to build a pipeline. But now the buildspec checks the pipeline manifest to see which environment stages to deploy to (and only upgrades those envs), so both files (and `.workspace`)need to be checked into the user's repo. This updates docs and CLI prompts to reflect that change.

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

Author: huanjani

internal/pkg/cli/pipeline_init.go

@@ -209,11 +209,11 @@ func (o *initPipelineOpts) Execute() error {
 	return nil
 }
 
-// RequiredActions returns follow-up actions the user can take after successfully executing the command.
+// RequiredActions returns follow-up actions the user must take after successfully executing the command.
 func (o *initPipelineOpts) RequiredActions() []string {
 	return []string{
-		"Commit and push the generated buildspec and manifest file.",
-		fmt.Sprintf("Run %s to deploy your pipeline for the repository.", color.HighlightCode("copilot pipeline update")),
+		fmt.Sprintf("Commit and push the %s, %s, and %s files of your %s directory to your repository.", color.HighlightResource("buildspec.yml"), color.HighlightResource("pipeline.yml"), color.HighlightResource(".workspace"), color.HighlightResource("copilot")),
+		fmt.Sprintf("Run %s to create your pipeline.", color.HighlightCode("copilot pipeline update")),
 	}
 }
 
@@ -544,7 +544,9 @@ func (o *initPipelineOpts) createPipelineManifest() error {
 		manifestMsgFmt = "Pipeline manifest file for %s already exists at %s, skipping writing it.\n"
 	}
 	log.Successf(manifestMsgFmt, color.HighlightUserInput(o.repoName), color.HighlightResource(manifestPath))
-	log.Infoln("The manifest contains configurations for your CodePipeline resources, such as your pipeline stages and build steps.")
+	log.Infof(`The manifest contains configurations for your CodePipeline resources, such as your pipeline stages and build steps.
+Update the file to add additional stages, change the branch to be tracked, or add test commands or manual approval actions.
+`)
 	return nil
 }
 
@@ -584,7 +586,9 @@ func (o *initPipelineOpts) createBuildspec() error {
 		return err
 	}
 	log.Successf(buildspecMsgFmt, color.HighlightResource(buildspecPath))
-	log.Infoln("The buildspec contains the commands to build and push your container images to your ECR repositories.")
+	log.Infof(`The buildspec contains the commands to build and push your container images to your ECR repositories.
+Update the %s phase to unit test your services before pushing the images.
+`, color.HighlightResource("build"))
 
 	return nil
 }

site/content/docs/concepts/pipelines.md

@@ -24,14 +24,14 @@ Want to learn more about CodePipeline? Check out their [getting started docs](ht
 Creating a Pipeline requires only three steps:
 
 1. Preparing the pipeline structure.
-2. Committing the generated `buildspec.yml`.
+2. Committing and pushing the files generated in the `copilot/` directory.
 3. Creating the actual CodePipeline.
 
 Follow the three steps below, from your workspace root:
 
 ```bash
 $ copilot pipeline init
-$ git add copilot/buildspec.yml && git commit -m "Adding Pipeline Buildspec" && git push
+$ git add copilot/pipeline.yml copilot/buildspec.yml copilot/.workspace && git commit -m "Adding pipeline artifacts" && git push
 $ copilot pipeline update
 ```
 
@@ -55,7 +55,7 @@ This won't create your pipeline, but it will create some local files that will b
 
 ### Step 2: Updating the Pipeline manifest (optional)
 
-Just like your service has a simple manifest file, so does your pipeline. After you run `pipeline init`, two files are created: `pipeline.yml` and `buildspec.yml`, both in your `copilot/` directory. If you poke in, you'll see a file that looks something like this (for a service called "api-frontend" with two environments, "test" and "prod"):
+Just like your service has a simple manifest file, so does your pipeline. After you run `pipeline init`, two files are created: `pipeline.yml` and `buildspec.yml`, both in your `copilot/` directory. If you poke in, you'll see that the `pipeline.yml` looks something like this (for a service called "api-frontend" with two environments, "test" and "prod"):
 
 ```yaml
 # This YAML file defines the relationship and deployment ordering of your environments.
@@ -93,27 +93,31 @@ stages:
 
 There are 3 main parts of this file: the `name` field, which is the name of your CodePipeline, the `source` section, which details the repository and branch to track, and the `stages` section, which lists the environments you want this pipeline to deploy to. You can update this anytime, but you must run `copilot pipeline update` afterwards.
 
-Typically, you'll update this file if you add new environments you want to deploy to, or want to track a different branch.
+Typically, you'll update this file if you add new environments you want to deploy to, or want to track a different branch. The pipeline manifest is also where you may add a manual approval step before deployment or commands to run tests (see "Adding Tests," below) after deployment.
 
 ### Step 3: Updating the Buildspec (optional)
 
 Along with `pipeline.yml`, the `pipeline init` command also generated a `buildspec.yml` file in the `copilot/` directory. This contains the instructions for building and publishing your service. If you want to run any additional commands, besides `docker build`, such as unit tests or style checkers, feel free to add them to the buildspec's `build` phase.
 
 When this buildspec runs, it pulls down the version of Copilot which was used when you ran `pipeline init`, to ensure backwards compatibility.
 
-### Step 4: Creating your Pipeline
+### Step 4: Pushing New Files to your Repository
 
-Now that your `pipeline.yml` and `buildspec.yml` are created, check them in and push them to your repository. The `buildspec.yml` is needed for your pipeline's `build` stage to run successfully. Once you've done that, to actually create your pipeline run:
+Now that your `pipeline.yml`, `buildspec.yml`, and `.workspace` files have been created, add them to your repository. These files in your `copilot/` directory are required for your pipeline's `build` stage to run successfully. 
+
+### Step 5: Creating your Pipeline
+
+Here's the fun part! Run:
 
 `copilot pipeline update`
 
-This parses your `pipeline.yml`, creates a CodePipeline in the same account and region as your project and kicks off a pipeline execution. Log into the AWS Console to watch your pipeline go.
+This parses your `pipeline.yml`, creates a CodePipeline in the same account and region as your project and kicks off a pipeline execution. Log into the AWS Console to watch your pipeline go, or run `copilot pipeline status` to check in on its execution.
 
 ![Your completed CodePipeline](https://user-images.githubusercontent.com/828419/71861318-c7083980-30aa-11ea-80bb-4bea25bf5d04.png)
 
 ## Adding Tests
 
-Of course, one of the most important parts of a pipeline is the automated testing. To add your own test commands, include the commands you'd like to run after your deploy step in the `test_commands` section. If all the commands succeed, your change is promoted to the next stage. 
+Of course, one of the most important parts of a pipeline is the automated testing. To add tests, such as integration or end-to-end tests, that run after a deployment stage, include those commands in the `test_commands` section. If all the tests succeed, your change is promoted to the next stage. 
 
 Adding `test_commands` generates a CodeBuild project with the [aws/codebuild/amazonlinux2-x86_64-standard:3.0](https://docs.aws.amazon.com/codebuild/latest/userguide/build-env-ref-available.html) image - so most commands from Amazon Linux 2 (including `make`) are available for use. 
 
@@ -139,4 +143,4 @@ stages:
         - echo "woo! Tests passed"
     -
       name: prod
-```
+```