Merge pull request #449 from tulios/document-pre-release-versions

Document pre-release versions

README.md

@@ -22,6 +22,9 @@ KafkaJS is battle-tested and ready for production.
 - Support for AWS IAM authentication
 - Admin client
 
+_Read something on the website that didn't work with the latest stable version?_  
+[Check the pre-release versions](https://kafka.js.org/docs/pre-releases) - the website is updated on every merge to master.
+
 ## <a name="getting-started"></a> Getting Started
 
 ```sh

docs/PreReleases.md

@@ -0,0 +1,42 @@
+---
+id: pre-releases
+title: Pre-releases
+---
+
+Stable KafkaJS versions can take a while to be released. Release candidates are usually deployed in production for at least a week before general availability. We do this to make sure that all releases are stable, and we trust our services to verify most production use-cases. Although this process guarantees some quality, it can be too slow or unpredictable. Some versions go out faster than others, and it can be frustrating if you need a particular feature that has not been included in a stable release yet.
+
+In the past, the recommendation was to point your `package.json` to the commit hash with the change you needed, but this approach has some complications. Companies usually proxy NPM and have some expectations on how dependencies are handled, your CI or deploy server might not have access to GitHub, among other issues. This process was an extra barrier for users to try out the new code, helping us test and perfect the next release.
+
+To alleviate this issue, we are now automatically creating pre-release versions on every merge to master containing changes to `src/`, `index.js` or, `package.json`.
+
+## Using pre-release versions
+
+To use the latest pre-release version, run:
+
+```sh
+# Yarn
+yarn add kafkajs@beta
+
+# Npm
+npm install --save kafkajs@beta
+```
+
+## Versioning
+
+If the current stable version is `1.9.3` and we merge a new PR to master, a pre-release will be generated with the version `1.10.0-beta.0`. It will always use the next minor version. If a second PR is merged, the next version would be `1.10.0-beta.1`, since we are generating a new pre-release for the same stable version, it will continue incrementing the last number. If we release a patch, it will continue to make beta releases using the next minor, so stable on `1.9.4` will continue to generate `1.10.0-beta.N`.
+
+## Pre-release package changes
+
+In order to know what a pre-release version contains, we have added a new attribute to the `package.json` of pre-release versions, `kafkajs`:
+
+```javascript
+{
+  // package.json
+  "kafkajs": {
+    "sha": "43e325e18133b8d6c1c80f8e95ef8610c44ec631",
+    "compare": "https://github.com/tulios/kafkajs/compare/v1.9.3...43e325e18133b8d6c1c80f8e95ef8610c44ec631"
+  }
+}
+```
+
+This contains the git SHA used to generate the version and the GitHub URL to quickly compare the differences with the stable version at the time of the pre-release creation.

scripts/pipeline/generateBetaReleaseVersion.js

@@ -1,44 +1,7 @@
 #!/usr/bin/env node
 
-const https = require('https')
 const { coerce, prerelease, parse } = require('semver')
-
-const getCurrentVersion = async () =>
-  new Promise((resolve, reject) => {
-    const request = https.request(
-      {
-        protocol: 'https:',
-        host: 'registry.npmjs.org',
-        path: `/kafkajs`,
-        headers: {
-          'User-Agent': 'KafkaJS Azure Pipeline',
-        },
-      },
-      res => {
-        let rawData = ''
-
-        res.setEncoding('utf8')
-        res.on('data', chunk => (rawData += chunk))
-        res.on('end', () => {
-          try {
-            if (res.statusCode !== 200) {
-              return reject(
-                new Error(`Error getting current NPM version: ${res.statusCode} - ${rawData}`)
-              )
-            }
-
-            const data = JSON.parse(rawData)
-            resolve(data['dist-tags'])
-          } catch (e) {
-            reject(e)
-          }
-        })
-      }
-    )
-
-    request.on('error', reject)
-    request.end()
-  })
+const getCurrentVersion = require('./getCurrentNPMVersion')
 
 const sameStableVersion = (stable, beta) => coerce(stable).version === coerce(beta).version
 

scripts/pipeline/getCurrentNPMVersion.js

@@ -0,0 +1,40 @@
+const https = require('https')
+
+const getCurrentVersion = async () =>
+  new Promise((resolve, reject) => {
+    const request = https.request(
+      {
+        protocol: 'https:',
+        host: 'registry.npmjs.org',
+        path: `/kafkajs`,
+        headers: {
+          'User-Agent': 'KafkaJS Azure Pipeline',
+        },
+      },
+      res => {
+        let rawData = ''
+
+        res.setEncoding('utf8')
+        res.on('data', chunk => (rawData += chunk))
+        res.on('end', () => {
+          try {
+            if (res.statusCode !== 200) {
+              return reject(
+                new Error(`Error getting current NPM version: ${res.statusCode} - ${rawData}`)
+              )
+            }
+
+            const data = JSON.parse(rawData)
+            resolve(data['dist-tags'])
+          } catch (e) {
+            reject(e)
+          }
+        })
+      }
+    )
+
+    request.on('error', reject)
+    request.end()
+  })
+
+module.exports = getCurrentVersion

scripts/pipeline/updatePackageJsonForPreRelease.js

@@ -3,6 +3,7 @@
 const path = require('path')
 const fs = require('fs')
 const execa = require('execa')
+const getCurrentVersion = require('./getCurrentNPMVersion')
 
 console.log('Env:')
 for (const env of Object.keys(process.env)) {
@@ -26,13 +27,15 @@ const commitSha = execa
   .stdout.toString('utf-8')
   .trim()
 
-packageJson.version = PRE_RELEASE_VERSION
-packageJson.kafkajs = {
-  sha: commitSha,
-  compare: `https://github.com/tulios/kafkajs/compare/master...${commitSha}`,
-}
-
-console.log(packageJson.kafkajs)
-const filePath = path.resolve(__dirname, '../../package.json')
-fs.writeFileSync(filePath, JSON.stringify(packageJson, null, 2))
-console.log(`Package.json updated with pre-release version ${PRE_RELEASE_VERSION}`)
+getCurrentVersion().then(({ latest }) => {
+  packageJson.version = PRE_RELEASE_VERSION
+  packageJson.kafkajs = {
+    sha: commitSha,
+    compare: `https://github.com/tulios/kafkajs/compare/v${latest}...${commitSha}`,
+  }
+
+  console.log(packageJson.kafkajs)
+  const filePath = path.resolve(__dirname, '../../package.json')
+  fs.writeFileSync(filePath, JSON.stringify(packageJson, null, 2))
+  console.log(`Package.json updated with pre-release version ${PRE_RELEASE_VERSION}`)
+})

website/core/Footer.js

@@ -57,6 +57,9 @@ class Footer extends React.Component {
             >
               Star
             </a>
+            <a href="https://badge.fury.io/js/kafkajs">
+              <img src="https://badge.fury.io/js/kafkajs.svg" alt="npm version" height="18" />
+            </a>
           </div>
         </section>
       </footer>

website/i18n/en.json

@@ -43,6 +43,9 @@
         "title": "A Brief Intro to Kafka",
         "sidebar_label": "Intro to Kafka"
       },
+      "pre-releases": {
+        "title": "Pre-releases"
+      },
       "producer-example": {
         "title": "Producer"
       },

website/package.json

@@ -9,6 +9,6 @@
     "rename-version": "docusaurus-rename-version"
   },
   "devDependencies": {
-    "docusaurus": "^1.7.1"
+    "docusaurus": "^1.12.0"
   }
 }

website/sidebars.json

@@ -11,7 +11,8 @@
       "instrumentation-events",
       "custom-logger",
       "retry-detailed",
-      "faq"
+      "faq",
+      "pre-releases"
     ],
     "Examples": [
       "running-kafka-in-development",