Cherry-pick in lost/abandoned commits from 9.x (#3072)

* VM setup tips (#3036)

* Update local-development.md to reference committing DrupalVM files.

* New guidelines for contribution. (#3045)

* Adding replication and verification step sections and clean up formatting.

* Adding new guidelines for PRs to the CONTRIBUTING docs.

* Fixes #2964: When manually deploying using a tag also push that tag to source repo. (#2992)

* Adding a cutSourceTag method and invoking when deploying tag.

* Set default deploy.tag_source config setting and check it when deploying.

* Refactoring to use a single cutTag method.

* Remove line about expectation you already have a tag on your source before you tag a release.

* Warn if user is creating a tag but tag_source option is false.

* Updating deploy documentation.

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,5 +1,25 @@
-Fixes # .
+Fixes # 
+--------
 
 Changes proposed:
+---------
+(What are you proposing we change?)
+
 -
 -
+
+Steps to replicate the issue:
+----------
+(If this PR is not fixing a defect/bug, you can remove this section.)
+
+1. 
+2. 
+
+Steps to verify the solution:
+-----------
+(How does someone verify that this does what you think does?)
+
+1.
+2. 
+
+

docs/CONTRIBUTING.md

@@ -35,3 +35,10 @@ To execute the same "release" testing that is performed during CI execution, run
 ## PHPUnit
 
 See [the PHPUnit section in the automated testing docs](testing.md#PHPUnit)
+
+# Submitting Pull Requests
+
+Changes should be submitted as Github Pull Requests to the project repository. To help with review, pull requests are expected to adhere to two main guidelines:
+
+1. PRs should be atomic and targeted at a single issue rather than broad-scope.
+2. PRs are expected to follow the template defined by the project in `.github/ISSUE_TEMPLATE.md` 

docs/deploy.md

@@ -54,6 +54,10 @@ To create a new git tag for the artifact (rather than committing to a branch) ru
 
 This will generate the artifact, tag it with `1.0.0`, and push it to the remotes defined in blt.yml.
 
+When deploying a tag to the artifact repo, if the config option `deploy.tag_source` is set to TRUE, BLT will also create the supplied tag on the source repository. This makes it easier to verify the source commit upon which an artifact tag is based.
+
+*Note* however that BLT _does not_ automatically push the tag created on the source repository to its remote.
+
 ## Modifying the artifact
 
 The artifact is built by running the `artifact:build` target, which does the following:

docs/local-development.md

@@ -27,6 +27,11 @@ To use [Drupal VM](http://www.drupalvm.com/) with a Drupal project that is gener
 1. Create & boot the VM
 
         blt vm
+        
+1. Commit all resulting files, including `box/config.yml` and `Vagrantfile`.
+
+        git add -A
+        git commit -m <your commit meessage>
 
 1. Install Drupal
 
@@ -39,6 +44,8 @@ To use [Drupal VM](http://www.drupalvm.com/) with a Drupal project that is gener
 
 There are also other changes you can make if you choose to match the Acquia Cloud server configuration more closely. See Drupal VM's example configuration changes in Drupal VM's `examples/acquia/acquia.overrides.yml` file.
 
+Subsequently, you should use `vagrant` commands to interact with the VM. Do not re-run `blt vm`. For instance, use `vagrant up` to start the VM, and `vagrant halt` to stop it.
+
 Note: With a Drupal VM setup, BLT expects all commands (with the exception of commands in the `blt vm` namespace), to be executed within the VM. To SSH into the VM, simply run `vagrant ssh` as you did in the "Install Drupal" step above.
 
 ### Drupal VM and Behat tests

src/Robo/Commands/Deploy/DeployCommand.php

@@ -19,6 +19,7 @@ class DeployCommand extends BltTasks {
   protected $commitMessage;
   protected $excludeFileTemp;
   protected $deployDir;
+  protected $tagSource;
 
   /**
    * This hook will fire for all commands in this command file.
@@ -28,6 +29,7 @@ class DeployCommand extends BltTasks {
   public function initialize() {
     $this->excludeFileTemp = $this->getConfigValue('deploy.exclude_file') . '.tmp';
     $this->deployDir = $this->getConfigValue('deploy.dir');
+    $this->tagSource = $this->getConfigValue('deploy.tag_source', TRUE);
   }
 
   /**
@@ -53,12 +55,15 @@ public function deploy($options = [
     $this->checkDirty($options);
 
     if (!$options['tag'] && !$options['branch']) {
-      $this->say("Typically, you would only create a tag if you currently have a tag checked out on your source repository.");
       $this->createTag = $this->confirm("Would you like to create a tag?", $this->createTag);
     }
     $this->commitMessage = $this->getCommitMessage($options);
 
     if ($options['tag'] || $this->createTag) {
+      // Warn if they're creating a tag and we won't tag the source for them.
+      if (!$this->tagSource) {
+        $this->say("Config option deploy.tag_source if FALSE. The source repo will not be tagged.");
+      }
       $this->deployToTag($options);
     }
     else {
@@ -188,7 +193,14 @@ protected function deployToTag($options) {
     $this->checkoutLocalDeployBranch();
     $this->build();
     $this->commit();
-    $this->cutTag();
+    $this->cutTag('build');
+
+    // Check the deploy.tag_source config value and also tag the source repo if
+    // it is set to TRUE (the default).
+    if ($this->tagSource) {
+      $this->cutTag('source');
+    }
+
     $this->push($this->tagName, $options);
   }
 
@@ -531,15 +543,22 @@ protected function push($identifier, $options) {
 
   /**
    * Creates a tag on the build repository.
+   *
+   * @param $repo
+   *   The repo in which a tag should be cut.
    */
-  protected function cutTag() {
-    $this->taskExecStack()
+  protected function cutTag($repo = 'build') {
+    $execStack = $this->taskExecStack()
       ->exec("git tag -a {$this->tagName} -m '{$this->commitMessage}'")
       ->setVerbosityThreshold(VerbosityThresholdInterface::VERBOSITY_VERBOSE)
-      ->stopOnFail()
-      ->dir($this->deployDir)
-      ->run();
-    $this->say("The tag {$this->tagName} was created for the build artifact.");
+      ->stopOnFail();
+
+    if ($repo == 'build') {
+      $execStack->dir($this->deployDir);
+    }
+
+    $execStack->run();
+    $this->say("The tag {$this->tagName} was created on the {$repo} repository.");
   }
 
   /**

template/blt/blt.yml

@@ -21,6 +21,10 @@ git:
   default_branch: master
   remotes: []
 
+deploy:
+  # When manually deploying a tag, also tag the source repository.
+  tag_source: TRUE
+
 drush:
   # You can set custom project aliases in drush/sites/*.site.yml.
   aliases: