Development & Test Environments

Table of Contents

• Run Jekyll Server
  • Compiling CSS/JS files
  • Setup Jekyll
• Modifying JavaScript
  • Inline JavaScript/JSON comments
  • External JavaScript
• How To Pass the CI Tests
  • Verify the Commits
  • Check the Core Functionality
  • Check the SASS Code Style
• Maintaining the project
  • Managing the hotfix branches

---

Run Jekyll Server

Compiling CSS/JS files

To run the project, you need to compile JS for it. So setup Node.js first, then run the following command.

npm i && npm run build

The compiled output will be in assets/js/dist/ and _sass/dist/.

Setup Jekyll

Follow the instructions in the Jekyll Docs to complete the installation of the basic environment. Git also needs to be installed.

Before the first run, go to the root directory and install the dependencies:

bundle

And then start the local server.

./tools/run

Modifying JavaScript

If your changes involve JavaScript, please read the following sections.

Inline JavaScript/JSON comments

For inline JS (code between <script> and </script>) or JS / JSON file containing Front Matter, if you want to add comments to it, please use {%- comment -%} and {%- endcomment -%} instead of two slashes // (e.g. {%- comment -%} code comment message {%- endcomment -%} ). This is because in a production environment, jekyll-compress-html compresses HTML files, but does not recognize // correctly and thus breaking the HTML structure as a result.

External JavaScript

If you changed the files in the _javascript/ directory, then you need to rebuild the JS. During the development, real-time debugging can be performed through the following commands:

Firstly, start a Jekyll server:

./tools/run

And then open a new terminal sessioin and run:

npm run watch:js

When you are finished developing, press ctrl + C to end the npm process above, and then run the npm run build:js command. The new compressed JS files will be exported to assets/js/dist/.

How To Pass the CI Tests

This project has CI turned on. In order for your pull request to pass the test, please read the following.

Verify the Commits

Before you create a git commit, please complete the following setup.

If you run npm i once, commitlint and husky is already installed.

And then enable husky for the repo:

husky install

Some Git GUI (such as Sourcetree, Gitnuro, etc.) may not be able to search your system's node.js execution path correctly, and may break with a message: npx: command not found!. In this case, you need to set up a configuration file ~/.huskyrc:

If you have a single version of node.js, execute the following command in the terminal.

echo "export PATH=\"$(dirname $(which node)):\$PATH\"" > ~/.huskyrc

If you installed node.js via nvm, create the file ~/.huskyrc and fill in the following:

# This loads nvm.sh, sets the correct PATH before running hook, and ensures the project version of Node
export NVM_DIR="$HOME/.nvm"

[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

# If you have an .nvmrc file, we use the relevant node version
if [ -f ".nvmrc" ]; then
  nvm use
fi

See also: https://typicode.github.io/husky/troubleshooting.html#command-not-found

Check the Core Functionality

bash ./tools/test

Check the SASS Code Style

npm test

Maintaining the project

Managing the hotfix branches

The hotfix branch naming format is hotfix/<MAJOR>.<MINOR>.<PATCH>, e.g. hotfix/3.2.1.

1. Create a new hotfix branch from the production branch (on GitHub).

2. Commit the patch to the hotfix branch by:

   1. Branch from hotfix and then commit patches to the new patch branch.
   2. Create a PR for the patch branch on GitHub, then squash merge into into the hotfix branch.

3. When hot-fixes is done, create a PR for the hotfix branch and merge it into the production branch (using the --no-ff option).