123 lines
3.5 KiB
Markdown
123 lines
3.5 KiB
Markdown
**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 <submodule_commit_hash>
|
|
```
|
|
|
|
Record the `submodule_commit_hash` and update the local submodule:
|
|
|
|
```console
|
|
git -C assets/lib merge <submodule_commit_hash>
|
|
```
|
|
|
|
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
|