Development & Test Environments

Table of Contents

• Run Jekyll Server
  • Compiling 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 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 (*.min.js) will be in assets/js/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 /* */ instead of two slashes //. Because in a production environment, jekyll-compress-html will compress the HTML file, but it does not handle // correctly and therefore breaks the HTML structure.

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

When you are finished developing, press ctrl + C to end the npm process above, and then run the npm run build 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 name of a hotfix branch 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:
   1. Create a patch branch on the hotfix branch and commit the changes.
   2. Create a PR for the patch branch on GitHub and merge it into the hotfix branch.
3. After all patches have been committed to the hotfix branch via Pull Request, the maintainer can checkout hotfix branch on the local machine and run tools/release to release it.