Merge remote-tracking branch 'jenkinsci/master' into cleanup

Conflicts:
	TUTORIAL.md

CHANGES.md

@@ -2,6 +2,23 @@
 
 Only noting significant user changes, not internal code cleanups and minor bug fixes.
 
+## 1.11 (not yet released)
+* [JENKINS-30346](https://issues.jenkins-ci.org/browse/JENKINS-30346): added a cross platform `deleteDir` step to recursively delete a directory and its contents.
+
+## 1.10 (Aug 31 2015)
+
+* [JENKINS-30122](https://issues.jenkins-ci.org/browse/JENKINS-30122): regression in usage of the Authorize Project plugin in 1.10-beta-1.
+* [JENKINS-29739](https://issues.jenkins-ci.org/browse/JENKINS-29739): _Snippet Generator_ did not work for `build` with exactly one parameter.
+* [JENKINS-29169](https://issues.jenkins-ci.org/browse/JENKINS-29169): `build('otherWorkflow').buildVariables` can now be used to access variables set using `env.KEY = 'value'` notation.
+
+## 1.10-beta-1 (Aug 21 2015)
+
+* [JENKINS-26942](https://issues.jenkins-ci.org/browse/JENKINS-26942): added `stash` and `unstash` steps (deprecating `unarchive`).
+* [JENKINS-26135](https://issues.jenkins-ci.org/browse/JENKINS-26135): expand global library functionality to allow predefined variables and even custom DSLs.
+* [JENKINS-29890](https://issues.jenkins-ci.org/browse/JENKINS-29890): `input` step submitter was not being consistently logged.
+* [JENKINS-25879](https://issues.jenkins-ci.org/browse/JENKINS-25879), [JENKINS-29875](https://issues.jenkins-ci.org/browse/JENKINS-29875): New API to run long lived tasks that could block on I/O in a separate thread avoiding to block main CPS VM thread.
+* [JENKINS-29653](https://issues.jenkins-ci.org/browse/JENKINS-29653): visual tweak to _Snippet Generator_.
+
 ## 1.9 (Aug 06 2015)
 
 * _Running Steps_ link is now called _Workflow Steps_ as it will show steps for workflows that have long since completed.

COMPATIBILITY.md

@@ -8,16 +8,14 @@ Entries list the class name serving as the entry point to the relevant functiona
 
 ## SCMs
 
-See [this guide](scm-step/README.md#supporting-workflow-from-an-scm-plugin) for making `SCM`s compatible.
-
 - [X] `GitSCM` (`git`): supported as of 2.3; native `git` step also bundled
 - [X] `SubversionSCM` (`subversion`): supported as of 2.5; native `svn` step also bundled
 - [X] `MercurialSCM` (`mercurial`): supported as of 1.51
 - [X] `PerforceScm` (`p4`, not the older `perforce`): supported as of 1.2.0
 - [ ] `DimensionsSCM` (`dimensionsscm`): [JENKINS-26165](https://issues.jenkins-ci.org/browse/JENKINS-26165)
 - [ ] `IntegritySCM` (`integrity-plugin`): [JENKINS-27140](https://issues.jenkins-ci.org/browse/JENKINS-27140)
 - [ ] `RepoScm` (`repo`): [JENKINS-26836](https://issues.jenkins-ci.org/browse/JENKINS-26836)
-- [ ] `teamconcert`: [JENKINS-27464](https://issues.jenkins-ci.org/browse/JENKINS-27464)
+- [X] `teamconcert`: supported as of 1.9.4
 - [X] `CVSSCM` (`cvs`): scheduled to be supported in 2.13
 
 ## Build steps and post-build actions
@@ -29,14 +27,14 @@ See [this guide](scm-step/README.md#supporting-workflow-from-an-scm-plugin) for
 - [X] `Mailer` (`mailer`)
 - [X] `CopyArtifact` (`copyartifact`): [JENKINS-24887](https://issues.jenkins-ci.org/browse/JENKINS-24887) in 1.34
 - [ ] `DeployPublisher` (`deployer-framework`): [JENKINS-25976](https://issues.jenkins-ci.org/browse/JENKINS-25976)
-- [ ] `FindBugsPublisher` and similar (`analysis-core` and downstream): [JENKINS-25977](https://issues.jenkins-ci.org/browse/JENKINS-25977)
-- [ ] `ExtendedEmailPublisher` (`email-ext`): [PR 97](https://github.com/jenkinsci/email-ext-plugin/pull/97)
+- [X] Analysis publishers (e.g., `FindBugsPublisher`): supported as of `analysis-core` 1.73 and downstream plugins (e.g., `findbugs` 4.62)
+- [ ] `ExtendedEmailPublisher` (`email-ext`): [PR 107](https://github.com/jenkinsci/email-ext-plugin/pull/107)
 - [ ] `Ant` (`ant`): [JENKINS-26056](https://issues.jenkins-ci.org/browse/JENKINS-26056)
 - [ ] `Maven` (home TBD): [JENKINS-26057](https://issues.jenkins-ci.org/browse/JENKINS-26057)
 - [ ] `XShellBuilder` (`xshell`): [JENKINS-26169](https://issues.jenkins-ci.org/browse/JENKINS-26169)
-- [ ] `DockerBuilder` (`docker-build-step`): [JENKINS-26178](https://issues.jenkins-ci.org/browse/JENKINS-26178)
+- [ ] ~~`DockerBuilder` (`docker-build-step`): [JENKINS-26178](https://issues.jenkins-ci.org/browse/JENKINS-26178)~~
 - [ ] `CucumberTestResultArchiver` (`cucumber-testresult-plugin`): [JENKINS-26340](https://issues.jenkins-ci.org/browse/JENKINS-26340)
-- [ ] `HtmlPublisher` (`htmlpublisher`): [JENKINS-26343](https://issues.jenkins-ci.org/browse/JENKINS-26343)
+- [X] `HtmlPublisher` (`htmlpublisher`): supported as of 1.6
 - [ ] `JaCoCoPublisher` (`jacoco`): [JENKINS-27120](https://issues.jenkins-ci.org/browse/JENKINS-27120)
 - [ ] `Publisher` (`testng`): [JENKINS-27121](https://issues.jenkins-ci.org/browse/JENKINS-27121)
 - [ ] `GroovyPostbuildRecorder` (`groovy-postbuild`): [JENKINS-26918](https://issues.jenkins-ci.org/browse/JENKINS-26918)
@@ -53,7 +51,8 @@ See [this guide](scm-step/README.md#supporting-workflow-from-an-scm-plugin) for
 - [ ] `GitPublisher` (`git`) or a custom step: [JENKINS-28335](https://issues.jenkins-ci.org/browse/JENKINS-28335)
 - [ ] SonarQube Jenkins: [SONARJNKNS-213](http://jira.sonarsource.com/browse/SONARJNKNS-213)
 - [ ] `VSphereBuildStepContainer` (`vsphere-cloud`): [JENKINS-28930](https://issues.jenkins-ci.org/browse/JENKINS-28930)
-- [X] `ScoveragePublisher` (`scoverage`): supported in 1.2.0
+- [X] `ScoveragePublisher` (`scoverage`): supported as of 1.2.0
+- [ ] `XShellBuilder` (`xshell`): [JENKINS-30372](https://issues.jenkins-ci.org/browse/JENKINS-30372)
 
 ## Build wrappers
 
@@ -63,51 +62,57 @@ See [this guide](scm-step/README.md#supporting-workflow-from-an-scm-plugin) for
 - [ ] `DashboardBuilder` (`environment-dashboard`): [issue 20](https://github.com/vipinsthename/environment-dashboard/issues/20)
 - [X] `TimestamperBuildWrapper` (`timestamper`): supported as of 1.7
 - [ ] `MaskPasswordsBuildWrapper` (`mask-passwords`): [PR 3](https://github.com/jenkinsci/mask-passwords-plugin/pull/3)
-- [X] `SSHAgentBuildWrapper` (`ssh-agent`): supported as of 1.8
-- [ ] `XvfbBuildWrapper` (`xvfb`): [JENKINS-28928](https://issues.jenkins-ci.org/browse/JENKINS-28928)
-- [ ] `LockWrapper` (`locks-and-latches`): [JENKINS-29461](https://issues.jenkins-ci.org/browse/JENKINS-29461)
+- [X] `XvfbBuildWrapper` (`xvfb`): supported as of 1.1.0-beta-1
+- [X] `GCloudBuildWrapper` (`gcloud-sdk`): scheduled to be supported as of 0.0.2
+- [X] `NpmPackagesBuildWrapper` (`nodejs`): scheduled to be supported as of 0.3
+- [ ] `AnsiColorBuildWrapper` (`ansicolor`): https://github.com/dblock/jenkins-ansicolor-plugin/pull/54
 
 ## Triggers
 
-- [ ] `gerrit-trigger`: [JENKINS-26010](https://issues.jenkins-ci.org/browse/JENKINS-26010)
+- [X] `gerrit-trigger`: supported as of 2.15.0
 - [ ] `ghprb`: [JENKINS-26591](https://issues.jenkins-ci.org/browse/JENKINS-26591)
-- [ ] `github`: [JENKINS-27136](https://issues.jenkins-ci.org/browse/JENKINS-27136)
+- [X] `github`: scheduled to be supported as of 1.14
 - [ ] `xtrigger-plugin`: [JENKINS-27301](https://issues.jenkins-ci.org/browse/JENKINS-27301)
 - [ ] `deployment-notification`: [JENKINS-28632](https://issues.jenkins-ci.org/browse/JENKINS-28632)
-- [ ] `gitlab-plugin`: [issue 89](https://github.com/DABSquared/gitlab-plugin/issues/89)
+- [X] `gitlab-plugin`: supported as of 1.1.26
 - [X] `bitbucket`: supported as of 1.1.2
 
 ## Clouds
 
 - [ ] `elasticbox`: [JENKINS-25978](https://issues.jenkins-ci.org/browse/JENKINS-25978) (could also include build wrapper integration)
 - [ ] `mansion-cloud`: [JENKINS-24815](https://issues.jenkins-ci.org/browse/JENKINS-24815)
-- [ ] `mock-slave` (for prototyping): [JENKINS-25090](https://issues.jenkins-ci.org/browse/JENKINS-25090)
+- [X] `mock-slave` (for prototyping): supported as of 1.7
 - [X] `docker`: supported as of 0.8
 - [X] `nectar-vmware` (CloudBees Jenkins Enterprise): supported as of 4.3.2
-- [ ] `operations-center-cloud` (CloudBees Jenkins Enterprise/Operations Center): RM-2642
+- [ ] `operations-center-cloud` (CloudBees Jenkins Enterprise/Operations Center): CJP-2951
 - [X] `ec2`: known to work as is
 
 ## Miscellaneous
 
-- [X] `rebuild`: [JENKINS-26024](https://issues.jenkins-ci.org/browse/JENKINS-26024)
-- [ ] `parameterized-trigger` (to support a workflow as downstream): [JENKINS-26050](https://issues.jenkins-ci.org/browse/JENKINS-26050)
-- [X] `build-token-root`: [JENKINS-26693](https://issues.jenkins-ci.org/browse/JENKINS-26693)
-- [X] `credentials-binding`: `withCredentials` step as of 1.3
+- [X] `rebuild`: supported as of 1.24
+- [X] `parameterized-trigger` (to support a workflow as downstream): supported as of 2.28
+- [X] `build-token-root`: supported as of 1.2
 - [ ] `build-failure-analyzer`: [JENKINS-27123](https://issues.jenkins-ci.org/browse/JENKINS-27123)
 - [ ] `shelve-project`: [JENKINS-26432](https://issues.jenkins-ci.org/browse/JENKINS-26432)
-- [X] `job-dsl`: implemented in 1.29
+- [X] `job-dsl`: Workflow creation supported as of 1.29
 - [X] `zentimestamp`: basic compatibility in 4.2
 - [ ] `claim`: [JENKINS-27206](https://issues.jenkins-ci.org/browse/JENKINS-27206)
 - [ ] `ListSubversionTagsParameterValue` (`subversion`): [JENKINS-27718](https://issues.jenkins-ci.org/browse/JENKINS-27718)
-- [X] `authorize-project`: scheduled for 1.0.4
+- [X] `authorize-project`: supported as of 1.1.0
+- [ ] `lockable-resources` : [JENKINS-30269](https://issues.jenkins-ci.org/browse/JENKINS-30269)
+- [X] `customize-build-now`: supported as of 1.1
 
 ## Custom steps
 
 For cases when a first-class Workflow step (rather than an adaptation of functionality applicable to freestyle projects) makes sense.
 
-- [X] `parallel-test-executor`: supported with `splitTests` step since 1.6
+- [X] `docker-workflow`: DSL based on `docker` global variable
+- [X] `credentials-binding`: `withCredentials` step as of 1.3
+- [X] `ssh-agent`: `sshagent` step as of 1.8
+- [X] `parallel-test-executor`: `splitTests` step since 1.6
 - [ ] `gerrit-trigger`: [JENKINS-26102](https://issues.jenkins-ci.org/browse/JENKINS-26102), [JENKINS-26103](https://issues.jenkins-ci.org/browse/JENKINS-26103)
-- [X] `mailer`: [JENKINS-26104](https://issues.jenkins-ci.org/browse/JENKINS-26104) in Workflow 1.2
+- [X] `mailer`: `mail` step in Workflow 1.2
+- [ ] `artifactory`: [JENKINS-30121](https://issues.jenkins-ci.org/browse/JENKINS-30121)
 
 # Plugin Developer Guide
 
@@ -149,6 +154,71 @@ This allows most parameters to be left at their default values in a workflow scr
 For Java-level compatibility, leave any previous constructors in place, but mark them `@Deprecated`.
 Also remove `@DataBoundConstructor` from them (there can be only one).
 
+##### Handling default values
+
+To ensure _Snippet Generator_ enumerates only those options the user has actually customized from their form defaults, ensure that Jelly `default` attributes match the property defaults as seen from the getter.
+For a cleaner XStream serial form in freestyle projects, it is best for the default value to also be represented as a null in the Java field.
+So for example if you want a textual property which can sensibly default to blank, your configuration form would look like
+
+```xml
+<f:entry field="stuff" title="${%Stuff}">
+    <f:textbox/>
+</f:entry>
+```
+
+and your `Describable` should use
+
+```java
+private @CheckForNull String stuff;
+public @CheckForNull String getStuff() {
+    return stuff;
+}
+@DataBoundSetter public void setStuff(@CheckForNull String stuff) {
+    this.stuff = Util.fixNull(stuff);
+}
+```
+
+If you want a nonblank default, it is a little more complicated.
+If you do not care about XStream hygiene, for example because the `Describable` is a Workflow `Step` (or is only being used as part of one):
+
+```xml
+<f:entry field="stuff" title="${%Stuff}">
+    <f:textbox default="${descriptor.defaultStuff}"/>
+</f:entry>
+```
+
+```java
+private @Nonnull String stuff = DescriptorImpl.defaultStuff;
+public @Nonnull String getStuff() {
+    return stuff;
+}
+@DataBoundSetter public void setStuff(@Nonnull String stuff) {
+    this.stuff = stuff;
+}
+@Extension public static class DescriptorImpl extends Descriptor<Whatever> {
+    public static final String defaultStuff = "junk";
+    // …
+}
+```
+
+(The `Descriptor` is the most convenient place to put a constant for use from a Jelly view: `descriptor` is always defined even if `instance` is null, and Jelly/JEXL allows a `static` field to be loaded using instance-field notation.
+From a Groovy view you could use any syntax supported by Java to refer to a constant, but Jelly in Jenkins is weaker: `getStatic` will not work on classes defined in plugins.)
+
+To make sure the field is omitted from the XStream form when unmodified, you can use the same `Descriptor` and configuration form but null out the default:
+
+```java
+private @CheckForNull String stuff;
+public @Nonnull String getStuff() {
+    return stuff == null ? DescriptorImpl.defaultStuff : stuff;
+}
+@DataBoundSetter public void setStuff(@Nonnull String stuff) {
+    this.stuff = stuff.equals(DescriptorImpl.defaultStuff) ? null : stuff;
+}
+```
+
+None of these considerations apply to mandatory parameters with no default, which should be requested in the `@DataBoundConstructor` and have a simple getter.
+(You could still have a `default` in the configuration form as a hint to new users, as a complement to a full description in `help-stuff.html`, but the value chosen will always be saved.)
+
 ### SCMs
 
 See the [user documentation](scm-step/README.md) for background. The `checkout` metastep uses an `SCM`.
@@ -205,11 +275,43 @@ To add support for use of a `Builder` or `Publisher` from a workflow, depend on
 Then implement `SimpleBuildStep`, following the guidelines in [its Javadoc](http://javadoc.jenkins-ci.org/jenkins/tasks/SimpleBuildStep.html).
 Also prefer `@DataBoundSetter`s to a sprawling `@DataBoundConstructor` ([tips](#constructor-vs-setters)).
 
+Note that a `SimpleBuildStep` is designed to work also in a freestyle project, and thus assumes that a `FilePath workspace` is available (as well as some associated services, like a `Launcher`).
+That is always true in a freestyle build, but is a potential limitation for use from a Workflow build.
+For example, you might legitimately want to take some action outside the context of any workspace:
+
+```groovy
+node('win64') {
+  bat 'make all'
+  archive 'myapp.exe'
+}
+input 'Ready to tell the world?' // could pause indefinitely, do not tie up a slave
+step([$class: 'FunkyNotificationBuilder', artifact: 'myapp.exe']) // ← FAILS!
+```
+
+Even if `FunkyNotificationBuilder` implements `SimpleBuildStep`, the above will fail, because the `workspace` required by `SimpleBuildStep.perform` is missing.
+You could grab an arbitrary workspace just to run the builder:
+
+```groovy
+node('win64') {
+  bat 'make all'
+  archive 'myapp.exe'
+}
+input 'Ready to tell the world?'
+node {
+  step([$class: 'FunkyNotificationBuilder', artifact: 'myapp.exe']) // OK
+}
+```
+
+but if the `workspace` is being ignored anyway (in this case because `FunkyNotificationBuilder` only cares about artifacts that have already been archived), it may be better to just write a custom step (described below).
+
 ### Build wrappers
 
 Here the metastep is `wrap`.
 To add support for a `BuildWrapper`, depend on Jenkins 1.599+ (typically 1.609.1), and implement `SimpleBuildWrapper`, following the guidelines in [its Javadoc](http://javadoc.jenkins-ci.org/jenkins/tasks/SimpleBuildWrapper.html).
 
+Like `SimpleBuildStep`, wrappers written this way always require a workspace.
+If that would be constricting, consider writing a custom step instead.
+
 ## Triggers
 
 Replace `Trigger<AbstractProject>` with `Trigger<X>` where `X` is `Job` or perhaps `ParameterizedJob` or `SCMTriggerItem` and implement `TriggerDescriptor.isApplicable` accordingly.
@@ -220,8 +322,8 @@ Do not necessarily need any special integration, but are encouraged to use `Once
 
 ## Custom steps
 
-Plugins can also implement custom Workflow steps with specialized behavior by adding a dependency on `workflow-step-api`.
-Generally you will extend `AbstractStepImpl`, `AbstractStepDescriptorImpl`, and `AbstractStepExecutionImpl` (or `AbstractSynchronousStepExecution`).
+Plugins can also implement custom Workflow steps with specialized behavior.
+See [here](step-api/README.md) for more.
 
 ## Historical background
 

README.md

@@ -64,13 +64,16 @@ and browse [localhost:8080](http://localhost:8080/).
 
 # Presentations
 
-Jenkins Workflow: What’s Up? (JUC DC) (Jun 2015): [slides](http://www.slideshare.net/jgcloudbees/juc-dc-2015-workflow-whats-up)
+Jenkins Workflow: What’s Up? (JUC West) (Sep 2015): [slides](http://www.slideshare.net/jgcloudbees/juc-west-15-jenkins-workflow-whats-up) and accompanying [demo](https://youtu.be/yaEF3VAjWbk)
+
+Jenkins Office Hour on Workflow for plugin developers (Aug 2015): [video](https://www.youtube.com/watch?v=4zdy7XGx3PA)
 
 Workflow Meetup London (Mar 2015): [slides](http://www.slideshare.net/jgcloudbees/london-workflow-summit-kkjg)
 
+Jenkins Workflow Screencast (Jan 2015): [video](https://www.youtube.com/watch?v=Welwf1wTU-w)
+
 Webinar _Orchestrating the Continuous Delivery Process in Jenkins with Workflow_ (Dec 2014): [video](http://youtu.be/ZqfiW8eVcuQ)
 
-JUC San Francisco (Oct 2014): [video](https://www.youtube.com/watch?v=rswdksvwvJY)
 
 # Detailed guides