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

[Towards 1.0] Handling deprecation #766

Closed
SBoudrias opened this Issue Feb 27, 2015 · 27 comments

Comments

Projects
None yet
10 participants
@SBoudrias
Member

SBoudrias commented Feb 27, 2015

The issue

We've been pretty careful in every yeoman-generator release to stay as backward compatible as possible.

This mean through the months (even years now), legacy features have build up in our code core. I think it would be irresponsible from us to remove all of these features in one go with a 1.0.0 release. There would be a lot of deprecation all at once, and it might discourage users from upgrading their generators (ugh ugh python 3).

Considering this, I'm wondering what would be the most efficient way to slowly start deprecating features and help generator authors upgrade to latest versions?

Proposed solution

Would it make sense to start slowly pushing minor version updates (as we're pre 1.0) where we start deprecating legacy features. We could remove one legacy feature per release, maybe at a pace of 1 release every 2 weeks.

The issue with this solution is that bug fixes happening on releases past 0.18 will be harder to integrate into generators as upgrading yeoman-generator might require code changes. Is this really an issue though? We haven't receive any serious bug report since the last 0.18 patch release.

Deprecation list

  • file-utils contexts (this.src, this.dest)
  • wiring mixin
  • invoke and hookFor
  • actions/actions mixin (this is a major part though, we should probably just façade the less magical mem-fs-editor raw interface and remove any template handling weirdness from the file related methods)
  • NamedBase constructor (it's so simple we could keep it, but frankly it's a bit useless IMO)
  • actions/string mixin
  • this._
  • actions/file mixin
  • a bunch of assertions and test methods (most of them have logged deprecation warning for a while, we'd be safe to remove them)

Let me know if you feel anything is missing here!

I'm not sure if we should add remote and fetch utilities to this list? Is there any task they solve that cannot be accomplished using npm?

Please leave feedback

I'd really like to hear the opinion of maintainers of some major generators (ng-fullstack, mean, java-hipster, etc) who're not part of the core yeoman team.

Thanks for reading up to here!

@sindresorhus

This comment has been minimized.

Show comment
Hide comment
@sindresorhus

sindresorhus Feb 27, 2015

Member

Would it make sense to start slowly pushing minor version updates (as we're pre 1.0) where we start deprecating legacy features. We could remove one legacy feature per release, maybe at a pace of 1 release every 2 weeks.

I think that makes sense as long as we're transparent about it and do blog posts about how to migrate.

Is there any task they solve that cannot be accomplished using npm?

Nope. We have way too much cruft in the API that could just be require'able modules.

I'd really like to hear the opinion of maintainers of some major generators (ng-fullstack, mean, java-hipster, etc) who're not part of the core yeoman team.

@SBoudrias Can you mention the relevant people?

Sidenote: The result of this discussion should be put into a blog post on yeoman.io.

Member

sindresorhus commented Feb 27, 2015

Would it make sense to start slowly pushing minor version updates (as we're pre 1.0) where we start deprecating legacy features. We could remove one legacy feature per release, maybe at a pace of 1 release every 2 weeks.

I think that makes sense as long as we're transparent about it and do blog posts about how to migrate.

Is there any task they solve that cannot be accomplished using npm?

Nope. We have way too much cruft in the API that could just be require'able modules.

I'd really like to hear the opinion of maintainers of some major generators (ng-fullstack, mean, java-hipster, etc) who're not part of the core yeoman team.

@SBoudrias Can you mention the relevant people?

Sidenote: The result of this discussion should be put into a blog post on yeoman.io.

@SBoudrias

This comment has been minimized.

Show comment
Hide comment
@SBoudrias

SBoudrias Feb 27, 2015

Member

cc'ing people this might interest @DaftMonk @jdubois @jmirc @LeovR @jrcryer @Swiip @zckrs @diegonetto @wesleytodd @robwierzbowski @seratch @Snugug @mrichard

Oh man, starting to feel like I'm a spam bot - so sorry!

Member

SBoudrias commented Feb 27, 2015

cc'ing people this might interest @DaftMonk @jdubois @jmirc @LeovR @jrcryer @Swiip @zckrs @diegonetto @wesleytodd @robwierzbowski @seratch @Snugug @mrichard

Oh man, starting to feel like I'm a spam bot - so sorry!

@jdubois

This comment has been minimized.

Show comment
Hide comment
@jdubois

jdubois Feb 27, 2015

Thanks @SBoudrias !
Of course you need to deprecate stuff, no problem with that!
However, I must admit I have no idea which APIs we use, and where... In Java that would be easy to spot, but in JavaScript I'm lost (does JavaScript suck, or do I suck at JavaScript??). Maybe you could add some logging on top of each method that will be deprecated -> something like "warning, this is a deprecated method", so that when we run the generator we see straight away if there are some issues?

jdubois commented Feb 27, 2015

Thanks @SBoudrias !
Of course you need to deprecate stuff, no problem with that!
However, I must admit I have no idea which APIs we use, and where... In Java that would be easy to spot, but in JavaScript I'm lost (does JavaScript suck, or do I suck at JavaScript??). Maybe you could add some logging on top of each method that will be deprecated -> something like "warning, this is a deprecated method", so that when we run the generator we see straight away if there are some issues?

@sindresorhus

This comment has been minimized.

Show comment
Hide comment
@sindresorhus

sindresorhus Feb 27, 2015

Member

@jdubois Yes, that's a good idea, we'll do that whenever possible.

Member

sindresorhus commented Feb 27, 2015

@jdubois Yes, that's a good idea, we'll do that whenever possible.

@zckrs

This comment has been minimized.

Show comment
Hide comment
@zckrs

zckrs Feb 27, 2015

Thanks for mention.
No problem with deprecate 😃
Totally agree for a warning log before to remove a method.

Your "Deprecation list" is complete ? should evolve ?

Anyway we stand ready to receive releases.

zckrs commented Feb 27, 2015

Thanks for mention.
No problem with deprecate 😃
Totally agree for a warning log before to remove a method.

Your "Deprecation list" is complete ? should evolve ?

Anyway we stand ready to receive releases.

@Swiip

This comment has been minimized.

Show comment
Hide comment
@Swiip

Swiip Feb 27, 2015

I remember the switch from the generator 0.17 to 0.18, it was not transparent (something about the paths in the new file system helper). As it's our main dependency I don't consider being able to change the version without worrying a bit about the impacts.

So, I don't mind if there is a lot of deprecations in a new version, especially if there is some sort of documentations helping the migration, even more if it's a major version. I would just plan a task of migration. In fact, I even prefer a big cleanup of the API better than having to fix things every two weeks.

Also, like @jdubois, whenever it's possible, I like the idea of a warning log.

To be honest, I prepare myself for the release of Gulp 4 which will be a lot harder to deal with, I think :)

Swiip commented Feb 27, 2015

I remember the switch from the generator 0.17 to 0.18, it was not transparent (something about the paths in the new file system helper). As it's our main dependency I don't consider being able to change the version without worrying a bit about the impacts.

So, I don't mind if there is a lot of deprecations in a new version, especially if there is some sort of documentations helping the migration, even more if it's a major version. I would just plan a task of migration. In fact, I even prefer a big cleanup of the API better than having to fix things every two weeks.

Also, like @jdubois, whenever it's possible, I like the idea of a warning log.

To be honest, I prepare myself for the release of Gulp 4 which will be a lot harder to deal with, I think :)

@wesleytodd

This comment has been minimized.

Show comment
Hide comment
@wesleytodd

wesleytodd Feb 27, 2015

Contributor

Thanks for looping me in. I am also going to ping a contributor who has been adding a lot to the wordpress generator @Toddses.

A ton of issues that get filed on my generator are for warning messages that beginning users don't understand. So having depreciation messages in the main-line branch is going to generate a bunch of pointless GitHub issues. Maybe we could start with a --development-warnings flag or something to enable them. At least for the current major version branch.

Secondly, I agree with @jdubois that I am not entirely sure which of that list we are using. I have recently found the documentation to be difficult to follow. JSDoc makes some seriously weird structure on their generated output. We tried at my company to wrangle that beast and have mostly given up. So I understand the plight, but still cannot determine for sure which we are using.

Thirdly, and related to the "secondly", documentation on the migration would be greatly helpful. When @Toddses updated the generator to 0.18 I really had no insights into the change. Just like @Swiip said. So it would really be helpful to have a clear explanation as to what features are deprecated and what should take their place. Preferably with examples :)

Contributor

wesleytodd commented Feb 27, 2015

Thanks for looping me in. I am also going to ping a contributor who has been adding a lot to the wordpress generator @Toddses.

A ton of issues that get filed on my generator are for warning messages that beginning users don't understand. So having depreciation messages in the main-line branch is going to generate a bunch of pointless GitHub issues. Maybe we could start with a --development-warnings flag or something to enable them. At least for the current major version branch.

Secondly, I agree with @jdubois that I am not entirely sure which of that list we are using. I have recently found the documentation to be difficult to follow. JSDoc makes some seriously weird structure on their generated output. We tried at my company to wrangle that beast and have mostly given up. So I understand the plight, but still cannot determine for sure which we are using.

Thirdly, and related to the "secondly", documentation on the migration would be greatly helpful. When @Toddses updated the generator to 0.18 I really had no insights into the change. Just like @Swiip said. So it would really be helpful to have a clear explanation as to what features are deprecated and what should take their place. Preferably with examples :)

