Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
[Towards 1.0] Handling deprecation #766
We've been pretty careful in every
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?
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.
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!
I think that makes sense as long as we're transparent about it and do blog posts about how to migrate.
Nope. We have way too much cruft in the API that could just be require'able modules.
@SBoudrias Can you mention the relevant people?
Sidenote: The result of this discussion should be put into a blog post on yeoman.io.
Thanks @SBoudrias !
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 :)
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
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 :)
Mar 26, 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:
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.
referenced this issue
Apr 6, 2015
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.
A tricky thing about
IMO the solution is to stay away from
If you want an example, check the update commit made to generator-generator
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.