Development & Test Environments

Table of Contents

• Startup
• Modifying JavaScript
  • Inline JavaScript/JSON comments
  • External JavaScript
• How To Pass the CI Tests
  • Check commit messages
  • Check the Core Functionality
  • Check the SASS Code Style
• Maintaining the project
  • Managing the hotfix branches

---

Startup

Install VS Code, Dev Containers, and Docker.

Next, fork this repository and then open VS Code to clone your repo in container volume. Wait a few minutes for Docker to create the container, and once everything is ready, you can start the Jekyll server in the VS Code terminal:

./tools/run.sh

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.sh

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.

Check commit messages

Once you've run command npm install in the root directory of the repository, commit-lint is activated. Every commit you created will be checked to ensure it meets the requirements of Conventional Commits.

Important

If you use a Node version manager and want to use Git hooks through Git GUIs, you might encounter a "command not found" error when committing your changes.

For more information on the cause and solution, refer to the Husky docs: "Node Version Managers and GUIs".

Check the Core Functionality

bash ./tools/test.sh

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).