Commit 53451538 authored by Dan Allen's avatar Dan Allen

Merge branch 'issue-17-min-node-version-adr' into 'master'

resolves #17 add ADR regarding minimum node version

Closes #17

See merge request antora/antora-direct!6
parents 8b9213a1 2e232969
Pipeline #12263488 passed with stages
in 2 minutes and 15 seconds
......@@ -10,7 +10,9 @@
:uri-issue-board: {uri-project}/boards/368796
:uri-issue-labels: {uri-project}/labels
:uri-ci-pipelines: {uri-project}/pipelines
:uri-adr-0001: {uri-project}/blob/master/docs/architecture/content/adr/0001-minimum-node-version.adoc
// External URIs:
:uri-async-func: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function
:uri-git: https://git-scm.com
:uri-git-dl: {uri-git}/downloads
:uri-gulp: https://gulpjs.com
......@@ -183,36 +185,35 @@ To see which version of Node you have installed, open a terminal and type:
If `node --version` doesn't return any information, you don't yet have Node installed.
The minimum required version of Node is *v7.10.1*, as indicated in the [.path]_package.json_ file.
The minimum required version of Node is *8.0.0*, as indicated in [.path]_package.json_, though we recommend using the latest release in the 8.x series.
This is also the recommended version of Node for development.
.Why Node 7?
.Why Node 8?
****
This project leverages the latest and greatest features of ECMAScript, namely ECMAScript 2016 (ES2016, or ES7 for short).
The main feature of ES7 this project depends on is the `await` keyword since it drastically simplifies asynchronous code.
That's why this project requires at least Node v7.10.1.
This project leverages the latest and greatest features of ECMAScript, namely ECMAScript 2017 (ES2017).
The main feature of ES2017 this project depends on is the {uri-async-func}[Async Function] (which introduced the `async` and `await` keywords).
This feature drastically simplifies our asynchronous code.
NOTE: We don't recommend using Node 8 at this time since it's not officially supported by one of the main dependencies of the project, NodeGit.
Nodegit is the git integration library used to fetch files form the content repositories.
Once Node 8 is officially supported by NodeGit, we'll consider bumping the recommended version of Node.
Node 8 is the first long-term support (LTS) release that provides this feature, which is why it's defined as the prerequisite.
You can read more about the decision to set Node 8 as the minimum required version in {uri-adr-0001}[ADR 0001: Minimum Node Version].
****
If you don't yet have Node installed, or the version of Node you have isn't Node 7, we strongly recommend using {uri-nvm}[nvm] (Node Version Manager) to manage your Node installations.
If you don't yet have Node installed, or the version of Node you have isn't Node 8, we strongly recommend using {uri-nvm}[nvm] (Node Version Manager) to manage your Node installations.
Follow the {uri-nvm-install}[nvm installation instructions] to set up nvm on your machine.
TIP: Many CI environments use nvm to install the version of Node used for the build job.
By using nvm, you can closely align your setup with the environment that is used to generate and publish the production site.
Once you've installed nvm, open a new terminal and install Node 7 using:
Once you've installed nvm, open a new terminal and install Node 8 using:
$ nvm install 7
$ nvm install 8
The above command will install the latest version of Node 7.
The above command will install the latest version of Node 8.
If you already have other Node versions installed, you can configure Node 7 as the default for any new terminal.
If you already have other Node versions installed, you can configure Node 8 as the default for any new terminal.
$ nvm alias default 7
$ nvm alias default 8
You can skip this step if you didn't previously have any Node versions installed because `nvm install` automatically adds the default alias to the first version of Node you install.
......
= ADR 0001: Minimum Node Version
:revdate: 2017-09-25
== Status
Proposed
== Context
The current minimum version of Node for Antora is Node 7.
However, being an odd version number, Node 7 is not slated to become a long-term support (LTS) release.
Now that Node 8 is now considered stable and mature, the Node project recommends its use over Node 7.
Libraries such as Yarn are beginning to phase out support for Node 7.
The current LTS release is Node 6.
However, Antora cannot go backwards to Node 6 since Antora relies on several ES2016 (ES7) features first introduced in Node 7, including the await keyword.
The only option is forward.
== Decision
We will bump the minimum version of Node to develop and use Antora from Node 7 to Node 8.
The only factor that was previously holding back this change was for nodegit to support Node 8.
Installing nodegit on Node 8 used to require the installer to build nodegit from source, which took several minutes.
We've confirmed that nodegit installs on Node 8 using Yarn in a few seconds (tested using Node v8.5.0 and Yarn 1.1.0).
Now that nodegit supports Node 8, there is nothing preventing Antora from upgrading.
== Consequences
By making Node 8 the minimum required version of Node, we can be sure Antora will depend on a version of Node that will be supported from October 2017--which aligns perfectly with the initial release of Antora--to December 2019, according to the https://github.com/nodejs/Release[Node LTS schedule].
......@@ -9,7 +9,7 @@
"license": "MPL-2.0",
"main": "lib/index.js",
"engines": {
"node": ">= 7.10.1"
"node": ">= 8.0.0"
},
"devDependencies": {
"array-to-stream": "^1.0.2",
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment