The future of ng-annotate

Question

The future of ng-annotate

olov opened this issue 8 years ago · comments

I have maintained ng-annotate for almost three years now and I think it's now time for me to either pass the maintainer bit forward or to declare ng-annotate feature complete, disabling implicit matching.

I created ng-annotate because it seemed tedious and error-prone to keep two parameter-lists in sync. At the time most angular-applications had similar enough structure that detecting functions to annotate automagically seemed like a good idea. But as angular progressed and its community grew, the slope became more and more slippery. I eventually added support for explicitly marking up which functions to annotate (first via /*@ngInject*/, then via "ngInject") but regrettably to late. The automagic expectation still remains, as reflected in the issue tracker. Please note that "ngInject" works great in practice - it takes a couple of seconds to type it in, you don't need to keep two parameter lists in sync and it's crystal clear which parts of your code will be transformed and which won't.

Which brings us to TypeScript and ES2015+ support. With "ngInject" markup it works fine as long as ng-annotate is fed with the tsc/babel/.. processed output. With implicit matching it's a whole different beast on top of the already slippery automagic-slope. I've consistently said no to adding ES2015+ support for this reason, and there are lingering pull requests and issues (mostly feature requests).

I see two paths forward (are there other options?):

I will ship a vastly simplified ng-annotate 2.0, supporting explicit "ngInject" matching only. It will be (mostly) feature frozen but bugs will be fixed. An unimportant but still nice side effect would be that ng-annotate becomes even faster.
I pass it along. The new maintainer(s) can revisit my decision to not support unprocessed ES2015+ input and how far to further slip down the implicit slope.

Thoughts on this? I'm interested in hearing from users, current and future contributors and from anyone interested in taking on the maintainer role.

Martin Olsansky · Answer 1 · Wed Jun 08 2016 21:50:35 GMT+0800 (China Standard Time)

@olov First of all thanks for keeping us up to date

I like path 1

Michał Gołębiowski-Owczarek · Answer 2 · Wed Jun 08 2016 21:55:42 GMT+0800 (China Standard Time)

I like the first option - very reliable, less surprises.

All that'd need to happen going forward is to support new ECMAScript features where needed - for now injecting arrow functions & ES6 classes.

Jeremy PELE · Answer 3 · Wed Jun 08 2016 21:57:18 GMT+0800 (China Standard Time)

@olov Thanks for the feedback. I would go for the 1st option.

Besides, it doesn't prevent anyone to fork this repo and support ES6.

c-vetter · Answer 4 · Thu Jun 09 2016 05:18:50 GMT+0800 (China Standard Time)

@olov I agree with the others, option 1 is the way to go. as Jeremy says, there's nothing stopping anyone from going forward anyway.

On the point of the slippery slope: I've found myself in situations where I wasn't sure if I could leave out the explicit annotation, and as with other instances of erring on the sides of consistency and clarity, I was on the path to annotating everything anyway. After all, even if I knew exactly when an un-annotated function would be injected and when not, why keep those guessing who come after me? Just my two cents 👍

Oh, and thank you for ng-annotate 😄

Matthieu Sieben · Answer 5 · Thu Jun 09 2016 14:06:28 GMT+0800 (China Standard Time)

Go for option 1! As long as #220 is included

Victor Perron · Answer 6 · Fri Jun 10 2016 17:56:20 GMT+0800 (China Standard Time)

Option 1. Unprocessed ES6 shouldn't be supported in my opinion. Use toolchains, dudes.

Michał Gołębiowski-Owczarek · Answer 7 · Fri Jun 10 2016 18:20:17 GMT+0800 (China Standard Time)

Unprocessed ES6 shouldn't be supported in my opinion. Use toolchains, dudes.

Why? There are lots of ES6-compatible environments now and not every project has to support IE. Also, it's perfectly fine to want to run your code in ES6 mode during development for easier debugging and having ng-annotate work there would help a lot.

Requiring transpiling ES6 to ES5 in all cases decreases usefulness of ES6 a lot.

Paweł Grabarz · Answer 8 · Mon Jun 27 2016 20:49:00 GMT+0800 (China Standard Time)

If we go with option 1, it would be possible and probably quite easy to implement ng-annotate functionality not as a standalone tool, but as a babel 6 plugin. That way it would stay compatible with any toolchain and would support ES6 out of the box.

valerio · Answer 9 · Sat Jul 02 2016 08:58:55 GMT+0800 (China Standard Time)

I would go for 2.
It seems you don't have time even to merge valid PRs, and besides, maintainers could also help towards the "simple" options.
It's not an exclusive path.

Andrew Schmadel · Answer 10 · Wed Jul 20 2016 22:47:08 GMT+0800 (China Standard Time)

I've been maintaining a fork of ng-annotate that reimagines this project as a babel plugin instead of a standalone tool.

Currently, the plugin passes ng-annotate's test suite, supports ES6 sources (and annotating things like class constructors), and works with implicit annotations.

Additionally, as a Babel plugin, we get to take advantage of Babel's fairly robust parser (with support for modern language features) and suite of transformation tools. Developers who are already using Babel should also see significant performance improvements over ng-annotate, as the sources only need to be parsed once. (Even with implicit matching, the plugin does not appear to add much overhead beyond the work already being done by the parser.)

Regardless of ng-annotate's future, I intend to maintain my fork. If we feel that it's OK for ng-annotate to live on as a Babel plugin, we could treat my fork as a successor to this project.

(PS. Huge thanks to @olov for all of the work he's done over the years on ng-annotate!)

Michał Gołębiowski-Owczarek · Answer 11 · Thu Jul 21 2016 05:00:33 GMT+0800 (China Standard Time)

@schmod Very interesting! Does it support options? The ideal setup for me is to:

Always use 'ngInject';
Disable any possible heuristic that the plugin has and rely only on the 'ngInject'; pragma.
Have support for ES6 classes & arrow functions in the following way:

class Circle {
    constructor(service1, service2) {
        'ngInject';
        /* code */
    }
    method(param1, param2) {
        /* code */
    }
}

angular
    .module('myModule')
    .component('myCircle', {
        template: '...',
        controller: CircleController,
    })
    .run((service1, service2) => {
        'ngInject';
        /* code */
    });

Is that possible to achieve with your plugin?

Andrew Schmadel · Answer 12 · Tue Jul 26 2016 02:44:08 GMT+0800 (China Standard Time)

Right now, there isn't a configuration option to disable implicit matches, but it should be fairly straightforward to implement. I'll put that on the roadmap.

2, 3. I just pushed a new release that supports arrow functions and prologue annotations in class constructors.

Andrew Schmadel · Answer 13 · Tue Jul 26 2016 07:44:01 GMT+0800 (China Standard Time)

Actually, explicit-only matching turned out to be really easy to implement, and is now released in v0.4.0 of babel-plugin-angularjs-annotate.

Olov Lassus · Answer 14 · Wed Jul 27 2016 15:04:02 GMT+0800 (China Standard Time)

@schmod that sounds awesome!

I haven't yet tried babel-plugin-angularjs-annotate, but based on reading the README these are the changes that I'd make:

Delete implicit matching stuff. If not, make it opt-in rather than opt-out. Deleting would be better, for a bunch of reasons.
As a consequence of 1, delete all implicit matching stuff in the README (or move to a separate document).
Guide users to "ngInject" whenever possible because comments are brittle. var x = /* @ngInject */ ($scope) => { ... }; becomes var x = ($scope) => { "ngInject"; .. };. It should be easy to let babel-plugin-angularjs-annotate strip away the prologue string to prepare for optimal minification.

Just my opinions but I think it would make life easier for developers and users alike. :-)

Andrew Schmadel · Answer 15 · Sat Jul 30 2016 04:52:53 GMT+0800 (China Standard Time)

I avoided copying the entirety of ng-annotate's README for reasons that I no longer remember.

If the Babel plugin is indeed the future of ng-annotate, I should indeed aim to provide comprehensive documentation, rather than directing new users to ng-annotate's README.

Some other thoughts:

Why is implicit matching so problematic? Are there major known issues? I understand that it's not reliable in 100% of situations, but it's generally been pretty solid for me.
Ditto for comments. Are there specific transformations that are known to mangle comments, but leave prologue directives intact?
With the above things in mind, I think that it might be a good idea to have a "strict" mode that looks for implicit matches, and prints a warning (or error) if they haven't been explicitly marked for annotation. [Yes, this functionality probably belongs in a linter.]

Andrew Schmadel · Answer 16 · Sat Jul 30 2016 05:04:36 GMT+0800 (China Standard Time)

Another possibility: A special mode that does implicit matches, and then adds prologue directives to those functions (instead of adding the actual $inject annotations), while stripping out existing comment-based /* @ngInject */ hints and explicit $inject annotations.

This could be useful for preparing existing code to use our recommended "best practices."

Michał Gołębiowski-Owczarek · Answer 17 · Sat Jul 30 2016 23:39:30 GMT+0800 (China Standard Time)

@schmod I've just switched one of my projects to your plugin and it worked like a charm in my ES6-based code. I no longer have to disable strictDi in the development ES6 server mode. Thanks!

c-vetter · Answer 18 · Sun Jul 31 2016 03:07:48 GMT+0800 (China Standard Time)

@schmod

Why is implicit matching so problematic? Are there major known issues? I understand that it's not reliable in 100% of situations, but it's generally been pretty solid for me.

From a user's point of view, I consider it a best practice to have every occurrence explicit. The main reasons being that this

removes the author's need to distinguish cases where implicit matching works versus those where it doesn't
helps the reader's understanding of what's happening

Of course, there will be authors like yourself, as well as myself at an earlier time, who will like the implicit matching and have no issues. However, since you will need to use explicit annotations anyway as soon as implicit matching fails you and implicit matching greatly increases the code's complexity, I think the cost probably outweighs the benefits.

Andrew Schmadel · Answer 19 · Tue Aug 02 2016 01:18:53 GMT+0800 (China Standard Time)

I've been stuck on 1.2.28 for so long that I keep forgetting that strictDi exists.

strictDi mitigates most of the risks of explicit-only annotations (ie. that you've forgotten an "ngInject" somewhere and won't discover it until you test a minified build).

I think it's reasonable for us to recommend explicit annotations and strictDi for new users.

Olov Lassus · Answer 20 · Tue Aug 02 2016 01:40:08 GMT+0800 (China Standard Time)

Implicit matching is problematic because a) it's a never-ending story and b) false positives (breaking code). see the ng-annotate issue tracker for lots of more info. :)
Comments are problematic because of rewriting tools shuffling them around (see issue tracker here too). That's why I came up with "ngInject" in the first place (and yes most proper source rewriters respect prologues).
I have no problem with a strict mode. :)

My comments are just meant as advice based on my experience of maintaining ng-annotate, so don't feel any pressure of doing this or that to please me.

I think your Babel plugin is indeed the future of ng-annotate. @mgol since we had discussions about a Babel plugin not long ago, I'd like to hear whether you'd be happy with this too?

Andrew Schmadel · Answer 21 · Tue Aug 02 2016 03:57:49 GMT+0800 (China Standard Time)

As I've mentioned, I'm in favor of leaving implicit matching in place for the time being.

However, you've convinced me that 1.0.0 (ie. the first release I'll make with breaking changes) should turn of implicit matching by default, and the docs should clearly emphasize explicit annotations and prologue directives as the preferred way of doing things.

I like this because it makes the documentation really straightforward:

Usage

tl;dr;

Add 'ngInject'; to the top of any function body that will be invoked with Angular's DI injector. That's it.

angular.module('myMod').service('mySvc', function($scope){
   'ngInject';
   $scope.foo = "bar";
});

angular.module('myMod').directive('myDir', (urlBase) => {
   'ngInject';
   return {
      restrict: 'E',
      controller: ($http) => {
          'ngInject';
          $http.get(urlBase + '/foo');
      }
   };
});

Andrew Schmadel · Answer 22 · Tue Aug 02 2016 03:59:38 GMT+0800 (China Standard Time)

There's also another babel plugin that seems like it's being developed in parallel:
https://github.com/marcioj/babel-plugin-angular-annotate

Michał Gołębiowski-Owczarek · Answer 23 · Wed Aug 03 2016 20:40:44 GMT+0800 (China Standard Time)

@mgol since we had discussions about a Babel plugin not long ago, I'd like to hear whether you'd be happy with this too?

Yup, I'm happy with the plugin!

There's also another babel plugin that seems like it's being developed in parallel:
https://github.com/marcioj/babel-plugin-angular-annotate

It seems it was created from scratch, though. And a large part of it is supporting specific "configurations" which are string representations of object property access paths which should have parameters annotated (like "$httpProvider.interceptors.push"). It also seems it doesn't support any explicit annotation style. So I definitely prefer your plugin.

Olov Lassus · Answer 24 · Thu Sep 15 2016 14:22:48 GMT+0800 (China Standard Time)

Alright, I think the timing is right to get this done now. @schmod what's the current status and how would you prefer to proceed with the migration? I'm thinking a prominent message at the top of the ng-annotate README that briefly explains that ng-annotate is now deprecated in favor of babel-plugin-angularjs-annotate, preferably with a link to a .md file on your repo that explains the easiest way to migrate (for existing ng-annotate users). The babel-plugin-angularjs-annotate README should also be updated to make it clear that it's the ng-annotate successor. If it's possible to disallow new issues on the ng-annotate github page then that will happen too. Anything else we need to do?

Andrew Schmadel · Answer 25 · Fri Sep 16 2016 21:48:00 GMT+0800 (China Standard Time)

I think the steps forward are:

Bump babel-plugin-angularjs-annotate to 1.0.0 and turn implicit matching off by default
Write a migration guide, and update README.md to reflect that we're considering the new project to be "stable" -- I'd like to PR this and ask a few of you to look it over before I merge it.
Update ng-annotate's README.md to point new users to the Babel plugin.

