Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Document guidance on moving content to a new version of the Electric Book template #57
Obviously a key to this is my getting stricter about semantic versioning. I've probably made many breaking changes in semver patch numbers. I'm not too concerned about this while we're still at major version 0, but we will absolutely need a simple upgrade path by the time we hit 1.0 next year. So any structural decisions need to be really solid here on out.
More thinking on this: we could define certain files as 'core' template files that, on upgrade, will be overwritten. Users should be warned (in both code comments and general documentation) not to edit these, because an upgrade would overwrite them. If a user needs to adapt a core template file, they should create a renamed version of it and use that.
We would create a set of upgraded, core-only files to copy into an existing project directory.
One tricky area is upgrades to
Then again, easy upgrades may never be possible. It may be better to provide guidance and best-practice on using the template in a way that makes upgrading later easier. For instance, avoid customising template includes.
@SteveBarnett Further to discussion in #95: Another frequent use case for an easy way to upgrade is testing new features. To really test a new feature, we should use it in a repo with examples of everything the EB workflow can handle. But adding all the data and content required for that to the template is a PITA.
It would be great to be able to use https://github.com/electricbookworks/electric-book-workflow as a test repo, since it's already got of examples of almost everything in it (we could add a translation example). But currently changing its template version is a tricky manual process of replacing and, in places, editing exactly the right files.
We need a way to do:
(Content and customizations) + (EB template vX.Y.Z) = Electric Book vX.Y.Z
That might still be a multi-step, partly manual process, but should be, say, three quick steps, e.g.
Our first step towards that is deciding what files and folders constitute 'core' template files that a user should not change, because they would be overridden by a template-version change. Then, we can decide whether:
The first option means there's less for us to maintain; but we'd have to rewrite some stuff to test for the presence of includes like
Note on my semver expectations once we're at 1.0:
That is, print-pdf output becomes a key test.
referenced this issue
Mar 17, 2017
Some further thoughts: Octopress is doing some interesting things in its move to 3.0. I'm not sure we want to go as widely modular as they do (see the Octopress org on GitHub to see the way they do it with lots of gems and Octopress wrapper scripts for all the things. Their bit on updating is also interesting.
A first step for us might be to add another option to the
Something we can do to prep for upgrade is review the separation of Jekyll stuff, EB stuff, and Theme / project stuff (I'd also be keen to see where we can simplify stuff and remove some duplication, use the defaults as much as possible, and so on).
For reference, these were the steps I took on another project to update it. Not applicable to all projects, but an indication of the kinds of decisions one needs to make.
I've come to believe upgrades are unlikely to ever be simple, given that this template is a template, not a CMS, and is often highly customised. Instead, we could add documentation as rough guidance on how to approach moving content from an old version of the template to a new one.