Open aeiras opened 6 months ago
Dear @ttelang,
Thank you for your generosity in attending today's meeting and introducing yourself while enabling many Q&A.
This ticket has now been assigned to you, and you can use it as you see fit. 👍 This community collaborated with another wonderful MicroProfiler on a similar written project 2019- Technical White Paper Pro Bono by Lars RÖWEKAMP! #3 that has about 86 comments. Therefore, ASK AWAY!
Below is the core summary, in addition to your notes above, of today's feedback provided by MicroProfilers:
The milestones listed above should be postponed to ~ one month later to enable MP proactive feedback.
During the MP Holiday period, The Tutorial contract agreement needs to be signed directly with the EF team. Reza will connect you with the respective EF members via the MPWG forum. Those conversations with the EF are expected to be private. You are most welcome to use this ticket to let us know when the agreements are signed, and you are a GO to initiate your Research, if any, during the Holiday period.
MPWG Charter should help you navigate your contributions and collaboration with the MP Community. As mentioned today, MP's Openness is 1 of the seven pillars that should be protected while adding value to the ecosystem.
Requests @ttelang,
As a follow-up, I created a Google Drive space for you in the MP community folder under MP>Content
We need your email to give you Editor's access to own and manage the folder.
@aeiras - thanks for creating the Google Drive space. For granting edit permissions, my email id is: tarun.telang@gmail.com.
I have shared following queries to Kito via email. While, I am awaiting response, others may also respond here in case any further inputs.
I see there are two formats used for Jakarte EE tutorials: (1) https://eclipse-ee4j.github.io/jakartaee-tutorial/ (Old one) (2) https://jakartaee.github.io/jakartaee-documentation/jakartaee-tutorial/current/index.html (New one)
I am referring the following repositories and planning to create MicroProfile tutorial on similar lines:
From the above repos, I understand that I need to use the following tools to generate the MicroProfile tutorials:
@aeiras - thanks for creating the Google Drive space. For granting edit permissions, my email id is tarun.telang@gmail.com.
Dear Tarun,
Thank you for getting back to me so quickly. Your editor access has been sent this AM. Welcome to MPWG, contributing via Google Drive as well. :)
I am glad the extra resources provided via this ticket are valuable to your initial MP research. You are already helping improve things in MP with the ticket you submitted. Amazing OSS form, Tarum. You got this! :)
As we start the MP Holiday brake up until the 8th of January, I wish you a beautiful Holiday and a happy end of 2023!
Following Items have been discussed so far:
I will be preparing the MicroProfile Tutorial as per the format -
https://jakartaee.github.io/jakartaee-documentation/jakartaee-tutorial/current/index.html
The content would be written as per Jakarta EE Tutorial Style Guide
Diagrams will be created using draw.io as per the guidelines at this page - [Jakarta EE Tutorial - Creating Diagrams]- https://github.com/jakartaee/jakartaee-tutorial/blob/main/CONTRIBUTING.md#creating-diagrams.
I am planning to store the assets of the MicroProfile Tutorials in the following repositories:
S.N | Repo | Purpose |
---|---|---|
1. | https://github.com/eclipse/microprofile-tutorial | Content of the MicroProfile Tutorial |
2. | https://github.com/eclipse/microprofile-documentation | Builds documentation site using the Antora Playbook. |
3. | https://github.com/eclipse/microprofile-documentation-ui | HTML and CSS assets used for the look and feel of the documentation site. |
4. | https://github.com/eclipse/microprofile-examples | Example source code used inside the Tutorial content |
I need to finalize whether 1&4 should be merged or kept separately.
I would be referring How Antora Works to get started with how Antora orchestrator pulls up the content from different repos and generates the UI with content, search, etc.
Thanks Kito for confirming the format and tools via email and sharing the style guides about writing content and creating diagrams.
I have started organizing the content in this repository, https://github.com/ttelang/microprofile-tutorials - will get this copied to the new repository https://github.com/microprofile/microprofile-tutorials in a weeks time after it gets into decent shape.
The tutorial will be based will be based on the currently available latest version of MicroProfile 6.1. Let me know in case, anyone has any other opinion or views on this.
Today (Jan 23, 2024), I attended MP Open API Technical Call today, presented the outline draft document - https://drive.google.com/file/d/1sSy5FyeQM_QYBPWK761XrBAtUtUQx6ye/view?usp=sharing for feedback on the MicroProfile OpenAPI Specification chapter.
Below were some inputs I received:
@ttelang Thank you for joining the MP Technical call yesterday and providing an informative update! As promised on the call, when you are ready to get feedback, please email to the following 2 addresses: microprofile@googlegroups.com, microprofile-wg@eclipse.org
This EF issue was raised to get the dedicated microprofile-tutorial repo created.
Thanks @Emily-Jiang for sharing about MicroProfile google group and working group mailing lists. I have subscribed to these and started a conversation regarding seeking feedback about the MicroProfile API Tutorial. I will engage with these forums for further inputs regularly.
Please find below my revised plan for completing the MicroProfile APIs Tutorial:
Milestone | Deliverables | Date | ETA |
---|---|---|---|
Design | Final Content Outline and Structure | Done | |
Milestone 1 | Draft Completion for Chapters 1 | 6th Feb 2024 | Done |
Draft Completion for Chapters 2 | 8th Feb 2024 | Done | |
Draft Completion for Chapters 3 | 10th Feb 2024 | Done | |
Milestone 2 | Draft Completion for Chapters 4 | 12th Feb 2024 | Done |
Draft Completion for Chapters 5 | 14th Feb 2024 | Done | |
Draft Completion for Chapters 6 | 16th Feb 2024 | Done | |
Milestone 3 | Draft Completion for Chapters 7 | 18th Feb 2024 | Done |
Draft Completion for Chapters 8 | 20th Feb 2024 | 7th March | |
Draft Completion for Chapters 9 | 22th Feb 2024 | 7th March | |
Draft Completion for Chapters 10 | 24th Feb 2024 | 8th March | |
Draft Completion for Chapter 11 | 26th Feb 2024 | 8th March | |
Milestone 4 | Finalized Tutorial | 29th Feb 2024 | 10th March |
I am working on this repo - https://github.com/ttelang/microprofile-tutorials. After the new repo within the eclipse organization is created, I would move the content there.
Update - This is the new repo for MicroProfile tutorial - https://github.com/eclipse/microprofile-tutorial, please watch this for further updates.
I am worried about using the MicroProfile starter as the basis for the tutorial. It creates a mess regarding the variability of JDK/MicroProfile Version/Spec support. Some implementations, like Quarkus, focus on its own starter and not the MicroProfile starter because it is more feature-specific to Quarkus.
Maybe a more appropriate approach is for each runtime to provide a CLI, pom.xml, or instructions for project creation. During the development of the tutorial, I suspect each implementation would have to tweak the instructions as we learn more.
I am worried about using the MicroProfile starter as the basis for the tutorial. It creates a mess regarding the variability of JDK/MicroProfile Version/Spec support. Some implementations, like Quarkus, focus on its own starter and not the MicroProfile starter because it is more feature-specific to Quarkus.
Maybe a more appropriate approach is for each runtime to provide a CLI, pom.xml, or instructions for project creation. During the development of the tutorial, I suspect each implementation would have to tweak the instructions as we learn more.
I attended MP Starter call on 12th Feb 2024. MP6.1 supports is not yet there.
Below is what I am planning to cover.
Introducing readers about generating a new project structure using MicroProfile Starter. Will also add a note like something like below:
IMPORTANT: At the time of writing this tutorial, the latest MicroProfile released version was 6.1. We will not be using MicroProfile Starter to generate the project structure as it does not currently support this version.
@ttelang the github repo https://github.com/eclipse/microprofile-tutorial has been created. You can create PRs to move your materials there.
Kindly review and share your feedback, inputs or suggestions as comments directly to the Google Docs. Below is the list of chapters that are Ready for Review:
Front Matter - Sections: Legal, About this Tutorial, Who is this Tutorial for, What will be covered, Project, Downloading the Code, Prerequisites, Learning Objectives, Conventions
Chapter 1: Introduction to MicroProfile - Sections: What is MicroProfile, Need for MicroProfile, MicroProfile Specifications, Current MicroProfile Implementations, Architecture Philosophy, Benefits of MicroProfile, Relationship with Jakarta EE Specification
Chapter 2: Getting Started with MicroProfile - Sections: Development Environment Setup, Build Tools, Integrated Development Environments, Setting up MicroProfile Runtime, MicroProfile Starter, Creating a Java Project, Creating a REST Resource
Chapter 3: Jakarta EE Core Profile - Sections: Understanding the Jakarta EE 10 Core Profile, Key Specifications in Core Profile, Managing Component Dependencies, Handling HTTP Methods and Resources
Chapter 4: MicroProfile Open API - Sections: Introduction to MicroProfile OpenAPI, API Specification using MicroProfile Open API, Generating API Documentation, Exploring the APIs using Swagger UI
Chapter 5: MicroProfile Configuration - Sections: Understanding MicroProfile Configuration, Different environments required for Microservices development, Working with Various Configuration Sources, Key capabilities of MicroProfile Configuration, Implementing Configuration Properties, Creating a Custom Configuration Source, Dynamic Updates and Handling Configuration Change Events, Managing Configuration for Different Environments, Securing Configuration and Best Practices
Chapter 6: MicroProfile Health - Sections: Overview of MicroProfile Health, Types of Health Checks, Standard Health Checks, Implementing and Exposing Health Checks, Logging and Reporting Health Checks, Best Practices for Effective Health Checks
Chapter 7: MicroProfile Metrics - Sections: Introduction to MicroProfile Metrics, Need for Metrics in Microservices, Types of Metrics, Adding MicroProfile Metrics Dependency, Metrics Annotations, Using Metadata with Metrics, Categories of Metrics, Metric Registry, Instrumenting Microservices with Metrics, Creating Custom Metrics
I will update the above list as soon as more Chapters gets ready for review.
@ttelang the github repo https://github.com/eclipse/microprofile-tutorial has been created. You can create PRs to move your materials there.
@Emily-Jiang - Thanks for getting this repo created. I will start creating PRs in next couple of days for migrating the tutorial content.
We would need 3 more repos as for the MicroProfile API tutorial as mentioned in the table here - https://github.com/eclipse/microprofile-marketing/issues/847#issuecomment-1864488393
@ttelang the github repo https://github.com/eclipse/microprofile-tutorial has been created. You can create PRs to move your materials there.
@Emily-Jiang - Thanks for getting this repo created. I will start creating PRs in next couple of days for migrating the tutorial content.
We would need 3 more repos as for the MicroProfile API tutorial as mentioned in the table here - #847 (comment)
@ttelang we discussed this at the last Technical call. We agreed to just have one repo microprofile-tutorial. You can add multiple modules in that repo.
@ttelang I have the MP Tutorial repo set up for you with Apache License and it is ready for you to create PRs.
@ttelang I have the MP Tutorial repo set up for you with Apache License and it is ready for you to create PRs.
Hi @Emily-Jiang , I have created the following PRs for your review:
I am worried about using the MicroProfile starter as the basis for the tutorial. It creates a mess regarding the variability of JDK/MicroProfile Version/Spec support. Some implementations, like Quarkus, focus on its own starter and not the MicroProfile starter because it is more feature-specific to Quarkus.
Maybe a more appropriate approach is for each runtime to provide a CLI, pom.xml, or instructions for project creation. During the development of the tutorial, I suspect each implementation would have to tweak the instructions as we learn more.
The tutorial will take a neutral approach avoid emphasizing any single MicroProfile implementation.
Collaborating with the MicroProfile community, we can seek links to more in-depth guides provided by the implementations themselves.
Recorded these videos 🎥 while verifying the content of first three chapters of MicroProfile Tutorial (Milestone 1)
@ttelang Do you have an update? It's been a while and we haven't seen updates on the Google Docs that we review. Are you waiting on an action item from us?
@ttelang please provide a status update to this issue. Thanks!
@ttelang We'd like to get an update before the steering committee call on Tuesday.
Thanks!
Tracing history via MP forums