New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document guidance on moving content to a new version of the Electric Book template #57

Closed
arthurattwell opened this Issue Jan 6, 2017 · 7 comments

Comments

Projects
None yet
2 participants
@arthurattwell
Member

arthurattwell commented Jan 6, 2017

As a technical user, I want to upgrade my instance of the Electric Book Jekyll template without spending hours looking for breaking changes, so that I can take advantage of improvements to the template since I set up my project.

@arthurattwell

This comment has been minimized.

Member

arthurattwell commented Jan 6, 2017

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.

@arthurattwell

This comment has been minimized.

Member

arthurattwell commented Feb 23, 2017

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 _print partials, because changes there can affect reflow of books, which can have disastrous consequences for print books with no tolerance for reflow. Do we need to version-number _print partials, or perhaps have separate upgrade files for those. I.e. they are not considered core upgrades?

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.

@arthurattwell

This comment has been minimized.

Member

arthurattwell commented Mar 17, 2017

@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.

  1. Drop this directory of core files into your Jekyll root and let it overwrite existing files. It will not overwrite config files (e.g. meta.yml, _config.yml), 'this list' of customizable includes (e.g. end-elements, contact-form) any files in book folders.
  2. Run this search script, which checks whether your config files have all the variables this version requires.
  3. Add any settings/variables the search script suggests.

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:

  1. the template is the upgrade, and we remove all example files from the template, providing them in a separate 'sample data' repo; or
  2. we maintain a separate 'upgrade-to-latest' repo that only contains core files and nothing a user would normally modify.

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 end-elements, and provide fallbacks in their absence, since they won't ship with the template.

Note on my semver expectations once we're at 1.0:

  • major: book might not even build
  • minor: book will output but print pages might reflow differently (e.g. template Sass changes)
  • patch: print-pdf output will flow into the pages exactly the same way before and after the version change.

That is, print-pdf output becomes a key test.

@SteveBarnett

This comment has been minimized.

Collaborator

SteveBarnett commented Apr 20, 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 run-* scripts: upgradethat copies the files over. Once we have our cross-platform ruby script that replaces those, we might want to ebw upgrade instead.

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).

@arthurattwell

This comment has been minimized.

Member

arthurattwell commented May 25, 2017

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.

  • _config.yml: replace with template file, update settings
  • run-*: update with template files
  • /assets: replace existing template files with new ones
  • /book: don't change; may need to add unset Sass variables, which Jekyll will tell you about as an error when building
  • /_configs: remove all, replace with template files
  • /_data/meta.yml: check for required, unset, changed variables
  • /_html: remove folder if it exists
  • /_includes: replace template files with new ones
  • /_layouts: replace template files with new
  • /_sass: remove all and replace with template files; check print output
@arthurattwell

This comment has been minimized.

Member

arthurattwell commented Oct 28, 2017

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.

@arthurattwell arthurattwell changed the title from Electric Book upgrade path to Document guidance on moving content to a new version of the Electric Book template Oct 28, 2017

@arthurattwell

This comment has been minimized.

Member

arthurattwell commented Feb 11, 2018

Basic guidance added in #233.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment