Discussion: Release concerns

[imathis]

When we release 3.0, I'm concerned that people will assume it's just like 2.0 but better in some way. However, this release is very different from what Octopress has been up until this point. This will be the first part of a larger release. Octopress is shifting from being essentially a blog that you fork to a modular system of independent components. It will also be build on the latest version of Jekyll, something which Octopress is currently incompatible with due conflicts with a few plugins. Essentially, Octopress 3.0 will be better suited to Jekyll users than Octopress users, at least initially.

For those currently using Octopress, it will be a while before the new releases can compete with the features of the old version. For those who want themes and plugins, they'll have to wait for the release of octopress-ink, and themes and plugins to be built on top of it. With each release, vanilla Jekyll users will be able add the new shiny stuff to their sites.

Once Octopress is to the point where it can replace the old version, I'll need to have a plan to help people migrate. I'd love for it to be as simple as "Copy your posts into a new site, and run octopress init; octopress build, but they might be using some old liquid plugins which aren't being maintained anymore and don't work with the new version Jekyll. These users will see build errors and have to wade through their posts and pages and remove stuff that breaks things. I really hate that this is what lots of people are going to go through if they want to update their blogs.

I totally believe in what we're doing with this release, but it frustrates me to know this is what is going to happen. If this new release gets any attention at all, I'm going to be answering the "how do I migrate" question a lot, so I need to come up with a plan. I feel like that plan needs to be part of this release so here's what I want to do.

1. Get this code into imathis/octopress
2. Delete this repo
3. Move imathis/octopress to octopress/octopress
4. Rename the current master branch to 2.0-deprecated (better name?)
5. Make the branch containing this code base the new master branch.
6. rake release

Before I do that I need to have a blog post written explaining what's going on. I'm nervous about writing that post. I've sucked at managing this project and I deserve whatever criticism for the mistakes I've made. Part of me wants to delay the release of this until I can have more to show people so it will be more clear how things will work in the future. Only releasing the CLI and octopress-deploy kind of begs for a "we've waited three years for this?" response. I think Octopress-Ink will be the exciting part of this release and part of me wants to get it done before dropping the release candidate and owning the 3.0.

Anyway, that's what's swirling around in my head. Whoever reads this, feel free to advise.

[zackp30]

Can't wait! :)

[parkr]

When we release 3.0, I'm concerned that people will assume it's just like 2.0 but better in some way.

A release post will help with this. The first sentence after "Octopress 3.0" is out, should be "it's TOTALLY different than Octopress 2.0. Keep reading for more." As long as we're clear in communicating this, we'll be fine 😃

Once Octopress is to the point where it can replace the old version, I'll need to have a plan to help people migrate. [...] I really hate that this is what lots of people are going to go through if they want to update their blogs.

We can't make the upgrade process wholly seamless – the new Octopress is completely different than what Octopress 2.0 is, so yes, there will be pain. I think that's fine (we have ways to get help if people get stuck) – if it's 8 hours of pain, that's one thing. But insofar as the upgrading pains are reasonable, I think we can reasonably expect the user to do a bit of work to get the new version.

Only releasing the CLI and octopress-deploy kind of begs for a "we've waited three years for this?"

No Octopress users are entitled to anything. If someone says this, they can go build their own blog tool. You've poured your heart and soul into Octopress and its various components and absolutely no one is entitled to expect more than what you decide to deliver. Octopress 2.0 is admittedly a bit bloated, and Octopress 3.0 gives users a lot more in terms of ease-of-use (upgrading is going to be AWESOME after 3.0, for one). I think you have done a wonderful job – Octopress gets more love than most of the open-source repositories on this site (remember when you took 3 months to work full-time on this?). That's huge. You rock for sharing this with us, whatever it is.

[staxmanade]

I just recently ported to OctoPress 2.0 from BlogSpot and wanted to throw a couple concerns/pointers your way...

1. Thanks for everything you've done.

