Versioning about guide HOT 11 CLOSED

My plan was to publish the guides from branches - so we can have a 1.2 branch, a devel branch, and any number of translations for different versions.

Ideally, we could even deploy from PRs - as soon as someone submits a PR, we deploy that version to a preview link with the commit hash so that we can evaluate the change by looking at the rendered version.

from guide.

I can't think of any good way to flag differences - do you have any examples of other guides that do this?

from guide.

My plan was to publish the guides from branches

Interesting ... you seem to be implying a whitelisted set of branches? So, over time when we get to 3.0, we'll still be able to go back and look at the docs for 1.2? And 1.2 is basecamp for the new guide (so no 1.1 docs)?

Ideally, we could even deploy from PRs...

That's a brilliant idea - love it 😄

I can't think of any good way to flag differences - do you have any examples of other guides that do this?

Errm, no. I'm just the ideas guy 😉. Assuming these are being built from git commits, would it be difficult to add something if git diff flags differences on lines?

from guide.

Yep, I'm thinking a whitelisted set of branches. Building a complete guide for 1.1 seems like a step back to me - at the end of the day there is a limited amount of effort we can put into this and I would much prefer having one complete guide than two half-baked ones. My thought is that as soon as 1.3 comes out, we'll just make a new branch and leave the 1.2 guide as a historical thing, and maybe fix it every once in a while if there's an inaccuracy, or someone feels super compelled to contribute to it. But the focus will always be on the newest thing at least from my point of view.

I'd say the differences between versions thing could be a super stretch goal, but I'd rather not invest the energy designing something like that up front, especially considering the file structure could change, etc. If someone finds a good and functional example of such a design, we can consider it.

from guide.

A new branch for a new version is great, 1.2 for 1.2.., same 1.3, etc.

Another question - what about the localization, will be have it? And if yes, what version will it be - always latest?

from guide.

I think localization is something we should work towards. I think we are moving in several directions that make it easier:

1. Having the guide in a separate repo makes it easier to make a fork
2. Being able to deploy multiple versions means we can just have branches like 1.2-cn, 1.2-ru, etc
3. Having a more standard static site generator means it's much easier to understand and modify the website and content

I think there are already people out there interested in helping with localization, we just need to give them the tools. And if that doesn't work we could always hire someone.

from guide.

@stubailo yes, I understand. I am worried to not get lost in the branches 😄

I can also help with the localization when we'll have the tools.

from guide.

Reading this and talking to @stubailo I think we are getting confused about two different concept of "version":

1. Versions of the framework (e.g. 1.2 vs 1.3)
2. Versions of the guides.

Certainly it seems useful to have branches for each framework version (within reason) and permalinks for the latest guide for each framework version.

Also there's utility in being able to host in-development guides and PRs, which is basically like a CI deploy of the guide. These wouldn't be linked to publicly however.

What is unclear to us is if there's value in also having permalinked guide versions. So say for instance there was 1.2 routing guide that was based on IR, and we decided, no let's rewrite it with FR, do we want to keep a permalink to the 1.2 IR routing guide around?

One workaround for this is to just make such drastic changes with framework changes but the problems I see with this are:

1. We are trying to get less monolithic and dependent on framework changes, not more.
2. Packages we depend on and reference are going to change much more frequently than releases
3. If we'd decided FR was the way to go for Meteor is there any reason why we wouldn't want to say that for people on 1.2, and just for people on 1.3?
4. Is that super-confusing for people?

The biggest issue with permalinks to guide versions is an even greater maintenance burden (do we keep the 1.2/IR guide up to date with changes in IR, even though we don't recommend it anymore?).

Recommendation

I think for now we just go one public guide per-Meteor version, starting at 1.2.

As a stretch goal let's figure out a CI system that builds guides off every commit of the repo, but not link to them publicly anywhere.

If the IR/FR transition-type situation above comes up and it's a huge disaster, let's revisit.

from guide.

We are trying to get less monolithic and dependent on framework changes, not more.

I actually think updating the guide with major Meteor releases can be an interesting way of hitting the happy medium between a monolithic single platform and a bunch of independent packages. Imagine a world where a major new Meteor release basically === a new version of the guide. So we could be releasing new stuff all the time with people trying it (like we do now with pre-releases) and then the big announcement drops when we update the guide to make the new stuff the official way to do it.

I don't know if this actually makes sense, but it's an idea. I agree with your recommendation to start with.

from guide.

That's an interesting thought. I like it
On Wed, 7 Oct 2015 at 4:01 PM, Sashko Stubailo [email protected]
wrote:

We are trying to get less monolithic and dependent on framework changes,
not more.

I actually think updating the guide with major Meteor releases can be an
interesting way of hitting the happy medium between a monolithic single
platform and a bunch of independent packages. Imagine a world where a major
new Meteor release basically === a new version of the guide. So we could
be releasing new stuff all the time with people trying it (like we do now
with pre-releases) and then the big announcement drops when we update the
guide to make the new stuff the official way to do it.

I don't know if this actually makes sense, but it's an idea. I agree with
your recommendation to start with.

—
Reply to this email directly or view it on GitHub
#7 (comment).

from guide.

+1

from guide.