Project documentation needs transparent commentary about core loading/bundling technologies, future road-map
dchennells opened this issue · comments
Angular-Seed (together with the project owner's excellent Switching to Angular, 3rd Ed.—Oct. 2017) have taught me much of what I've learned about this framework and ecosystem during the past several months and I'm grateful to the owner and community for their years of contributions that have brought this project to this stage.
That said, as I've learned much more about the current (i.e. 2019) ecosystem for Angular development and the core technologies in use here, I've belatedly realized that this project represents, above-all, a substantial technology bet on SystemJS over WebPack.
In light of the prestige and huge following of this project (nearly 5,000 stars), more effort needs to be made in the key ReadMe and wiki to make the core ("opinionated") technology choices clear on the tin, so as to assist users new to the framework in making the right investment of their time. Ideally, there should be a link to a blog article that rationalizes or justifies the continuing (or is it legacy?) commitment to SystemJS as a loader/bundler.
As it stands, the contents of our ReadMe and wiki do not assist newbies in making an informed choice.
As a minimum, we need to link to and engage with the material in the following resource to outline the use-cases in which we believe the core technologies in use in this seed are the right bet, for dev and prod, for new development in 2019, versus alternatives:
Comparison of module bundlers and loaders
The choices about technologies are not trivial. Anyone who has configured the project.config.ts in this seed to support angular material widgets; who has discovered the intricacies of configuring a (third party, babel) systemjs plugin-transpiler to make function an ostensibly "angular"-oriented project such as ng-circle-progress; or who has configured functioning lazy loading aligned with the current guidance in the angular docs for Lazy Loading Feature Modules will immediately understand the gravity of the choice for new users' and teams' efforts.
If this is a legacy project that still primarily reflects the scene ca. 2015, then we need:
- a road-map for transforming it to something that will vindicate the investments of new users just "switching" to Angular;
- mark it, up-front, as deprecated (not recommended in its current form for new development); or,
- champion a downstream fork that stands the best chance of providing a competitive/winning set of tools.
Because of the connection of this project to the project owner's books, there is no doubt that this project is attracting interest from general users relatively new to the ecosystem. We need to ensure that the top level messages for this project treat them responsibly, with the care and respect they deserve.
@dchennells thanks for putting this all together! For the past a couple of months I've been working on the Angular CLI, and this is the tool that I'd recommend to developers getting started with Angular.
I'll reflect this in the README and in the project's description.
Webpack is not the key advantage of the CLI, in fact, the CLI is independent of its build system. It's mostly the level of investment and the ability to make informative decisions. I started the seed project in the early days when Angular was still called Angular 2, and it was using AtScript. Back then, this was the only way for me to try Angular and to build the examples for my book "Switching to Angular."
Since 2015, Google grew an entire Angular tooling team that I joined last year. Some of us are working on both, the tooling and the framework side, which allows us to bend technologies in a way that it'll be most suitable for engineers to be productive with Angular. Although I feel the Angular Seed project still provides a solid foundation for building applications with the framework, it's development ergonomics is not comparable with the Angular CLI.
One of the main benefits of the Seed was the flexibility it provides - the entire build system is modular and extensible, that was a missing part in the CLI. In the new release of the CLI, however, we'll be introducing a new "Architect API" that will allow developers to add custom functionality to their build process.
Depending on the level of investment that you've put into tuning your development process it might or might not be worth it to migrate to the CLI. If most of the modifications that you did were in project.config.ts, then you should be able to almost seamlessly switch to the CLI by moving your source files and installing the missing dependencies.
If you're maintaining a lot of custom build scripts, there are two choices:
- Implement them as "custom builders" for Angular CLI to extend its pipeline
- Keep your project based on Angular seed and do not migrate to the CLI. As I mentioned above, the bundler is not critical - I'd strongly recommend you to use rollup.js, which is already part of the seed project
I hope Angular seed helped you to get started with Angular! Thank you for giving it a try! ❤️
I'm glad to hear about the additional commentary you are planning to add to the ReadMe and Project Description. I hope that, depending on the optics on your current team, you might also consider expanding your comment here into a blog post or conference presentation for a wider audience concerning the emerging, state-of-the-art Angular tooling landscape and how your current project (and, previously, angular-seed) fit into that.
Something I like about angular-seed is the explicit, extensible and imperative (Gulp-style) task-runner TypeScript code. To the extent you are opening up a similar but more capable (and well-documented) experience with the new Architect API for the Angular CLI, that sounds exciting and highly productive.
The expectations for an influential and vital seed/template project are high: it should ideally offer a reference implementation of the current leading tooling options and configuration patterns, with a mock/sample code implementation that aligns with the best practices set out in the core framework docs and guides. You and your contributors did yeoman work in bringing this project close to that ideal, back in the day. Your new comments will no doubt inform users of the current status.
As for me, I'm going to stick with the seed for my current project (a long-running-process-monitoring app), now that I've invested the (approximately 40 hours of) development time to resolve the configuration requirements of the seed related to diverse/complex package/plug-in and dependency management and to beat the core/shared/navigation/routing code patterns into shape. For my next project (a performance/UX-critical commercial web app), later this year, I'll hope to shift to an angular-nextgen-seed powered by your team's Architect API. 😉
When the time comes, where will we look for such a reference implementation?
You can check it out here angular/angular-cli#13463
We'll work on documenting it in future versions in the CLI.
Thank you @mgechev for giving me the opportunity to be part of this project. Those were my very first steps into open source contribution and i am happy was able to contribute something to the community, to which i was for many years 'just a user'. And as @dchennells pointed out: i also learned so very much!
❤️
Is there a chance that you publish a way how to migrate a project from the angular-seed to the angular-cli?
One can of course build a new "clean" cli project an copy paste the source folders. But begginers like me can easliy be confused about the differences in the project configurations.