2. If you updated the OctoPress 2.0 readme to consider saying something like

   Warning: If you're about to start a fresh blog with OctoPress, consider taking a look at OctoPress 3.0 (It's still a work-in-progress)... (possibly some other warm & fuzzy disclaimer text?)

   I've spent lots of time hacking and porting my blog to OctoPress 2.0. I've really enjoyed the process (as it's totally hacking in some cases 😸) but I somehow missed the OctoPress 3.0 and how it's going to be quite different.

3. I'm a bit concerned that a little 9-part-series on how to port from BlogSpot will soon become out-of-date. This is something I feel I'm running into across the web - many people who have ported to OctoPress, have created blogs related to how they did it, or tweaks they made. Some of which are old and out of date already (that's a general problem with blogs) - but this may be even worse with 3.0...

4. This is open source, and people are people. (<-- that's about the most generic sentence I've ever written) So you're going to get some haters, but it's their own fault for picking something that's tagline is A blogging framework for hackers.. I wouldn't worry too much about it. There's too many good things going on in the OSS world to worry about those who aren't going find a way to take their little bit of pain and find a way to pay it forward.

5. While all of my experiences during my port and I'm currently working through are/were not ideal, that's kind-of the point. I've learned about Ruby (which I only knew enough to hack some Rakefile's together) and now I know more about Jekyll.

6. I feel like I have more to add, but it's time to take my little girls to pickup Easter eggs

👍 on the work you've done. I hope I can help to provide value once I get to know it better .

[mattr-]

As long as we're clear in communicating this, we'll be fine 😃

No you won't. It won't matter how well or how much you communicate it, the fact that the 3.0 release is the start of a much better Octopress 3 series but not yet ready to replace Octopress 2.x will be lost on most users. I can speak from experience here since this is exactly what happened to us in the KDE community with the KDE 4 series. KDE 4.0 was similar to Octopress' 3.0 release and despite everything we said about it's not really ready for users of the 3.x series yet, we still faced a ton of backlash. This is what will happen with the mob.

[mattr-]

No Octopress users are entitled to anything. If someone says this, they can go build their own blog tool.

While this statement is true, they'll still act like they're entitled to it and nobody will go build their own blog tool. They'll just bitch about how Octopress 3.0 sucks and that nobody should use it. My prior comment explains the reasoning.

[mattr-]

Having been in a similar situation before, I totally applaud the efforts you're putting in to make Octopress better software - software that will be easier for you to maintain, provide more functionality for its users, and give those same users a better experience.

I have two suggestions, which you are totally free to take with a grain of salt 😃. The first is to distance the latest releases of this project completely from the Octopress brand. Call it completely something else, iterate on those releases until you have something that is close enough to the previous version of Octopress, and then "merge" the two projects and then call it Octopress 4.0 after the merge.

The second suggestion is to never put out a release of Octopress 3 that isn't a pre-release until it's ready for prime-time as a replacement for Octopress 2. This allows you to still get releases out there, and iterate on the software without the giant backlash from the mob. You'll still get some feedback and those folks are most likely to be able to understand what you're trying to do with Octopress 3 before you do a GA release. This may mean that the first release of Octopress 3.x that you do that doesn't have an .pre or a .rc suffix, may be a 3.5 or a 3.6 release. I think that's ok.

It beats have the soul sucking, soul crushing, motivationally draining, emotionally wrecking experience that comes with huge changes in major releases.

[drallgood]

Having migrated from 2.0 to 3.0, I think there is a way to do this the right way.
3.0 seems to be (on its own) ready for primetime. It's just a lot different compared to the 2.X branch and thus veterans might have to learn a few things.

I'd suggest to provide a migration tool that does the following:

• create a new project
• install & configure jekyll-compass
• copy custom plugins, themes and content to it. Upgrade the "old" octopress plugins.
• update the config (a few things have changed)

That should help mitigating the major pain points of any migration. If someone has customized his old octopress a lot, he'll need to fix a few things, but overall that should give him a head start.

As for new users:
They can just go ahead with 3.0. All they need is a little bit more documentation.

[imathis]

@mattr- I really want to keep the Octopress name. This is finally what I always wanted this project to become and I feel like the name is finally starting to fit.

I feel like I'm still a bit too close to things to make a decision right now. Some of this work is really fun: building the tools, writing plugins, writing documentation; and some of it is not so fun: Figuring out how to update the existing documentation, redirects, and what to do with issues on a project I can't hope to maintain in its current state.

Sometimes I'll be listing through the things I need to do to release and my mind just grinds to a halt when I get to the parts that worry me. It's easier to just work on the next thing I know I need to do. Right now I'm working on Ink a lot, and building a new default theme for it. It's really exciting and should serve as a great way to show how this stuff is supposed to work. Once I have that done, I think I'll be able to see more clearly and think about the right way to handle the release.

To all who've commented on this issue, thank you so much; it means a lot to me. If you're reading this and not commenting, thank you too. I feel like I've mucked things up a good bit and I'm really encouraged that people are still excited about the stuff I'm building.

[imathis]

@drallgood I really do need to write a migration guide, but one problem is that everyone is going to have a different expectation of what it means to migrate. To me it means, you have your content in a new working octopress site, but all that old stuff with the .themes directory and Rake and Compass is gone. I want this thing to look like any other Jekyll site. It's probably hard to imagine how that will work since Ink isn't yet released. When that happens I think it'll be more clear why I want to do that.

Of course, many people probably just want things to keep working and use the latest Jekyll. I'm not sure how to help those people because everyone's sites have become something entirely their own. The whole Octopress themes system is something I wanted to build for but never supported until Ink. All those third-party themes rely on a thing that was never meant to be used this way. It was an early idea of how I might manage themes which never matured.

Basically there's a lot of stuff people have done to their sites which I don't really have any desire to support or encourage, and sadly a lot of that is stuff I set a pattern for. I have to figure out how to explain to these people why the new way is worth dumping lots of their stuff to embrace. It's a hard sell for some, but for many who never changed their site at all, it should be pretty easy.

Anyway, lots to think about.

[jbinto]

To all who've commented on this issue, thank you so much; it means a lot to me. If you're reading this and not commenting, thank you too.

No, thank you @imathis (and @parkr) for all your work with Octopress.

I'll just add a bit of perspective. I've been using Octopress 2 for just over a year now. I used it as a black box, only peripherally aware that it made use of Jekyll under the covers. Everything I know about Octopress I learned from the documentation. I only just recently realized that the {% %} syntax comes from Liquid, I had assumed it was Octopress specific.

I spent some time trying to look into Octopress 3 a few months ago, but was scared away by how fundamentally different it is. I'm a little clearer after following this issue for a few weeks, and I do realize it's still a WIP.

My impression of Octopress 3 is "batteries not included", e.g. it assumes you already have a Jekyll site, and the new Octopress is just a set of tools to manipulate blog-type content inside that context.

I don't know whether I'm representative of the wider user base. But I wanted to convey that there may be a subset of Octopress users who are completely ignorant of all things Jekyll, and perhaps a migration guide should be written considering that perspective.

My Octopress 2 blog is very vanilla, I'm not using any exotic plugins or themes. I only have a dozen or so posts. I'm happy to do any migration by hand, massaging data as necessary. If this means creating a new blog from scratch and importing these old posts by hand, so be it. If it means getting my hands dirty with Jekyll, so be it. But I don't want to go down blind alleys. What do you recommend for this simple case?

[imathis]

@jbinto Thanks for your response. I've heard many similar things from many people over the years. Octopress has been a gateway for Jekyll, Liquid and for many folks, even Ruby. Even though the tagline is "a blogging framework for hackers" the Octopress user base represents a much wider audience than I ever could have anticipated. I've met teachers who use this as a way to avoid their institutions terrible site publishing tools and even folks who's geek friend or spouse set them up with it and simply taught them the steps they need to know.

You're right about Octopress being "batteries not included" for the moment. Octopress Ink is very soon to be released and it should not only alleviate that concern, but provide a new tool to the whole Jekyll community for using and building plugins and themes with tremendous simplicity.

For users like you who've made minimal changes and who largely just want Octopress for the simplicity of setup and workflow, this is what I imagine the upgrade process will be like:

1. gem install octopress; gem install octopress-default-theme
2. Create a new branch in your project.
3. Move all files and directories into _old_site/
4. jekyll new . --bare
5. octopress init .
6. Copy pages and posts over from _old_site/
7. Add gems: [octopress-default-theme] to your _config.yml.
8. Change posts to have layout: theme:post and pages to have layout: theme:page in their yaml front-matter.
9. Run jekyll build

This of course will only get you up and running with a new theme. If you used any of the old Octopress plugins that shipped with Octopress by default, you'll likely get some build errors. My hope is to have new versions of most of the plugins available at launch. This would mean that you'd get to pick and choose what you install and simply add them as gems in your Jekyll configuration or your Gemfile under the :octopress group. Some of the plugins which have liquid tags will have new syntaxes so posts or pages will need to be updated to use the new syntaxes.

So yeah, depending on what you've done to your blog, this is what it might look like. People who've been using vanilla Jekyll all along, will have a much easier time adding Octopress and it's plugins and themes into their sites and workflows. By bringing Octopress back inline with the Jekyll and its conventions, I'm hoping to merge the two communities so Octopress is no longer seen as a an alternative option to Jekyll. It will simply be a framework for Jekyll that is as modular and disposable as anything else. Unfortunately to get there, it's probably going to be tricky for folks to upgrade.

[sheriferson]

I write this from the perspective of an amateur programmer who doesn't know Ruby but has successfully tinkered with Octopress 2.0 enough to create a site that I'm very happy with.

First, I do want to thank @imathis a lot for his work so far. I've used Octopress for a long time and it's awesome.

I think a basic guide on how to move over the content - and nothing else - from an Octopress 2 system to a clean/brand new 3.0 one would help a ton.

Any users who would have to go through some pain to migrate from 2.x to 3 would have had to do quite a bit of tinkering with themes, plugins, etc, and my impression is that one should know the risks of tinkering with a system they don't fully understand. Even if they didn't do a ton of modifications, Octopress is clearly targeting a certain group of tinkerers with some tolerance for that kind of pain.

I admit I did a whole bunch of 'hacking' with the 2.x install I have, and I accept that I may have to start fresh with customization in a 3.0 Octopress. I would just appreciate a guide on how to start. The instructions in the current README don't seem sufficient to create a working site, so if instructions for creating a clean site are added, I think that would comfort a lot of people/alleviate a lot of concern.

[imathis]

I do hope to write a more thorough guide on how to migrate content over. I don't suspect many people will want to migrate until I have finished at least one theme for Octopress Ink and Octopress 3.0. I'm working on finishing that part up now and once I'm done I'll begin working on a guide. At first it will be a brief guide and hopefully some early adopters will help me iterate on it based on their experiences.

[ludwick]

@imathis - When I find some time to migrate over, I'll probably just try the list of steps you gave above as they seem pretty clear. I'm really looking forward to this version since it's always bothered me a little that the repo for my website had the full octopress repo as part of its history and getting new versions was a merge (and if I wanted to use plugins, sometimes those too, if I didn't just copy them over!) Having it all gem-ified seems so much cleaner even if original octopress made me learn just a little bit of ruby.