@eddiemonge

This comment has been minimized.

Show comment
Hide comment
@eddiemonge

eddiemonge Mar 2, 2015

Member

Some of us from core could make ourselves available from time to time to help with the migrations as well to ease the transition.

Member

eddiemonge commented Mar 2, 2015

Some of us from core could make ourselves available from time to time to help with the migrations as well to ease the transition.

SBoudrias referenced this issue Mar 26, 2015

Removing functionnality allowing env to pass a template engine
Rationale: Template engine are only related to the generator itself. The
environment shouldn't have any control on it (it just doesn't make
sense)
@SBoudrias

This comment has been minimized.

Show comment
Hide comment
@SBoudrias

SBoudrias Apr 5, 2015

Member

First deprecation release https://github.com/yeoman/generator/releases/tag/v0.19.0

All deprecated methods will log a message to the console and should work just as before. (Exception: this.src and this.dest won't work, but will log a warning to the console).

Member

SBoudrias commented Apr 5, 2015

First deprecation release https://github.com/yeoman/generator/releases/tag/v0.19.0

All deprecated methods will log a message to the console and should work just as before. (Exception: this.src and this.dest won't work, but will log a warning to the console).

@addyosmani

This comment has been minimized.

Show comment
Hide comment
@addyosmani

addyosmani Apr 5, 2015

Member

Thanks for driving the move towards trimming and cleaning up the codebase, Simon. I agree with Sindre that in general this all sounds fine as long as we're being transparent about what is being deprecated and this indeed seems to be the case with the first deprecation release.

Perhaps my only suggestion here is it might be useful to publish a deprecation roadmap so it's clear to authors when features may no longer be available to them. As with any API deprecations, providing guidance around the replacement "way to do things" is probably also appreciated by authors.

Member

addyosmani commented Apr 5, 2015

Thanks for driving the move towards trimming and cleaning up the codebase, Simon. I agree with Sindre that in general this all sounds fine as long as we're being transparent about what is being deprecated and this indeed seems to be the case with the first deprecation release.

Perhaps my only suggestion here is it might be useful to publish a deprecation roadmap so it's clear to authors when features may no longer be available to them. As with any API deprecations, providing guidance around the replacement "way to do things" is probably also appreciated by authors.

@zenorocha

This comment has been minimized.

Show comment
Hide comment
@zenorocha

zenorocha Apr 6, 2015

Member

Just noticed that withPrompt has been removed in favor of withPrompts. I think these kind of test helpers should also be listed here since I had to look over the commit history to find this change.

1c05544

/cc @SBoudrias

Member

zenorocha commented Apr 6, 2015

Just noticed that withPrompt has been removed in favor of withPrompts. I think these kind of test helpers should also be listed here since I had to look over the commit history to find this change.

1c05544

/cc @SBoudrias

@jdubois

This comment has been minimized.

Show comment
Hide comment
@jdubois

jdubois Apr 6, 2015

@SBoudrias

I have an error (not just deprecation warning, it fails) with:

(!) #_ is deprecated. Require your own version of Lodash or underscore.string

-> I'm doing a "require" on underscore.string and it doesn't work, but I'm really a beginner on this... Do you have any working example? I tried to copy on generator-angular, but I'm not sure it uses the new API.

jdubois commented Apr 6, 2015

@SBoudrias

I have an error (not just deprecation warning, it fails) with:

(!) #_ is deprecated. Require your own version of Lodash or underscore.string

-> I'm doing a "require" on underscore.string and it doesn't work, but I'm really a beginner on this... Do you have any working example? I tried to copy on generator-angular, but I'm not sure it uses the new API.

@zenorocha

This comment has been minimized.

Show comment
Hide comment
@zenorocha

zenorocha Apr 6, 2015

Member

@jdubois remember to remove this once you import your own version of lodash, which means _. instead of this._.

Member

zenorocha commented Apr 6, 2015

@jdubois remember to remove this once you import your own version of lodash, which means _. instead of this._.

@SBoudrias

This comment has been minimized.

Show comment
Hide comment
@SBoudrias

SBoudrias Apr 6, 2015

Member

@jdubois @zenorocha have the first part. Also FWIW, lodash now provide String utilities, so underscore.string might not even be necessary for your use case.

A tricky thing about _ I found while updating one of our core generator is that it is often abused in templates files. this.template make the generator instance the context of each templates, which make it very hard to fix.

IMO the solution is to stay away from this.template (or this.copy if used for templating) and move to the new file system helpers: this.fs.copyTpl(). With this method you manually pass the data you want in a template which make it very easy to search and debug.

If you want an example, check the update commit made to generator-generator

Member

SBoudrias commented Apr 6, 2015

@jdubois @zenorocha have the first part. Also FWIW, lodash now provide String utilities, so underscore.string might not even be necessary for your use case.

A tricky thing about _ I found while updating one of our core generator is that it is often abused in templates files. this.template make the generator instance the context of each templates, which make it very hard to fix.

IMO the solution is to stay away from this.template (or this.copy if used for templating) and move to the new file system helpers: this.fs.copyTpl(). With this method you manually pass the data you want in a template which make it very easy to search and debug.

If you want an example, check the update commit made to generator-generator

@jdubois

This comment has been minimized.

Show comment
Hide comment
@jdubois

jdubois Apr 7, 2015

Thanks @zenorocha but I'm already using _.
@SBoudrias I am indeed abusing this, and it's awful to debug. However I have so many templates, this is going to be hard to migrate!!!

jdubois commented Apr 7, 2015

Thanks @zenorocha but I'm already using _.
@SBoudrias I am indeed abusing this, and it's awful to debug. However I have so many templates, this is going to be hard to migrate!!!

@jdubois

This comment has been minimized.

Show comment
Hide comment
@jdubois

jdubois Apr 7, 2015

@SBoudrias OK this is working, but now I have to pass all parameters as arguments, and not use _. inside my template, but I have something like 300 templates... Can't we have a way to make it work as before?

jdubois commented Apr 7, 2015

@SBoudrias OK this is working, but now I have to pass all parameters as arguments, and not use _. inside my template, but I have something like 300 templates... Can't we have a way to make it work as before?

@SBoudrias

This comment has been minimized.

Show comment
Hide comment
@SBoudrias

SBoudrias Apr 7, 2015

Member

@jdubois yes, you can manually do this._ = _ in your constructor.

Member

SBoudrias commented Apr 7, 2015

@jdubois yes, you can manually do this._ = _ in your constructor.

@sondr3

This comment has been minimized.

Show comment
Hide comment
@sondr3

sondr3 Apr 15, 2015

Just throwing my two cents into the fold here, would it be possible to have an example generator (maybe even generator-generator) where with each release you update it to follow best practices and remove/update deprecated features and such so you can actually look at the changes and such. This is mostly how I've been able to piece together how things work and it would be neat to have a up-to-date simple place to look for how to do things properly.

sondr3 commented Apr 15, 2015

Just throwing my two cents into the fold here, would it be possible to have an example generator (maybe even generator-generator) where with each release you update it to follow best practices and remove/update deprecated features and such so you can actually look at the changes and such. This is mostly how I've been able to piece together how things work and it would be neat to have a up-to-date simple place to look for how to do things properly.

@SBoudrias

This comment has been minimized.

Show comment
Hide comment
@SBoudrias

SBoudrias Apr 15, 2015

Member

Hey @sondr3, we actually did update generator-generator to 0.19. You can see the update diff here: yeoman/generator-generator@f2a2aab

It is not our most complex generator, so it might not cover every case, but it's a place to start. We're in the process of updating generator-node currently.

Member

SBoudrias commented Apr 15, 2015

Hey @sondr3, we actually did update generator-generator to 0.19. You can see the update diff here: yeoman/generator-generator@f2a2aab

It is not our most complex generator, so it might not cover every case, but it's a place to start. We're in the process of updating generator-node currently.

@sondr3

This comment has been minimized.

Show comment
Hide comment
@sondr3

sondr3 Apr 15, 2015

Whelp, I thought I looked hard enough, thanks! I'll take a look.

sondr3 commented Apr 15, 2015

Whelp, I thought I looked hard enough, thanks! I'll take a look.

@markusfalk markusfalk referenced this issue Apr 15, 2015

Closed

templating #123

mischah added a commit to micromata/generator-baumeister that referenced this issue Apr 20, 2015

Downgrade yeoman-generator for now
Because 0.19.x gets rid `this._` which is heavily used throughout the templates.
See: yeoman/generator#766

Update and refactoring will happen with the next release.

sebastienrousseau added a commit to reedia/generator-avionic that referenced this issue May 15, 2015

Updating configuration files
1) Fixing some bugs related to yeoman-generator handling deprecation (yeoman/generator#766)

Signed-off-by: Sebastien Rousseau <sebastien.rousseau@mac.com>
@jdubois

This comment has been minimized.

Show comment
Hide comment
@jdubois

jdubois May 29, 2015

I got it working, using yeoman-generator 0.20.1

Excepted from the annoying issue I mentioned earlier, no problem at all. Not even one deprecation warning!! @SBoudrias did you deprecate a lot of things? Or is it me just using a small part of the generator?

jdubois commented May 29, 2015

I got it working, using yeoman-generator 0.20.1

Excepted from the annoying issue I mentioned earlier, no problem at all. Not even one deprecation warning!! @SBoudrias did you deprecate a lot of things? Or is it me just using a small part of the generator?

@jdubois

This comment has been minimized.

Show comment
Hide comment
@jdubois

jdubois May 29, 2015

Sorry, I see all the warnings now!!! Hell, lots of work!

jdubois commented May 29, 2015

Sorry, I see all the warnings now!!! Hell, lots of work!

@SBoudrias

This comment has been minimized.

Show comment
Hide comment
@SBoudrias

SBoudrias May 29, 2015

Member

@jdubois can you explain why you couldn't see the warnings? It might be helpful if other people also run into this issue.

Member

SBoudrias commented May 29, 2015

@jdubois can you explain why you couldn't see the warnings? It might be helpful if other people also run into this issue.

@jdubois

This comment has been minimized.

Show comment
Hide comment
@jdubois

jdubois May 30, 2015

@SBoudrias it's just that I forgot to do a "npm link" to fetch the new dependencies. Usually I don't touch them, so my code is always at the right version without doing it.

jdubois commented May 30, 2015

@SBoudrias it's just that I forgot to do a "npm link" to fetch the new dependencies. Usually I don't touch them, so my code is always at the right version without doing it.

@jdubois

This comment has been minimized.

Show comment
Hide comment
@jdubois

jdubois Jun 2, 2015

@SBoudrias I still have one issue left, with a method that is not behaving like it used to do. I opened up a Stackoverflow question about it, if you can help me it would be greatly appreciated, as I'm really stucked.

jdubois commented Jun 2, 2015

@SBoudrias I still have one issue left, with a method that is not behaving like it used to do. I opened up a Stackoverflow question about it, if you can help me it would be greatly appreciated, as I'm really stucked.

@SBoudrias

This comment has been minimized.

Show comment
Hide comment
@SBoudrias

SBoudrias Dec 8, 2016

Member

Hey everyone, today I published the beta v1.0.0-rc1 that'll hopefully become our first v1.

We've been documenting the changes in a blog post and updated documentation. We'll publish these resource on yeoman.io as soon as we have a stable 1.0

Let us know what you think and how 1.0 works for you!

Member

SBoudrias commented Dec 8, 2016

Hey everyone, today I published the beta v1.0.0-rc1 that'll hopefully become our first v1.

We've been documenting the changes in a blog post and updated documentation. We'll publish these resource on yeoman.io as soon as we have a stable 1.0

Let us know what you think and how 1.0 works for you!

@SBoudrias

This comment has been minimized.

Show comment
Hide comment
@SBoudrias

SBoudrias Dec 17, 2016

Member

Full 1.0 is out today. Open issues if you ran into any problems updating.

Member

SBoudrias commented Dec 17, 2016

Full 1.0 is out today. Open issues if you ran into any problems updating.

@SBoudrias SBoudrias closed this Dec 17, 2016

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