From 7e3dc87c7d30f1b1f9338aaf50c1e647cc28b259 Mon Sep 17 00:00:00 2001 From: yann Date: Wed, 28 May 2025 08:32:13 +0200 Subject: [PATCH] chirpy.wiki --- .gitignore | 1 + Development-&-Test-Environments.md | 80 +++++++++++++++++++ FAQ.md | 14 ++++ Home.md | 16 ++++ Maintenance.md | 36 +++++++++ Upgrade-Guide.md | 122 +++++++++++++++++++++++++++++ _Footer.md | 1 + _Sidebar.md | 12 +++ 8 files changed, 282 insertions(+) create mode 100644 .gitignore create mode 100644 Development-&-Test-Environments.md create mode 100644 FAQ.md create mode 100644 Home.md create mode 100644 Maintenance.md create mode 100644 Upgrade-Guide.md create mode 100644 _Footer.md create mode 100644 _Sidebar.md diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..723ef36 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +.idea \ No newline at end of file diff --git a/Development-&-Test-Environments.md b/Development-&-Test-Environments.md new file mode 100644 index 0000000..3f7cef2 --- /dev/null +++ b/Development-&-Test-Environments.md @@ -0,0 +1,80 @@ +**Table of Contents** + +- [Startup](#startup) +- [Modifying JavaScript](#modifying-javascript) + - [Inline JavaScript/JSON comments](#inline-javascriptjson-comments) + - [External JavaScript](#external-javascript) +- [How to pass the CI tests](#how-to-pass-the-ci-tests) + - [Check commit messages](#check-commit-messages) + - [Check the core functionality](#check-the-core-functionality) + - [Check the SASS code style](#check-the-sass-code-style) + +--- + +## Startup + +Install [VS Code][vscode], [Dev Containers][extension], and [Docker][docker]. + +Next, fork this repository and then open VS Code to [clone your repo in container volume][clone-in-vol]. 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: + +```console +./tools/run.sh +``` + +[vscode]: https://code.visualstudio.com/ +[extension]: https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers +[docker]: https://docs.docker.com/get-docker/ +[clone-in-vol]: https://code.visualstudio.com/docs/devcontainers/containers#_quick-start-open-a-git-repository-or-github-pr-in-an-isolated-container-volume + +## Modifying JavaScript + +If your changes involve JavaScript, please read the following sections. + +### Inline JavaScript/JSON comments + +For inline JS (code between ``) or JS / JSON file containing [Front Matter][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][html-compressor] 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: + +```console +./tools/run.sh +``` + +And then open a new terminal session and run: + +```console +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][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`][commitlint] is activated. Every commit you create will be checked to ensure it meets the requirements of [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/). + +> [!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](https://typicode.github.io/husky/how-to.html#node-version-managers-and-guis)". + +### Check the core functionality + +```console +bash ./tools/test.sh +``` + +### Check the SASS code style + +```console +npm test +``` + diff --git a/FAQ.md b/FAQ.md new file mode 100644 index 0000000..b811a61 --- /dev/null +++ b/FAQ.md @@ -0,0 +1,14 @@ +**Table of Contents** + +- [Why is there a blank page after the website is deployed to GitHub Pages?](#why-is-there-a-blank-page-after-the-website-is-deployed-to-github-pages) +- [Why isn't the website content updated immediately?](#why-isnt-the-website-content-updated-immediately) + +--- + +## Why is there a blank page after the website is deployed to GitHub Pages? + +Please take the time to read the [tutorial on deployment](https://chirpy.cotes.page/posts/getting-started/#deployment). + +## Why isn't the website content updated immediately? + +To load web pages offline, we used [PWA](https://web.dev/progressive-web-apps/) in this project. Every time you use a browser to visit your website, the local cache will be displayed to you first. At the same time, a background process will check for website updates and refresh the local cache. After that, you will be able to see the latest website contents; usually, this process takes tens of seconds to several minutes. If you want to see the latest content right away, please use the incognito mode of your browser. diff --git a/Home.md b/Home.md new file mode 100644 index 0000000..5ef7f80 --- /dev/null +++ b/Home.md @@ -0,0 +1,16 @@ +## Tutorial + +- [Getting Started](https://chirpy.cotes.page/posts/getting-started/) +- [Customize the Favicon](https://chirpy.cotes.page/posts/customize-the-favicon/) +- [Writing a New Post](https://chirpy.cotes.page/posts/write-a-new-post/) + +## Showcase + +- [Text and Typography](https://chirpy.cotes.page/posts/text-and-typography/) + +## Misc + +- [FAQ](https://github.com/cotes2020/jekyll-theme-chirpy/wiki/FAQ) +- [Upgrade Guide](https://github.com/cotes2020/jekyll-theme-chirpy/wiki/Upgrade-Guide) +- [Development](https://github.com/cotes2020/jekyll-theme-chirpy/wiki/Development-&-Test-Environments) +- [Maintenance](https://github.com/cotes2020/jekyll-theme-chirpy/wiki/Maintenance) \ No newline at end of file diff --git a/Maintenance.md b/Maintenance.md new file mode 100644 index 0000000..93f75ff --- /dev/null +++ b/Maintenance.md @@ -0,0 +1,36 @@ +**Table of Contents** + +- [Releasing a New Version](#releasing-a-new-version) +- [Managing the Hotfix Branches](#managing-the-hotfix-branches) + +--- + +## Releasing a New Version + +To release a new **Major** or **Minor** version, perform a *no fast-forward* merge from the `master` branch into the `production` branch. + +To release a new **Patch** version, perform a *no fast-forward* merge from the `hotfix` branch into the `production` branch. + +When GitHub Actions detects updates to the `production` branch, it will automatically trigger the release process. + +> [!IMPORTANT] +> Please **do not enable** any check tools such as `Codacy Static Code Analysis` or `commitlint` under the repository’s branch protection rule *Require status checks to pass before merging*. Doing so will prevent GitHub Actions from pushing commits to the `master` branch, which will cause the automated release process to fail. + +## Managing the Hotfix Branches + +The `hotfix` branch naming format is `hotfix/..`, e.g. `hotfix/3.2.1`. It is a temporary branch with a life cycle: + +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. +4. Delete this branch. + +[front-matter]: https://jekyllrb.com/docs/front-matter/ +[html-compressor]: https://github.com/penibelst/jekyll-compress-html +[ci]: https://en.wikipedia.org/wiki/Continuous_integration +[commitlint]: https://commitlint.js.org/ + diff --git a/Upgrade-Guide.md b/Upgrade-Guide.md new file mode 100644 index 0000000..49e606f --- /dev/null +++ b/Upgrade-Guide.md @@ -0,0 +1,122 @@ +**Table of Contents** + +- [Upgrading from Starter](#upgrading-from-starter) + - [Preparation](#preparation) + - [Adding Upstream](#adding-upstream) + - [Handling Submodule](#handling-submodule) + - [Fetch Updates](#fetch-updates) +- [Upgrade the Fork](#upgrade-the-fork) +- [Major Version Upgrades](#major-version-upgrades) + +## Upgrading from Starter + +If your website was created using [`chirpy-starter`][starter], follow these steps to update your repository. + +### Preparation + +The operations mentioned in this section only need to be performed once after cloning your repository locally. + +#### Adding Upstream + +```console +git remote add chirpy https://github.com/cotes2020/chirpy-starter.git +``` + +Verify the remote was added successfully: + +```console +git remote -v +``` + +The output should include: + +```log +chirpy https://github.com/cotes2020/chirpy-starter.git (fetch) +chirpy https://github.com/cotes2020/chirpy-starter.git (push) +``` + +#### Handling Submodule + +If your workflow does not require the submodule `assets/lib`, run command: + +```console +git config submodule.assets/lib.ignore all +``` + +This prevents the submodule from pulling files and taking up local disk space. + +### Fetch Updates + +The following steps need to be performed for each update. + +1. Fetch all tags from upstream: + + ```console + git fetch chirpy --tags + ``` + +2. Merge the latest tag from upstream into your local branch. For example, to merge tag `vX.Y.Z`, run: + + ```console + git merge vX.Y.Z --squash --allow-unrelated-histories + ``` + +3. If the list of conflicting files includes the submodule `assets/lib`: + - If you do not want to use the submodule, execute: + + ```console + git restore --staged assets/lib + ``` + + - If you have already initialized and enabled the submodule, follow the output hint: + + ``` + hint: - go to submodule (assets/lib), and either merge commit + ``` + + Record the `submodule_commit_hash` and update the local submodule: + + ```console + git -C assets/lib merge + ``` + +4. Resolve any remaining file conflicts manually. Keep any custom modifications if needed. + +5. Once conflicts are resolved, create a new commit to save the upgrade: + + ```console + git add . && git commit -m "chore: upgrade to X.Y.Z" + ``` + +6. Update the local theme gems: + + ```console + bundle update + ``` + +## Upgrade the Fork + +If you forked from the source project (there will be `gemspec` in the `Gemfile` of your site), merge the [latest upstream tags][latest-tag] into your Jekyll site to complete the upgrade. +The merge may conflict with your local modifications. Be patient and careful when resolving these conflicts. + +JS distribution files have been removed since [`v5.6.0`][v5.6.0], and Bootstrap CSS has been lean since [`v7.0.0`][v7.0.0]. For future upgrades, compile the CSS/JS files yourself: + +```console +npm run build +``` + +Then add them to your repository files: + +```console +git add assets/js/dist _sass/vendors -f +``` + +## Major Version Upgrades + +When upgrading to a **Major** version, read the [release notes][release-notes] for that version to understand any changes in project configuration. + +[starter]: https://github.com/cotes2020/chirpy-starter +[latest-tag]: https://github.com/cotes2020/jekyll-theme-chirpy/tags +[v7.0.0]: https://github.com/cotes2020/jekyll-theme-chirpy/releases/tag/v7.0.0 +[v5.6.0]: https://github.com/cotes2020/jekyll-theme-chirpy/releases/tag/v5.6.0 +[release-notes]: https://github.com/cotes2020/jekyll-theme-chirpy/releases diff --git a/_Footer.md b/_Footer.md new file mode 100644 index 0000000..57a0471 --- /dev/null +++ b/_Footer.md @@ -0,0 +1 @@ +[:pencil: Helps improve this page](https://github.com/cotes2020/jekyll-theme-chirpy/discussions/new?category=general) \ No newline at end of file diff --git a/_Sidebar.md b/_Sidebar.md new file mode 100644 index 0000000..2ab489b --- /dev/null +++ b/_Sidebar.md @@ -0,0 +1,12 @@ +- [**Back to Home**](https://github.com/cotes2020/jekyll-theme-chirpy/wiki) +- **Tutorial** + - [Getting Started](https://chirpy.cotes.page/posts/getting-started/) + - [Customize the Favicon](https://chirpy.cotes.page/posts/customize-the-favicon/) + - [Writing a New Post](https://chirpy.cotes.page/posts/write-a-new-post/) +- **Showcase** + - [Text and Typography](https://chirpy.cotes.page/posts/text-and-typography/) +- **Misc** + - [FAQ](https://github.com/cotes2020/jekyll-theme-chirpy/wiki/FAQ) + - [Upgrade Guide](https://github.com/cotes2020/jekyll-theme-chirpy/wiki/Upgrade-Guide) + - [Development](https://github.com/cotes2020/jekyll-theme-chirpy/wiki/Development-&-Test-Environments) + - [Maintenance](https://github.com/cotes2020/jekyll-theme-chirpy/wiki/Maintenance) \ No newline at end of file