Blog post on Declarative beta 2 (0.8.1 release) #526

Merged
merged 6 commits into from Jan 12, 2017

Projects

None yet

5 participants

@abayer
Contributor
abayer commented Jan 10, 2017 edited

cc @HRMPW @michaelneale @i386 @rtyler

fwiw, I put the 12th as the date 'cos I expected a two day delay to going live, but if @rtyler wants to take it live sooner, that's fine by me. =)

+---
+
+This week, we released the second beta of the new
+link:https://wiki.jenkins-ci.org/display/JENKINS/Pipeline+Model+Definition+Plugin[Declarative Pipeline syntax],
@rtyler
rtyler Jan 10, 2017 Member

I have been preferring links to plugins.jenkins.io whenever we reference plugins, mind updating?

+link:/blog/2016/12/19/declarative-pipeline-beta/[in the blog post introducing the first beta]
+from December, but we wanted to update you all on the syntax changes in the
+second beta. These syntax changes are the last compatibility-breaking changes to
+the syntax for the 1.0 release planned for February, so you can safely start
@rtyler
rtyler Jan 10, 2017 Member

s/for the/before the/

+and `dockerfile` now look like the following:
+
+[pipeline]
+----
@rtyler
rtyler Jan 10, 2017 Member

This block should be annotated with // Declarative // at the top, see this doc

+
+// If you're just specifying a Docker image, you can use this simple syntax.
+agent {
+ docker "ubuntu:lts"
@rtyler
rtyler Jan 10, 2017 Member

I reviewed a Pipeline like this on an internal document too, same copy-pasta issue. There is no ubuntu:lts image

@HRMPW
HRMPW Jan 10, 2017 Contributor

That was me and I copied it from either @abayer or @i386 . :)

+// When you are specifying a label or other arguments, docker looks like this:
+agent {
+ docker {
+ image "ubuntu:lts"
@rtyler
rtyler Jan 10, 2017 Member

same wrt ubuntu:lts

+ args "-v /tmp:/tmp -p 8000:8000"
+ }
+}
+----
@rtyler
rtyler Jan 10, 2017 Member

These various agent syntaxes all in one [pipeline] block I think is confusing. Ideally (IMO) they should be separated into their own blocks with the comment above each agent declaration as the paragraph of text outside the block

@HRMPW
HRMPW Jan 10, 2017 Contributor

👍

@michaelneale
michaelneale Jan 10, 2017 Contributor

yes or people will try to combine them and be confused.

+ return "foo" == "bar"
+ }
+}
+----
@rtyler
rtyler Jan 10, 2017 Member

same multi-pipeline-block critique as before

+
+=== Properties, options and wrappers
+We've renamed the old `properties` section to `options`. The `options` section
+is now where you'll put job properties, like `buildDiscarder`, Declarative-specific
@rtyler
rtyler Jan 10, 2017 Member

"The options section is now where you'll put job properties" is a confusing statement, and uses the term "job" which I have been trying to purge from al references related to Pipeline.

Suggest: "The options section is now where you will put Pipeline options such as foobar, etc"

@michaelneale
Contributor

really good - I think Tylers feedback is good, but I like it!

@abayer
Contributor
abayer commented Jan 10, 2017

Changes made. =)

@rtyler
rtyler approved these changes Jan 11, 2017 edited View changes

This looks fine for me, @bitwiseman will you merge this Thursday morning when you start workin'?

+ dockerfile true
+}
+
+// When you're building an image from a differnt file, or have a label or other
@rtyler
rtyler Jan 11, 2017 Member

s/diffrnt/different/

@abayer
abayer Jan 11, 2017 Contributor

dangit, I thought I'd fixed that.

@abayer
abayer Jan 11, 2017 Contributor

Ah, I did change it but forgot to commit that chunk. Sigh.

@bitwiseman
Contributor

@rtyler - Thursday, got it.

@bitwiseman

@abayer - Sorry, late review, been out sick.

+
+== Syntax Changes
+
+=== Agent
@bitwiseman
bitwiseman Jan 11, 2017 Contributor

Changed "agent" to block structure

+}
+----
+
+=== `when` - conditional stage execution
@bitwiseman
bitwiseman Jan 11, 2017 Contributor

Improved "when" conditions

+We introduced the `when` section a couple releases ago, but have made some
+changes to its syntax here in 0.8.1. We wanted to add some simpler ways to
+specify common conditions, and that required we re-work the syntax accordingly.
+Here's what `when` looks like now:
@bitwiseman
bitwiseman Jan 11, 2017 Contributor

s/Here's what when looks like now://

+changes to its syntax here in 0.8.1. We wanted to add some simpler ways to
+specify common conditions, and that required we re-work the syntax accordingly.
+Here's what `when` looks like now:
+
@bitwiseman
bitwiseman Jan 11, 2017 Contributor

You might put each of these as ==== headings.

==== Branch

+}
+----
+
+Another built-in condition is the environment condition, which checks to see
@bitwiseman
bitwiseman Jan 11, 2017 Contributor

==== Environment

+}
+----
+
+Lastly, there's the expression condition, which resolves an arbitrary
@bitwiseman
bitwiseman Jan 11, 2017 Contributor

==== Expression

+}
+----
+
+=== Properties, options and wrappers
@bitwiseman
bitwiseman Jan 11, 2017 Contributor

Renamed "properties" to "options"

+----
+
+=== Properties, options and wrappers
+We've renamed the old `properties` section to `options`. The `options` section
@bitwiseman
bitwiseman Jan 11, 2017 Contributor

s/old//

Also, for other sections you explained the reason for the change. You should do so here as well.

+We've renamed the old `properties` section to `options`. The `options` section
+is now where you'll put general Pipeline options like `buildDiscarder`,
+Declarative-specific options like `skipDefaultCheckout`, and block-scoped steps
+that should wrap around the execution of the entire build, like `timeout` or
@bitwiseman
bitwiseman Jan 11, 2017 Contributor

s/wrap around/wrap/
or
s/wrap around/span/

+== Heading towards 1.0!
+While we may still add more functionality to the Declarative Pipeline syntax
+before the 1.0 release, we won't be changing any existing syntax until, at the
+earliest, a future 2.0 release. This means that any pipelines you write against
@bitwiseman
bitwiseman Jan 11, 2017 Contributor

@abayer

While we may still add more functionality to the Declarative Pipeline syntax 
before the 1.0 release, we won't be changing any existing syntax until, at the
earliest, a future 2.0 release.

I know you're being honest here, but how about:

While we may still add more functionality to the Declarative Pipeline syntax, 
we won't change any existing syntax for the 1.0 release.
+the 0.8.1 syntax will keep working for the foreseeable future without any
+changes. So if you're already using Declarative Pipelines, make sure to update
+your `Jenkinsfile`s after upgrading to 0.8.1, and if you haven't been using
+Declarative Pipelines yet, install the _Pipeline: Model Definition_ plugin and
@bitwiseman
bitwiseman Jan 11, 2017 Contributor

Make this a link too. I know you have one earlier, but this is the lead out - you're telling them where to got next, give them a link.

@abayer
Contributor
abayer commented Jan 11, 2017

@bitwiseman Done!

@bitwiseman
Contributor

@abayer - Thanks! This will go out in the morning.

@bitwiseman bitwiseman merged commit 0887ea1 into jenkins-infra:master Jan 12, 2017
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment