add docs and NEWS for MasterShellCommand env argument

master/NEWS

@@ -4,11 +4,12 @@ Major User visible changes in Buildbot.             -*- outline -*-
 
 * NEXT RELEASE
 
-** New configuration key, 'changeCacheSize'
+** New Requirements
 
-This sets the number of changes that buildbot will keep in memory at once.
-Users of distributed version control systems should consider setting this to a
-high value (e.g. 10,000)
+The Buildmaster now requires Jinja-2.1 or higher.
+
+Both master and slave now require Twisted-8.0.0.  Although Twisted-2.5.0 may
+still work, it is not tested and not supported.
 
 ** Command-line options changed
 
@@ -22,12 +23,16 @@ command the following changes were done:
 Added new `-n|--no-logrotate` flag to create-master command which disables
 internal logging and log rotation mechanism in buildbot.tac (ticket #973)
 
-** New Requirements
+** MasterShellCommand semantics change
 
-The Buildmaster now requires Jinja-2.1 or higher.
+The MasterShellCommand now provides the buildmaster's environment to the step
+by default; pass env={} to pass a clean environment, instead.
 
-Both master and slave now require Twisted-8.0.0.  Although Twisted-2.5.0 may
-still work, it is not tested and not supported.
+** New configuration key, 'changeCacheSize'
+
+This sets the number of changes that buildbot will keep in memory at once.
+Users of distributed version control systems should consider setting this to a
+high value (e.g. 10,000)
 
 ** New libvirt-based Latent Buildslave Support
 

master/docs/cfg-buildsteps.texinfo

@@ -1851,6 +1851,10 @@ f.addStep(MasterShellCommand(command="""
     mv widgetsoft-new.tar.gz widgetsoft-`date +%a`.tar.gz"""))
 @end example
 
+Note that, by default, this step passes a copy of the buildmaster's environment
+variables to the subprocess.  To pass an explicit environment instead, add an
+@code{env=@{..@}} argument.
+
 @node Triggering Schedulers
 @subsection Triggering Schedulers
 @bsindex buildbot.steps.trigger.Trigger