Update your template

If the template has been updated since you first created your website from it, you may want to pull in the updates.

👤 Your version of the template is located in the CITATION.cff file in your website repo.

✨ The latest version of the template can be found in the main CITATION.cff file here.

📋 A high-level description of changes for each version can be found in the main CHANGELOG.md file here.

For convenience and familiarity, we also duplicate the template version info in GitHub tags and releases, but we consider the CITATION.cff file to be the source of truth. Tags/releases do not get transferred when generating from a template, and comparing commit hashes is not ergonomic, so we opted to have the version plainly specified in a file the user should always keep in their repo.

From pre-release

If you are coming from a pre-release version of the template (< v1.0.0), we strongly recommend just starting from scratch and not even attempting the merge instructions below. It will be quicker, easier, and less error-prone. Forget everything you know, start a new copy of the template, read through and follow the new docs, and judiciously copy and modify code from your old site into your new site. We know this is frustrating, but we think the upgrade is worth it.

If you can't or don't want to start from scratch, go through the merge instructions below, then go run the setup instructions and custom domain instructions if applicable.

Begin a merge

First, begin a merge of the latest template repo into your website repo. The method to do this depends on whether you generated or forked from the template:

Generated

Based on this post:

git remote add template https://github.com/greenelab/lab-website-template
git fetch --all
git merge template/main --allow-unrelated-histories

Forked

Based on this article:

git remote add upstream https://github.com/greenelab/lab-website-template
git fetch upstream
git merge upstream/main

Resolve merge conflicts

Because this is a template and not an installable package, updating it can unfortunately be difficult. This process is very tricky, even for the maintainers of this template. When doing this, carefully check every page and section on your site before publishing the changes. We can help you if you have trouble.

After you've started a merge, you'll mostly likely have to resolve some merge conflicts.

If you generated your website, you'll have to resolve all of the conflicts manually. This is because generating from a template starts a completely new, unrelated Git repo with no shared commit history, so Git has a difficult time automating the process.

If you forked your website, the process should be a little bit easier, but you'll still probably have to manually resolve some conflicts.

We'll assume you already know how to perform a merge conflict resolution in your Git interface of choice.

The hard part is carefully picking out which changes to accept. This essentially boils down to distinguishing between template content and user content. For template content, you want to "accept incoming/their changes" (pull in updates from the template). For user content, you want to "accept current/our changes" (keep the current content in your repo). There is also template repo only content, which you should be careful not to re-add.

Sometimes updates to the template will be "breaking changes" and will affect your user content, like a component parameter being renamed. Be sure to check the changelog for these changes. You may have also made modifications to template code, like tweaking the appearance of a component. In these cases, you'll have to judiciously decide how or if to merge in the updates.