Sadly, I think no matter what you do, some people will be upset or they will be using the original octopress in a way you didn't anticipate and so upgrade is harder than expected. I think it will help though just to be clear why it's not "one click". I'd be happy to read blog post drafts if you think it would help to have more eyes on it.

[ludwick]

So today (in between other things and after an epic "install xcode, nuke and reinstall macports, upgrade ruby" session mostly due to the fact I haven't touched it in more than a year), I have most everything working, with the genesis theme. Only things that look busted so far are pagination & somehow the theme configuration is being ignored. Not too bad once I looked at it (and it doesn't help that I've never used a "regular" jekyll site so all I know is the old octopress way).

[dgmstuart]

I've recently done a migration (of sorts) from Octopress 2 to 3 so thought I'd share my thoughts:

My current understanding that I've pieced together is that:

Octopress 2 was a full-featured blogging platform all in one bundle, with a lot of features provided by the default theme, and where other themes were expected to use the same sort of contract: i.e. you were able to switch out different themes and more or less keep the the same config file.

You could extend it with Octopress-specific plugins. I'm still not clear on what the relationship was with pure jekyll plugins.

Jekyll works as a blogging platform out of the box, but doesn't provide much in the way of tooling to help you write blog

Octopress 3, at it's core, is a jekyll plugin which fills that gap by providing some great tools for managing posts and deploying the blog.

Is that all basically correct?

As far as I'm concerned it's actually great: Octopress is now a small, sharp tool for doing a small set of things, and it has clear boundaries. It will let me use whatever tools and themes are available to whole the jekyll community.

I didn't really understand any of the above until I started looking into it. If I'd actually read the description on the new repo I would maybe have gotten there quicker, but it took some work to get my head around it. The trigger was when I 'completed' the migration, and realised that none of the built-in features (google analytics, disqus comments etc) came for free - because they had been features of the Octopress theme.

Getting back to feature parity does mean a bit of manual setup and finding a new theme etc. - I'm happy to do that, though I can see how some wouldn't be.

I don't really understand exactly how the genesis theme will fit in - presumably in future running octopress new will use that instead of the jekyll default? Is it in some way tied to using octopress/octopress or is it essentially just an awesome jekyll blogging theme that could be used independently of octopress?

[dgmstuart]

So one thing which might have helped me understand quicker (and set expectations for other migrators) might be a paragraph at the top of the readme briefly expanding on the problems that Octopress exists to solve and how it solves them.

[dgmstuart]

Also thank you so much for this project - not only has Octopress has been my introduction to Jekyll but also to liveblogging, and has also been an important factor in my moving towards using Vim as my main editor.