Docs should explain upgrade path

[Vaguery]

Is there any hope of an upgrade walk-through for bringing a site from 2.X -> 3.X? We have extensive modifications of the base template(s) and designs in our 2.X-based site, and have no idea where 3.X overlaps or diverges from 2.X

[mmistakes]

Essentially this https://mmistakes.github.io/minimal-mistakes/docs/upgrading/

Everything is new and there isn't much that stayed the same from 2. If you made any customizations then you're probably in for some pain. If not then the best thing to do is dump everything except your content (posts, pages, collections, and assets) and add them to a fresh version of 3.0. Then set some Front Matter defaults for things like layout in _config.yml as I changed the layout names to be more semantic eg. post.html ~> single.html since it applies to more than just posts.

[mmistakes]

The compare feature on GitHub might be useful for you as it can be used to identify what changed between commits, tags, releases, etc. For example here's a diff compare between 2.2.1 and the latest release 2.2.1...3.1.1

You can also compare between forks so you might be able to diff yours against 3.1.1 to figure out what to update. To be honest so much changed I don't think I even know everything I touched to properly document an upgrade path. It's essentially a new theme with the spirit of the original.

[wilsonmar]

I am very excited to make use of the new features, and I'm very grateful to Mike for leading the way.
But I realize there is complexity to upgrade.
Past experience tells me that several attempts is necessary to upgrade smoothly.
I won't be able to tweak a few settings and call it good because I have a live site in the old way.
For this reason I am building a repeatable approach so I can experiment various tries at upgrade.
Initially I created a shell script to download Mike's test-data repo and copy that on top of the minimal-mistakes theme files.
I'm using clone because I'm having problems getting the download to unzip since its folder contains a random code.

The initial attempt is at:
https://gist.github.com/wilsonmar/e2a146402ecd964100c9020127c605fd
repeated below:

#!/bin/bash
# getitfresh.sh in ~/gits folder
# reset theme from original by Michael Rose:
# Run this from any folder:
# Tested on Mac OSX El Capitan.
# 
set -x #echo on
cd ~/gits/jekyll

rm -rf minimal-mistakes
#   clone all history and branches:
git clone http://github.com/mmistakes/minimal-mistakes.git
#curl -L -o minimal-mistakes-master.zip http://github.com/mmistakes/minimal-mistakes/zipball/master/
#unzip minimal-mistakes-master.zip -d /minimal-mistakes
#rm minimal-mistakes-master.zip

rm -rf jekyll-theme-unit-test
git clone http://github.com/mmistakes/jekyll-theme-unit-test.git
#curl -L -o jekyll-theme-unit-test-master.zip http://github.com/mmistakes/jekyll-theme-unit-test/zipball/master/
#unzip jekyll-theme-unit-test-master.zip -d /jekyll-theme-unit-test2
#rm jekyll-theme-unit-test-master.zip

cp -Rf jekyll-theme-unit-test/* minimal-mistakes/ 

cd minimal-mistakes
bundle
python -mwebbrowser http://localhost:4000
bundle exec jekyll serve

To this I may need to write a program to scan through existing files to generate a combined file.

[mmistakes]

I think all of this gets much better once the "themes as gems" feature lands and Jekyll begins to mature.

Right now the whole idea of forking "some dude's repo" and calling that a theme is a pretty big mess.

It's probably not all that bad if you take the repo wholesale and don't change anything, but I think most people want to create their own thing. And that's when the real trouble begins as you really need to have an understanding of the source and track all changes to stay in sync.

[mmistakes]

@wilsonmar RE: pulling in test data. The jekyll-theme-test-unit set of files could probably be distilled down further and added as submodules similar to this approach.

I personally haven't worked with git submodules so I can't comment on how viable or easy that would be to do.

[wilsonmar]

Submodules would involve using hooks as well. Not too difficult but may be scary. My question is whether it's better to put the theme in the sub-module rather than content in a sub-module, as the article suggests.

[mmistakes]

@wilsonmar I thought about putting the theme in a submodule but that involves another layer of setup for the user. That and official support to do essentially the same thing is coming to Jekyll. I'd rather see how things shake out before committing to one or the other.

[wilsonmar]

Agreed. That's why for now I'm focusing on a bash script to download a theme, and populate it with demo data. Once that works, I'll overlay with my own folder of files instead of your demo files. But I'm stuck on errors after overlaying with your demo data.

[ghost]

@Vaguery et. al, when modifying themes like this it's a good practice to fork it and keep your own copy, including modifications, for which your actual website builds from. Here's why:

1. Theme enhancements and bugs discovered can quickly and easily be PR'd back to the fork's upstream repo (this one).
2. Any changes you've made to the theme itself are clearly separated from the content and specific modifications for your site.
3. When the base theme is updated you can upgrade and apply your customizations using git rebase, which will allow you to resolve merge conflicts, keep the commit history clean (meaning your commits won't be interspersed with what's coming down from the upstream) and level up your git-fu.