Skip to content

Commit

Permalink
DOC Update build tooling docs
Browse files Browse the repository at this point in the history
  • Loading branch information
GuySartorelli committed Oct 6, 2023
1 parent 294d9a2 commit 9aedf18
Showing 1 changed file with 32 additions and 32 deletions.
64 changes: 32 additions & 32 deletions en/05_Contributing/02_Build_Tooling.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ JavaScript or SCSS files, you'll need Node installed on your dev environment.

As of SilverStripe 4.4, our build tooling supports the v10.x (LTS as of Sept 2019) version
of NodeJS. SilverStripe 4.0 - 4.3 used Node v6.x.

If you already have a newer version of Node.js installed, check out the
[Node Version Manager](https://github.com/creationix/nvm) to run multiple versions
in your environment.
Expand All @@ -35,22 +35,22 @@ You'll need to install yarn after Node.js is installed.
See [yarn installation docs](https://yarnpkg.com/en/docs/install).
We recommend using `npm` which comes with Node.js to install it globally.

```
```bash
npm install -g yarn
```

Once you've installed Node.js and yarn, run the following command once in each core module folders:

```
yarn
```bash
yarn install
```

## The Basics: ES6, Webpack and Babel

[ECMAScript 6](https://github.com/lukehoban/es6features) (ES6)
is the newest version of the ECMAScript standard. It has some great new
features, but the browser support is still patchy, so we use Babel to transform ES6 source
files back to ES5 files for distribution.
files back to ES5 files for distribution.

[Webpack](https://webpack.github.io) contains the build tooling to
"transpile" various syntax patterns (ES6, SCSS) into a format the browser can understand,
Expand All @@ -64,80 +64,80 @@ Babel to transform our JavaScript in two ways.

## Build Commands

The `script` property of a `package.json` file can be used to define command line
The `script` property of a `package.json` file can be used to define command line
[scripts](https://docs.npmjs.com/misc/scripts).
A nice thing about running commands from an npm script is binaries located in
`node_modules/.bin/` are temporally added to your `$PATH`. This means we can use dependencies
defined in `package.json` for things like compiling JavaScript and SCSS, and not require
developers to install these tools globally. This means builds are much more consistent
across development environments.
across development environments.

To run an npm script, open up your terminal, change to the directory where `package.json`
is located, and run `$ yarn run <SCRIPT_NAME>`. Where `<SCRIPT_NAME>` is the name of the
is located, and run `yarn run <SCRIPT_NAME>`. Where `<SCRIPT_NAME>` is the name of the
script you wish to run.

### build

```
$ yarn run build
```bash
yarn run build
```

Runs [Webpack](https://webpack.github.io/) to builds the core JavaScript files.
Runs [Webpack](https://webpack.github.io/) to builds the core JavaScript files.
You will need to run this script whenever you make changes to a JavaScript file.

Run this script with `-- --watch` to automatically rebuild on file changes.
The first `--` separator is required to separate arguments from NPM's own ones.

```
$ yarn run build -- --watch
```bash
yarn run build -- --watch
```

*For development only*:
Run this to keep webpack automatically rebuilding your file changes, this will also include *.map files
for easier debugging. It is important to note that this should not be used for pushing up changes,
and you should run `yarn run build` after you're done.

```
$ yarn run watch
```bash
yarn run watch
```

### css

```
$ yarn run css
```bash
yarn run css
```

Compiles all of the `.scss` files into minified `.css` files.

Run this script with `-- --watch` to automatically rebuild on file changes.
The first `--` separator is required to separate arguments from NPM's own ones.

```
$ yarn run css -- --watch
```bash
yarn run css -- --watch
```

### lint

```
$ yarn run lint
```bash
yarn run lint
```

Run linters (`eslint` and `sass-lint`) linters to enforce
our [JavaScript](/contributing/javascript_coding_conventions) and
our [JavaScript](/contributing/javascript_coding_conventions) and
[CSS](/contributing/css_coding_conventions) coding conventions.

### test

```
$ yarn run test
```bash
yarn run test
```

Runs the JavaScript unit tests.

### coverage

```
$ yarn run coverage
```bash
yarn run coverage
```

Generates a coverage report for the JavaScript unit tests. The report is generated
Expand All @@ -159,7 +159,7 @@ the `framework/admin/client/src/bundles/` files for `require('expose?...')` stat

A shortened `webpack.config.js` in your own module could look as follows:

```
```js
module.exports = {
entry: {
'bundle': `mymodule/client/src/js/bundle.js`,
Expand All @@ -178,30 +178,30 @@ module.exports = {

Now you can use the following statements in your ES6 code without double includes:

```
```js
import react from 'react';
import jQuery from 'jQuery';
import FormBuilder from 'components/FormBuilder/FormBuilder';
```

## Publishing frontend packages to NPM

We're progressing to include NPM modules in our development process. We currently have a limited number of
We're progressing to include NPM modules in our development process. We currently have a limited number of
[JavaScript only projects published to NPM under the `@silverstripe` organisation](https://www.npmjs.com/search?q=%40silverstripe).

When a pull request is merged against one of those JS-only projects, a new release has to be published to NPM. Regular
Silverstripe CMS modules using these packages have to upgrade their JS dependencies to get the new release.

These are the steps involved to publish a new version to NPM for a package, similar steps apply for creating a new
package under the `@silverstripe` organisation:

1) Make your changes, pull from upstream if applicable
2) Change to the relevant container folder with the `package.json` file
3) Run `npm login` and make sure you’re part of the `@silverstripe` organisation
4) Make sure the `name` property of the `package.json` file matches to the right module name with organisation name prefix, e.g. `"name": "@silverstripe/webpack-config"`
5) Update the `version` property of the `package.json` file with a new version number, following semantic versioning where possible
6) Run `npm version` and validate that the version matches what you expect
7) Run `npm publish`
_IMPORTANT NOTE_: You cannot publish the same or lower version number. Only members of the Silverstripe CMS core team

*IMPORTANT NOTE*: You cannot publish the same or lower version number. Only members of the Silverstripe CMS core team
can publish a release to NPM.

0 comments on commit 9aedf18

Please sign in to comment.