Open sdelamo opened 4 years ago
I like this idea of generating the guides automatically. As someone that has updated the guides manually many times this would be great :smiley:
Some random thoughts in no particular order:
Instead of coupling the guides with Starter I think it would be better to fork the project and keep the guides code only in the fork. The main two benefits I see for this are to reduce the Starter build time (which already takes too much time) and do not mix the guides code with the features code. Keeping the fork up to date should be easy because we're not doing big changes in Starter anymore and we won't modify anything related to Starter in the Guides. Probably it would be a matter of merging the changes done upstream once a week and it won't be any merge conflicts.
I agree we should migrate 2-3 guides following this approach to really see how big the effort is and find any problems.
I'm afraid that migrating some of the "complex" guides (the ones with 3-4 microservices), with a lot of steps can be tricky and complicated. A few guides have "intermediate" directory (beside "complete" and "initial") and we fetch files from there as an intermediate solution. Then we explain a better solution and fetch the files from "complete" directory. Maybe we should re-think this and simplify those guides a little bit.
On the user side, I think with this approach it will be more complicated to users to send PRs because the code "is not there" but it's generated from rocker templates.
So, as a summary, :+1:. I think we should prioritize it and if we all agree start working on it. We have ideas for new guides on the pipeline and if the plan is not create more until this is done (or at least, only create new guides with this new approach during the migration), it's better to start soon.
I used a similar approach in Spring Security REST, by having a profile with the tests, and different features with their own dependencies and configurations to test different scenarios. Then I would generate all possible combinations with this custom profile, and add the generated projects to settings.gradle
, so at that point it was a matter of ./gradlew test
to test everything.
I really miss the possibility to package profiles as JAR files. If micronaut-starter
supported that, you wouldn't need to mess with forks.
A poor-man's alternative would be to create blank applications:
curl micronaut.io/launch --lang=kotlin
curl micronaut.io/launch --lang=groovy
curl micronaut.io/launch --lang=java
Then copy the artifacts (controller, test, configuration, etc).
And a third alternative coming to my mind is, instead of forking micronaut-starter
, you have a Gradle project with your features that has starter-core
and starter-cli
as dependencies.
In general, micronaut-starter
extensibility is something that should be revisited, and based on that, your strategy to implement this task might vary.
I think the idea of using starter is good. You don't have to fork it though as Alvaro said. You can simply add a dependency on it and your features will be picked up as they are just beans. Looking forward to the POC
In fact, my recommendation is that we don't write new guides until we have automate it.
With your recommendation, is there an ETA on when guide publishing would resume?
This is my vision for this.
Instead of being a guide per language, lets have a single guide. Each guide will contain build samples (Maven and Gradle), code samples in three languages (Java, Groovy, Kotlin) and test samples (Java Junit, Spock Groovy, Junit Kotlin).
My idea is to use the Launch infrastructure to create guides which upgrade automatically with new version and whose test are execute it each time the Micronaut Launch test suite is run.
For example, the Create your first Micronaut app would be a set of rocker templates:
and a Feature per guide:
Per guide, before rendering the HTML we will do some curl request to generate the sample projects:
Some projects, those with multiple apps (e.g. distributed tracing) may need to generate six projects or more.
We can make the Guide features hidden at the CLI and UI.
I think automating guides it is key to be able to write documentation and will provide a safety net of functional tests.
In fact, my recommendation is that we don't write new guides until we have automate it.
Before going rouge for every guide, I would recommend lets try to create a prototype with one guide.