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, use {%- comment -%} and {%- endcomment -%} for comments instead of two slashes //. For example: {%- comment -%} code comment message {%- endcomment -%}. This is because in a production environment, jekyll-compress-html compresses HTML files but does not recognize // correctly, which can break the HTML structure.

External JavaScript

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

Firstly, start a Jekyll server:

./tools/run.sh

And then open a new terminal session 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 enabled. To ensure your Pull Request passes the tests, please follow these guidelines.

Check commit messages

Once you've run npm install in the root directory of the repository, commit-lint is activated. Every commit you create 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. Branching from hotfix and then committing patches to the new patch branch.
   2. Creating a PR for the patch branch on GitHub, then squash merge it into the hotfix branch.

3. When hotfixes are done, create a PR for the hotfix branch and merge it into the production branch using the --no-ff option.