Add SQITCH_ORIG_ environment variables.

I realized that `SQITCH_USER_NAME` and `SQITCH_USER_EMAIL`, on their surface,
would be expected to take precedence over values store in the configuration.
So I've changed the to do so, then added `SQITCH_ORIG_NAME` and
`SQITCH_ORIG_EMAIL` to serve as fallbacks for when configuration is *not*
set. They're called "ORIG" because the expectation is that they get set by an
originating host that executes Sqitch on some other host. The canonical
example is the simple shell script to run Sqitch on Docker:

  https://github.com/sqitchers/docker-sqitch/blob/master/docker-sqitch.sh

Changes

@@ -15,11 +15,16 @@ Revision history for Perl extension App::Sqitch
        a username and can't find one from other sources (such as a target
        URL), Sqitch has traditionally fallen back on the system username. This
        environment variable can now be used to override the system username.
-     - Added the `$SQITCH_USER_NAME` and `$SQITCH_USER_EMAIL` environment
+     - Added the `$SQITCH_USER_NAME` and `$SQITCH_USER_EMAIL`, environment
+       variables, which take precedence over the values of the `user.name` and
+       `user.email` config variables.
+     - Added they `$SQITCH_ORIG_NAME` and `$SQITCH_ORIG_EMAIL` environment
        variables. Traditionally, when the `user.name` and `user.email` config
-       variables have not been set, Sqitch has attempted to read the system
-       user and host information to derive these values. These new environment
-       variables can now be used to override these system-derived values.
+       variables have not been set, Sqitch has attempted to read the system user
+       and host information to derive these values. These new environment
+       variables can now be used to override these system-derived values. The
+       intention is to allow an originating host to set these values on another
+       host where Sqitch will actually execute.
 
 0.9997 2018-03-15T21:13:52Z
      - Fixed the Firebird engine to properly detect multiple instances of a

lib/App/Sqitch.pm

@@ -77,7 +77,10 @@ has user_name => (
     isa     => UserName,
     default => sub {
         my $self = shift;
-        $self->config->get( key => 'user.name' ) || $ENV{SQITCH_USER_NAME} || do {
+        $ENV{SQITCH_USER_NAME}
+            || $self->config->get( key => 'user.name' )
+            || $ENV{SQITCH_ORIG_NAME}
+        || do {
             my $sysname = $self->sysuser || hurl user => __(
                     'Cannot find your name; run sqitch config --user user.name "YOUR NAME"'
             );
@@ -103,7 +106,10 @@ has user_email => (
     isa     => UserEmail,
     default => sub {
         my $self = shift;
-        $self->config->get( key => 'user.email' ) || $ENV{SQITCH_USER_EMAIL} || do {
+         $ENV{SQITCH_USER_EMAIL}
+            || $self->config->get( key => 'user.email' )
+            || $ENV{SQITCH_ORIG_EMAIL}
+        || do {
             my $sysname = $self->sysuser || hurl user => __(
                 'Cannot infer your email address; run sqitch config --user user.email you@host.com'
             );

lib/sqitch-environment.pod

@@ -41,14 +41,32 @@ support it. See L<sqitch-passwords> for details.
 =item C<SQITCH_USER_NAME>
 
 Full name of the current user. Used to identify the user adding a change to a
-plan file or deploying a change. This value is a fallback for when the
-C<user.name> L<sqitch-config> variable is not set.
+plan file or deploying a change. Supersedes the <user.name> L<sqitch-config>
+variable.
 
 =item C<SQITCH_USER_EMAIL>
 
 Email address of the current user. Used to identify the user adding a change to
-a plan file or deploying a change. This value is a fallback for when the
-C<user.email> L<sqitch-config> variable is not set.
+a plan file or deploying a change. Supersedes the C<user.email> L<sqitch-config>
+variable.
+
+=item C<SQITCH_ORIG_NAME>
+
+Full name of the original user. Intended for use by scripts that run 
+Sqitch from another host, where the originating host user's identity should
+be passed to the execution host, such as
+L<this Docker script|https://github.com/sqitchers/docker-sqitch/blob/master/docker-sqitch.sh>.
+This value will be used only when neither the C<$SQITCH_USER_NAME> nor the
+C<user.name> L<sqitch-config> variable is set.
+
+=item C<SQITCH_ORIG_EMAIL>
+
+Email address of the original user. Intended for use by scripts that run 
+Sqitch on a separate host, where the originating host user's identity should
+be passed to the execution host, such as
+L<this Docker script|https://github.com/sqitchers/docker-sqitch/blob/master/docker-sqitch.sh>.
+This value will be used only when neither the C<$SQITCH_USER_EMAIL> nor the
+C<user.email> L<sqitch-config> variable is set.
 
 =item C<SQITCH_EDITOR>
 

t/base.t

@@ -2,7 +2,7 @@
 
 use strict;
 use warnings;
-use Test::More tests => 149;
+use Test::More tests => 153;
 #use Test::More 'no_plan';
 use Test::MockModule;
 use Path::Class;
@@ -78,8 +78,8 @@ ENV: {
 # Test go().
 GO: {
     local $ENV{SQITCH_USER} = "__barack__";
-    local $ENV{SQITCH_USER_NAME} = 'Barack Obama';
-    local $ENV{SQITCH_USER_EMAIL} = 'barack@whitehouse.gov';
+    local $ENV{SQITCH_ORIG_NAME} = 'Barack Obama';
+    local $ENV{SQITCH_ORIG_EMAIL} = 'barack@whitehouse.gov';
 
     my $mock = Test::MockModule->new('App::Sqitch::Command::help');
     my ($cmd, @params);
@@ -107,6 +107,16 @@ GO: {
         'Should have read user email from configuration';
     is_deeply $sqitch->options, { engine => 'sqlite' }, 'Should have options';
 
+    # Make sure USER_NAME and USER_EMAIL take precedence over configuration.
+    local $ENV{SQITCH_USER_NAME} = 'Michelle Obama';
+    local $ENV{SQITCH_USER_EMAIL} = 'michelle@whitehouse.gov';
+    is +App::Sqitch->go, 0, 'Should get 0 from go() again';
+    isa_ok $sqitch = $cmd->sqitch, 'App::Sqitch';
+    is $sqitch->user_name, 'Michelle Obama',
+        'Should have read user name from environment';
+    is $sqitch->user_email, 'michelle@whitehouse.gov',
+        'Should have read user email from environment';
+
     # Now make it die.
     sub puke { App::Sqitch::X->new(@_) } # Ensures we have trace frames.
     my $ex = puke(ident => 'ohai', message => 'OMGWTF!');