Much time has passed since I published the initial version of the easy-ui5 generator about two and a half years ago. The project initially started as a nice show-case to prove that UI5-based projects can be kickstarted super fast and grew beyond that idea to a multi-functional scaffolding tool. Back then, I wasn't sure whether this tool would still be around (and used!) when it's two years old. This post will be all about how the community (= YOU!) influenced the tool until today and how it can support it in the future!
In case you want to hear more about the history and Open Source spirit behind the generator, listen to this UI5 NewsCast episode to which I was invited a few weeks ago.
As with every Open Source project, you never know if you'll get any attention at all. So I was thrilled when it got almost 100 downloads in the first week and received a first (SAP-internal) pull request by the UI5 core team member matthias.osswald.
From there, the tool grew slowly but also steadily. Over time, a few things changed in the way we deploy web apps to SAP BTP: From "approuter-embedded" apps to the HTML5 application repo and eventually to the managed approuter and the SAP Launchpad service. Updating the generator every now and then turned out to be a win-win situation. I got to understand many details about the new deployment options, and, as a side-effect, the SAP Community always had a generator using the latest innovations.
Over time, external contributions happened more frequently and turned easy-ui5 from a single-purpose to a multi-functional tool. uxkjaer, for example, added another sub-generator for nested components - a feature that I didn't think of but perfectly fitted in the generator. Other contributions went even further and added support for additional testing frameworks (even for frameworks I wasn't very familiar with). Thanks to everyone who contributed! With all these new features and contributors, the tool grew further and got almost 2500 downloads in its best week. So it's clear that the one significant factor that made this generator successful was the SAP Community around it!
The advantages of community contributions outweigh the minor disadvantages that exist. But I think it is also worth mentioning what didn't work so great. New pull requests naturally meant new code (written by another developer) needed to be checked and maintained by me. And whenever someone opened an issue for that code, I had to be the middleman and assign it to the original author of the pull request. I know that this is a natural part of open source projects which isn't a bad thing - but in combination with my lack of knowledge of some project parts, it increased the complexity of the overall project. I'd say this was the point when the tool grew beyond its initial scope.
Another problem of easy-ui5 was the definition of the scope that I wanted to cover. As already mentioned, easy-ui5 was designed to scaffold UI5 applications, and it was a no-brainer to add sub-generators for views, controllers, and models. All web applications need to be deployed somewhere, so it made sense to add some artifacts to support different target systems. And web apps need to be tested - of course. Ideally, I'd support multiple test frameworks. Then the question arose, are these tests separate projects or nested in the same code base? Well, there's no general answer to that question, which means the generator should create test projects as well. And while we're on it, bootstrapping other project types like libraries makes sense as well. You probably see where I want to go here: Where does the scope end? I also need to admit that the original architecture wasn't a good fit for such a generic scope.
In parallel, peter.muessig approached me and asked me about my plans for this project and how we can work together. Peter just had created a new organization on GitHub that should become the "central place to host all those different project types and ideally create a place to advertise the...
So when the urgency for a new architecture came up, it was the perfect opportunity to join forces. Together, we came up with a plan to hit all birds (scope, architecture, and the GitHub organization) with one stone: Turn easy-ui5 from a generator to a generator-runner!
It was the natural move to externalize all used templates from the "old easy-ui5" to this organization and turn the core of easy into a generic scaffolding tool that fetches templates on-demand from that GitHub organization. This way, generators become plugins for easy-ui5. The loose coupling gives every community member the chance to write their plugin and expose it to the entire UI5 ecosystem via easy-ui5.
8d8214c7f9734f45be69f95cc0d5aeee, who suggested a sub-generator for UI5 libraries, was brave enough to move first and volunteered to build an excellent easy-ui5-plugin to bootstrap UI5 libraries. Check out the source code on GitHub.
You probably now wonder how to build a plugin for easy-ui5. The great news is we didn't reinvent the wheel! All plugins are Yeoman generators that you can run standalone as well. This also makes it easy for me as I can simply redirect you to the official "Creating a generator" documentation 🙂
Besides the default Yeoman architecture, you need to meet only one condition to make your plugin available in easy-ui5: The generator repository needs to follow the name pattern "generator-ui5-X" to be hosted in the GitHub Organization "UI5 Community". Easy, isn't it?
In case you want to build a plugin, I recommend comparing it to the default plugin for new projects or Geert's generator-ui5-library.
From here, Easy-UI5 is capable of finding the plugin and all sub-generators that are included. I also recommend going the extra mile to annotate each sub-generator to make the life of developers easier:
In case you want to hear more about the history and Open Source spirit behind the generator, listen to this UI5 NewsCast episode to which I was invited a few weeks ago.
You can find the podcast here
The story so far
As with every Open Source project, you never know if you'll get any attention at all. So I was thrilled when it got almost 100 downloads in the first week and received a first (SAP-internal) pull request by the UI5 core team member matthias.osswald.
From there, the tool grew slowly but also steadily. Over time, a few things changed in the way we deploy web apps to SAP BTP: From "approuter-embedded" apps to the HTML5 application repo and eventually to the managed approuter and the SAP Launchpad service. Updating the generator every now and then turned out to be a win-win situation. I got to understand many details about the new deployment options, and, as a side-effect, the SAP Community always had a generator using the latest innovations.
Over time, external contributions happened more frequently and turned easy-ui5 from a single-purpose to a multi-functional tool. uxkjaer, for example, added another sub-generator for nested components - a feature that I didn't think of but perfectly fitted in the generator. Other contributions went even further and added support for additional testing frameworks (even for frameworks I wasn't very familiar with). Thanks to everyone who contributed! With all these new features and contributors, the tool grew further and got almost 2500 downloads in its best week. So it's clear that the one significant factor that made this generator successful was the SAP Community around it!
Challenges
The advantages of community contributions outweigh the minor disadvantages that exist. But I think it is also worth mentioning what didn't work so great. New pull requests naturally meant new code (written by another developer) needed to be checked and maintained by me. And whenever someone opened an issue for that code, I had to be the middleman and assign it to the original author of the pull request. I know that this is a natural part of open source projects which isn't a bad thing - but in combination with my lack of knowledge of some project parts, it increased the complexity of the overall project. I'd say this was the point when the tool grew beyond its initial scope.
Another problem of easy-ui5 was the definition of the scope that I wanted to cover. As already mentioned, easy-ui5 was designed to scaffold UI5 applications, and it was a no-brainer to add sub-generators for views, controllers, and models. All web applications need to be deployed somewhere, so it made sense to add some artifacts to support different target systems. And web apps need to be tested - of course. Ideally, I'd support multiple test frameworks. Then the question arose, are these tests separate projects or nested in the same code base? Well, there's no general answer to that question, which means the generator should create test projects as well. And while we're on it, bootstrapping other project types like libraries makes sense as well. You probably see where I want to go here: Where does the scope end? I also need to admit that the original architecture wasn't a good fit for such a generic scope.
In parallel, peter.muessig approached me and asked me about my plans for this project and how we can work together. Peter just had created a new organization on GitHub that should become the "central place to host all those different project types and ideally create a place to advertise the...
New Design
So when the urgency for a new architecture came up, it was the perfect opportunity to join forces. Together, we came up with a plan to hit all birds (scope, architecture, and the GitHub organization) with one stone: Turn easy-ui5 from a generator to a generator-runner!
It was the natural move to externalize all used templates from the "old easy-ui5" to this organization and turn the core of easy into a generic scaffolding tool that fetches templates on-demand from that GitHub organization. This way, generators become plugins for easy-ui5. The loose coupling gives every community member the chance to write their plugin and expose it to the entire UI5 ecosystem via easy-ui5.
8d8214c7f9734f45be69f95cc0d5aeee, who suggested a sub-generator for UI5 libraries, was brave enough to move first and volunteered to build an excellent easy-ui5-plugin to bootstrap UI5 libraries. Check out the source code on GitHub.
Creating a new UI5 library with easy-ui5
How to build a plugin for easy-ui5
You probably now wonder how to build a plugin for easy-ui5. The great news is we didn't reinvent the wheel! All plugins are Yeoman generators that you can run standalone as well. This also makes it easy for me as I can simply redirect you to the official "Creating a generator" documentation 🙂
Besides the default Yeoman architecture, you need to meet only one condition to make your plugin available in easy-ui5: The generator repository needs to follow the name pattern "generator-ui5-X" to be hosted in the GitHub Organization "UI5 Community". Easy, isn't it?
In case you want to build a plugin, I recommend comparing it to the default plugin for new projects or Geert's generator-ui5-library.
From here, Easy-UI5 is capable of finding the plugin and all sub-generators that are included. I also recommend going the extra mile to annotate each sub-generator to make the life of developers easier:
- The "hidden" property to hide sub-generators that shouldn't be exposed
- The "displayName" property to
- React to the "embedded" option that is passed to your sub-generator to allow a context-aware flow (e.g., to prevent a second greeting)
Showing the "displayName" of multiple sub-generators
Summary
- Easy-UI5 v3 is out! 🥳
- From now on, you'll always use the latest version of the templates even when you're not using the newest version of easy-ui5 (updating is still highly recommended)
- Different people can maintain various repos / plugins, but there's still one way to trigger them (yo easy-ui5)
- You can build your own plugins in the UI5 Community organization on GitHub
- SAP Managed Tags:
13 Comments