I might have some time for this in the coming week. Apologies that I've been busy lately.

Andrew Schmadel · Answer 26 · Thu Sep 29 2016 06:03:57 GMT+0800 (China Standard Time)

I've taken a stab at updating the documentation for babel-plugin-angularjs-annotate in preparation for the 1.0.0 release.

https://github.com/schmod/babel-plugin-angularjs-annotate/tree/next

Proofreading and improvements are welcome ;-)

Olov Lassus · Answer 27 · Sat Oct 01 2016 15:23:18 GMT+0800 (China Standard Time)

@schmod great - let me know when you're ready and I'll update the ng-annotate README with a deprecation notice and a link to your plugin. I'll also push a (final) release of ng-annotate to npm so that the updated README is there as well.

Sebastian Herrmann · Answer 28 · Fri Dec 09 2016 22:29:43 GMT+0800 (China Standard Time)

Thanks to much for the great work, @olov and @schmod! This is a prime example of how open-source software should happen. I'll gladly migrate my Angular projects to use the new babel plugin now and will let you know (in the new repo) if I run into any problems.
(Sorry if this is considered spam for some people who get mail notifications for this thread but I just wanted to express my gratitude.)

Michał Gołębiowski-Owczarek · Answer 29 · Fri Dec 09 2016 23:24:24 GMT+0800 (China Standard Time)

One thing to consider: in the typical Angular 2+ setup used via Angular CLI if you want to mix in Angular 1 components, you won't be able to use ng-annotate as the Babel plugin doesn't understand TypeScript. But the current ng-annotate doesn't understand TypeScript as well so this is not making matters worse.

Andrew Schmadel · Answer 30 · Sat Dec 10 2016 01:02:55 GMT+0800 (China Standard Time)

In that scenario, you'd probably want to opt for the TypeScript compiler to output ES6, and then run the output through babel to transpile to ES5. (Or, alternatively, there's nothing stopping you from running babel against ES5 sources)

Michał Gołębiowski-Owczarek · Answer 31 · Fri May 19 2017 19:17:53 GMT+0800 (China Standard Time)

@olov @schmod Can we proceed with the ng-annotate deprecation? I think the Babel plugin works really well right now and most people don't know ng-annotate is effectively deprecated and that they should move to the Babel plugin.

Olov Lassus · Answer 32 · Thu Jun 01 2017 22:20:57 GMT+0800 (China Standard Time)

It is done. Thanks everyone! I'm leaving this issue and #253 open for historical reasons.

Michał Gołębiowski-Owczarek · Answer 33 · Thu Jun 01 2017 23:25:23 GMT+0800 (China Standard Time)

@olov Can you run:

npm deprecate ng-annotate "My deprecation message"

so that people installing the package see the warning?

Andrew Schmadel · Answer 34 · Thu Jun 01 2017 23:52:00 GMT+0800 (China Standard Time)

I'll try to find time this week to update my repo to reflect ng-annotate's deprecation (and finally get 1.0 out the door)

Michał Gołębiowski-Owczarek · Answer 35 · Mon Jul 24 2017 01:40:19 GMT+0800 (China Standard Time)

@schmod Any updates? :)

Dashon 'DJ' Hawkins · Answer 36 · Thu Aug 24 2017 22:32:33 GMT+0800 (China Standard Time)

I really like and respect this community of commenters and in particular @schmod. I'm a newbie developer and was taught ES5 and now trying to transition into more functional programming in Javascript using ES6. I'm still have some minor difficulties wrapping my head around it. What @schmod has created is really great and I have been highly anticipating v1.0. Any word yet on a timeline? I would also like to contribute to any open source project based upon my beginner skill set. Any recommendations? I don't care how mundane or minor my role is. I just want to be more active in the community and grow and learn.

Alexey Sednev · Answer 37 · Thu Mar 15 2018 04:09:15 GMT+0800 (China Standard Time)

Here's a fork that has been patched to work with imports/exports in ES6: https://github.com/bluetech/ng-annotate-patched

Alexey Sednev · Answer 38 · Fri Mar 16 2018 00:52:56 GMT+0800 (China Standard Time)

There is another fork from nevcos that supports ngInject for ES6 classes. It's little behind bluetech fork but useful in own way.

Also, if you use ng-annotate with gulp, take a look at gulp-ng-annotate-patched

Jakub Freisler · Answer 39 · Tue Feb 19 2019 00:05:20 GMT+0800 (China Standard Time)

Actually, I've improved nevcos fork a little and everything got merged to ng-annotate-patched - feel free to use it with working support for ES6 classes.
BTW shouldn't ng-annotate-patched be mentioned in this library README file (and maybe npm deprecation message), so others can find it more easily?