Merge pull request #1794 from intuit/jenkins-docs

improve jenkins/next docs
intuit · Feb 11, 2021 · 8202af4 · 8202af4
2 parents 3c6035e + 1a2db89
commit 8202af4
Show file tree

Hide file tree

Showing 4 changed files with 59 additions and 20 deletions.
diff --git a/docs/pages/docs/build-platforms/jenkins.mdx b/docs/pages/docs/build-platforms/jenkins.mdx
@@ -5,14 +5,14 @@ title: Jenkins 2
 The following config declares the `release` action that run on all branches. The job will either release:
 
 - a new `latest` version from `baseBranch`
-- a `canary` build from a pull request (only on the main fork and if your package manager plugin implements them)
+- a `canary` build from a pull request (only if your package manager plugin supports it)
 
 **`Jenkinsfile`**
 
-> :warning:You must use some sort of step that implements `skip ci` functionality. Otherwise you will get stuck in a release loop!
+> :warning: You must use some sort of step that implements `skip ci` functionality.
+> Otherwise you will get stuck in a release loop!
 
 ```groovy
-
 pipeline {
   environment {
     NPM_TOKEN = credentials('NPM_TOKEN')
@@ -56,23 +56,11 @@ pipeline {
     stage('Publish') {
       parallel {
         stage('Canary') {
-          when {
-            allOf {
-              changeRequest();
-              expression { env.CHANGE_BRANCH != 'next' }
-            }
-          }
+          when { changeRequest(); }
           steps {
             sh "auto shipit"
           }
         }
-        stage('Next') {
-          when { branch 'next' }
-          steps {
-            sh 'git checkout -b next'
-            sh "auto shipit"
-          }
-        }
         stage('Latest') {
           when { branch 'main' }
           steps {
@@ -96,6 +84,56 @@ pipeline {
 }
 ```
 
+## Configuring Prereleases
+
+For `auto`'s prerelease to work you need to makes sure that you jenkins instance is configured correctly.
+
+1. Go to `General > Projects > GitHub Organization` and add a `Behaviors` that enables branch builds.
+
+   ![A screenshot of the jenkins configuration](/jenkins-next-branches.png)
+
+2. Add this to the top of your `Jenkinsfile`. 
+
+   ```groovy
+   // Exit the branch build if not on "baseBranch" or a prerelease, but still do PR builds
+   if (env.BRANCH_NAME != "master" && env.BRANCH_NAME != "next" && !env.BRANCH_NAME.startsWith('PR-')) {
+     echo ("Aborting build. Only the master/next branch and PR builds run.")
+     currentBuild.result = 'SUCCESS'
+     return
+    }
+   ```
+
+   If your successful you will see two separate builds in your PRs: `pr-merge` and `branch`.
+
+3. Modify your `canary` stage to not build the prerelease branch
+
+   ```groovy
+   stage('Canary') {
+     when {
+       allOf {
+         changeRequest();
+         expression { env.CHANGE_BRANCH != 'next' }
+       }
+     }
+     steps {
+       sh "auto shipit"
+     }
+   }
+   ```
+4. Add a stage for the prerelease
+
+   ```groovy
+   stage('Next') {
+     when { branch 'next' }
+     steps {
+       sh 'git checkout -b next'
+       sh "auto shipit"
+     }
+   }
+   ```
+
+5. Open a PR from your prerelease branch into your baseBranch and enjoy your prerelease! :tada:
+
 ## Troubleshooting
 
 If you are having problems make sure you have done the following:

diff --git a/docs/public/jenkins-next-branches.png b/docs/public/jenkins-next-branches.png
diff --git a/packages/cli/src/parse-args.ts b/packages/cli/src/parse-args.ts
@@ -584,12 +584,13 @@ export const commands: AutoCommand[] = [
     name: "next",
     group: "Release Commands",
     description: endent`
-      Make a release for your "prerelease" release line. This is ran automatically from "shipit".
+      Make a release for your "prerelease" release line. This is ran automatically by "shipit" in a prerelease branch.
 
       1. Creates a prerelease on package management platform
-      2. Creates a "Pre Release" on GitHub releases page.
+      2. Creates a "Pre Release" on GitHub releases page
+      3. If ran from a PR build in a CI, posts the prerelease's full releases notes and expected version of the prerelease
 
-      Calling the \`next\` command from a prerelease branch will publish a prerelease, otherwise it will publish to the default prerelease branch.
+      Calling the \`next\` command from a prerelease branch will publish a prerelease for just that branch, otherwise it will publish to the default prerelease branch.
     `,
     examples: ["{green $} auto next"],
     options: [

diff --git a/packages/core/src/auto.ts b/packages/core/src/auto.ts
@@ -1335,7 +1335,7 @@ export default class Auto {
     }
 
     if (!options.dryRun) {
-      await this.checkClean()
+      await this.checkClean();
     }
 
     await this.setGitUser();