1.x migration documentation inconsistent

[jesstelford]

While migrating a project from [email protected] to [email protected], I began by first following the documentation in the article Say Allo' To Yeoman-Generator 1.0:

Simpler default export

Previously the yeoman-generator package would expose a lot of unrelated functions.

It now only export the core Generator class:

const Generator = require('yeoman-generator');

export default class extends Generator {}

No more NamedBase and no more yeoman-environment factory (use
yeoman-environment directly for that).

To figure out how to use the new class extends Generator {} syntax, I jumped into the "Extending Generator" portion of the Getting Started tutorial, which goes on to say:

If you need to support ES5 environment, the static Generator.extend() method can be used to extend the base class and allow you to provide a new prototype.

So, I went looking for the documentation on this method, and ended up on the API Documentation page for Base, which has as an example:

var generator = require('yeoman-generator');
var MyGenerator = generator.Base.extend({
  writing: function() {
    this.fs.write('var foo = 1;', this.destinationPath('index.js'));
  }
});

... Which appears to be the 0.24.1 syntax that no longer works (Base is undefined), bringing me full-circle.

It would be great to fleshout the migration guide, update the getting started documentation to be clearer on how the new class can / can't be used (eg; what functions belong in the constructor, and what don't?), and updating the API documentation.

---

The correct syntax is:

var generator = require('yeoman-generator');
var MyGenerator = generator.extend({
  writing: function() {
    this.fs.write('var foo = 1;', this.destinationPath('index.js'));
  }
});

[addyosmani]

... Which appears to be the 0.24.1 syntax that no longer works (Base is undefined), bringing me full-circle.

Our apologies for what appears to be an oversight on our part. Thanks for filing an issue with the syntax workaround you noted.

It would be great to fleshout the migration guide, update the getting started documentation to be clearer on how the new class can / can't be used (eg; what functions belong in the constructor, and what don't?), and updating the API documentation.

This seems like a reasonable path forward to me. @SBoudrias was this an item already on your radar or something we could use some help with?

[SBoudrias]

Some version changes we made broke the API deploy script. So the documentation that was later fixed didn't made it to our website.

I should've - hopefully - fixed it now.

Had to do some git kungfu to reorder the ES6-ification from the codebase. People will need to reset when they pull.

[SBoudrias]

Should be okay now http://yeoman.io/generator/Base.html