openliberty / cloud-hosted-guides Goto Github PK

• Bullet point sections appear as code blocks
• Some strange formatting with the curl commands, tried to fix with PR
  • OpenLiberty/guide-microprofile-reactive-messaging-acknowledgment#63

Need to revisit the following

vs

Both Landing and password recovery pages should look likes as:

• is it possible to generate landing pages?
• define the content of the landing pages
• how to back them up?
• how to restore them?
• how to update them?

Implement the new design of the create account page as following:

Need to discuss and design the home page

Which Terminal are you referring to the OS or the one in the right panel?
For more than one terminal can we number them to make it easier to refer to which one we are talking about?

There is a "null" text at the bottom (under the time) of the landing page and the Access Cloud-Hosted Guide button at the top

but in staging SN the button at the bottom

• The height of the email and password text fields are too much. They can be thinner.
• The sign in button font is too big too
• the font size of all text should be same except the title
• The title "Sign in" and the sign in button look duplicated

I did not see a link for reset in the email. I am not clear how the technical support works.

Check Your Email

You entered If this email address is associated with your Open Liberty Hands On account, we will send a message with password recovery instructions to this email address.

If you do not receive a password reset message after 1 minute, verify that you entered the correct email address, or check your spam folder.

If you need further assistance, contact technical support.

The following terms are used in different pages.

• Open Liberty SkillsNetwork (in login page, github signin page)
• Open Liberty Skills Network (in login page)
• skillsnetwork.site (google signin page)
• Open Liberty Skills Network Portal (logout page, home page)
• Open Liberty Hands On (SN account page)

Need to be consistent

create more development quicklabs as https://github.com/OpenLiberty/cloud-hosted-guides/blob/staging/instructions/cloud-hosted-draft-guide-development/instructions.md

• include to update the github action(s)

e.g. cloud-hosted-draft-guide-development-1, cloud-hosted-draft-guide-development-2, cloud-hosted-draft-guide-development-3

Step 3

• The formatting of the table is a bit off. Maybe put spaces between username roles password

Step 7

• , getting this issue

Step ..

Could complete the lab

Overall

• When creating new files, I found it easier to command+click rather then following select File > Open > guide-microprofile-jwt/start/frontend/src/main/java/io/openliberty/guides/frontend/ApplicationBean.java

• Alternatively, when doing it locally on VSCode, you can do code -r guide-microprofile-jwt/start/frontend/src/main/java/io/openliberty/guides/frontend/ApplicationBean.java and it will open that file directly within the current instance of VSCode. To do this, we would need to add vscode to the path.

Can we externalize text to a separate properties files (or whatever equivalent or appropriate) so we don't have to hard code and they can be updated without needing to recompile code?

@jamiecoleman92 @gkwan-ibm

This section has been manually added to guide-reactive-service-testing.

Implement the new design as

When use Github login, I found "Open Liberty SkillsNetwork by austin0". Should not use austin0.

After doing some experimenting with the course view I noticed some of the layout needs correcting. This will probably need a redesign for some aspects such as the header and footer although the actual course may not be configurable. This may be a bigger piece of work but as a min we need to make sure the header and footer are readable and in some kind of order unlike the image below:

• Architecture diagram missing on first page —> remove reference to diagram as we will not be including it

• Additional pre-reqs page not needed now

• Missing this sentence —> The finish directory contains the finished project that you will build.

• Not sure why this is there —> start/SystemService.java in the Choosing an acknowledgment strategy section?

• POSTPROCESSING —> style is incorrect, should be underscore and in box type

• Not sure why this section is all in italics, not needed —> strategy by default. If the acknowledgment strategy is set to

• This formatting has gone funny - should just be bullet points ins the text not in a code box —> - If the method emits data, the incoming message is acknowledged after the outgoing message is acknowledged. - If the method doesn't emit data, the incoming message is acknowledged after the method or processing completes.

• All this text is formatted incorrectly, should be normal text —>
“ Its important that the methods use the POST_PROCESSING strategy because it fulfills the requirement that a message isn't acknowledged until after the message is fully processed. This processing strategy is beneficial in situations where messages must reliably not get lost. When the POST_PROCESSING acknowledgment strategy cant be “



————
Implementing the MANUAL acknowledgment strategy
———

• This shouldn’t be here —> finish/SystemService.java

• 
This should just be normal text as bullet points —> - If the system property isn't valid, the method acknowledges
  the incoming message and returns an empty reactive stream. The processing is
  complete. - If the system property is valid, the method creates a message with the value of the
  requested system property and sends it to the proper channel. The method acknowledges the incoming message only
  after the sent message is acknowledged.

———
Waiting for a message to be acknowledged
———

• This shouldn’t be here —> InventoryResource.java

• Missing semicolon at the end of the provided replacement for InventoryResource.java file

——
Building and running the application
———

• Command not formatted correctly to be copyable. Should be two separate commands—> docker build -t system:1.0-SNAPSHOT system/. docker build -t inventory:1.0-SNAPSHOT inventory/.

• Issues with formatting at the bottom of this page —> weird -- unnecessary lines here and command not formatted correctly to be copyable again - ./scripts/startContainers.sh

——
Testing the application
———

• Missing this sentence —> Go to the http://localhost:9085/inventory/systems URL to access the inventory microservice. You see the CPU systemLoad property for all the systems: (Only have “Go to the” at the moment)

• Need to remove comments or format them correctly for SNL —> otherwise curl commands will result in error 500

• Curl command not formatted correctly for copying —> curl -X PUT -d "os.name" http://localhost:9085/inventory/data --header "Content-Type:text/plain"

——
Tearing down the environment
——

• Command not configured correctly for copying —> ./scripts/stopContainers.sh

• The command —> rmdir guide-microprofile-reactive-messaging-acknowledgment - Fails to remove the directory

When a user logins in using Linkedin and instead of creating a new account presses "sign in" (temporarily disabled) it doesn't render properly.

Step 6 has the fonts going into very small for this part.

Overall, I think that the text hierarchy could be improved. In step 6, it a little bit hard to see quickly when we are switching to a new instruction.

When unlink an account, got following error

This problem was also reported at https://github.ibm.com/skills-network/portals/issues/1724

Accessing tutorial catalogue at https://ide.skillsnetwork.site/open-liberty-tutorial-catalogue I try to open a module and receive the following error in the Open Liberty Masterclass Modules

You tried to start a QuickLab with invalid markdown instructions. Please contact the QuickLab author to let them know their QuickLab is broken.

Encountered on Module 1 (Build) and Module 2 (Dev Mode) and Module 3 (Application API), have not checked other modules or categories yet.

Accessed in Firefox on Windows 10

The lab for guide-reactive-rest-client seems to be quite out out of date and has errors that are fixed in the current version, it also seems to have been converted with an old version of the tool so could use a refresh to fix a number of syntax errors.

Link to guide: https://github.com/openliberty/guide-reactive-rest-client

@jakub-pomykala can this be a situation to test the automation bot?

We have implemented a manual fix for the output example of terminal when user runs:

mvn liberty:dev

Previously the output example was

The defaultServer server is ready to run a smarter planet.

But now the output example is:

**********************************************************
*    Liberty is running in dev mode.

Every time commit a PR, all guides will be triggered to refresh. It slows down the SN.
Need to improve the refresh infrastructure/mechanism

• when merge a PR, only refresh 1 guide in SN, now refresh all guides
• PR not for guide, should not refresh SN

It is better to use a color for the text output or not use red instead of following screenshot.

step 7

• The command should be curl http://localhost:**9091**/inventory/systems/{$SYSTEM_IP}

• The text before this command tells you to get use the previously found IP, so I think we should either remove SYSTEM_IP=`docker inspect -f "{{.NetworkSettings.IPAddress }}" system` from the command or rewrite the instruction

step 8

• Potentially visual bug? The font size decreases here

• Test failure for inventory

In Module 1 in the Reactive Java Workshop I found some errors in the text.

At the end of step 2 there is this text

The SystemService class contains a Publisher method that is called Flowable.interval() method from rxJava is used to set the frequency of how often the system service publishes the calculation to the event stream.

The sentence doesn't work and it looks like it is missing the middle portion of this paragraph from the Microprofile Reactive Messaging guide

The SystemService class contains a Publisher method that is called sendSystemLoad(), which calculates and returns the average system load. The @Outgoing annotation on the sendSystemLoad() method indicates that the method publishes its calculation as a message on a topic in the Kafka messaging system. The Flowable.interval() method from rxJava is used to set the frequency of how often the system service publishes the calculation to the event stream.

A similar error occurs at the end of step 3. The text in the module says:

The InventoryResource class contains a method called systemLoadTopic.

The guide text says:

The InventoryResource class contains a method called updateStatus(), which receives the message that contains the average system load and updates its existing inventory of systems and their average system load. The @Incoming("systemLoad") annotation on the updateStatus() method indicates that the method retrieves the average system load information by connecting to the channel called systemLoad. Later in the guide, you will configure the service so that any messages sent by the system service through the systemLoad channel are retrieved from a topic called systemLoadTopic, as shown in the following diagram:

OL SN is using custom configuration. Need a backup and restore plan in case to rebuild it. e.g.

• use lms-yyyymmdd.zip
• backup the lms-yyyymmdd.zip in this repo

• microprofile-istio-retry-fallback
• microprofile-jwt
• microprofile-metrics
• microprofile-openapi
• microprofile-reactive-messaging-acknowledgment
• microprofile-reactive-messaging-rest-integration
• microprofile-rest-client-async

• the landing page is almost empty at the landing page and wrong
  • 

When @austin0 and myself try to login using Github/LinkedIn it requests our email address. This is some kind of a bug that is not major but should be looked into further. This has been tested with a number of different users and it only has happened to us till this date.

Example outcome of signing in with LinkedIn bellow:

Edit: This does not happen every single time on GitHub.

Ideally, if the lab (IDE) have a browser viewer, users can access e.g. http://localhost:9080/inventory/systems directly instead of by curl

If not, consider rewrite the guides to access the urls from the index.html

When trying to copy the new code from the left pane into the editor on the right, the error message pops up:

I am able to successfully copy and paste into the terminal, the issue is only with the editor. Also, if I copy using the browser's copy and paste, it works fine.

This was tested on a Linux VM using Firefox. This could be an issue unique to testing on a VM, but this is my only way to test it.

When users logout from landing page, SN should redirect them back to the openliberty.io/guides

What you'll learn

• Not formatted correctly --> Youll first look at the supplied client application that uses the JAX-RS default CompletionStage-based provider. Then, youll mo --> should just be the completionstage that's formatted differently, all the rest should be normal text

• Remove pre-req section, not needed for snl

Creating a web client using the default JAX-RS API

• this needs to be removed --> InventoryClient.java

• Needs to be used, not use --> JAX-RS provides a default reactive provider that you can use to create

• Missing a cd start command before first touch command to Create the InventoryClient interface.

• Codeblock for InventoryClient interface has gone very wrong!

• All the codeblocks and normal text after this seem to have been reversed and are all wrong for the remainder of this section.

• None of the sections have been separated out into new tabs in SNL following this

• GuideConverter.java
  • Need license comment in the java file
  • Better not hard code the string but read the adoc files from the guides-common repository
    • generic code to read adoc file
  • writeToFile() is not efficient to open, write, and close the .md file. Either
    • write the content to a string buffer/stream, at end write the string buffer/stream to the .md file
    • or open the file stream at the beginning, and close at the end
  • in getMD(String guideName), look like the "temp.adoc" is just opened and closed. Any reason?
  • in codeSnippet(String path, String guideName), look like the "temp.adoc" is just opened and not closed. Any reason?
• actions.yaml
  • README.md is removed before running the GuideConverter. In case, GuideConverter fail, will README.md be removed and PR still created?
• Does the action directly update the master? If yes, need to make sure the automation won't screw up the master, especailly in failure, although it is possible to revert the PR. (i.e. if failure, no update)

The production portal should only have production guides. No development work.

The staging portal should be used as development purpose for guides, converter, front-end, and even SN and quicklab update

Suggested edits for register and Login pages:

Register page

We will send you an account activation email. You can sign into the cloud-hosted guides next time, after you activate your account through that email.
--->
When you create an account, we send you an account activation email. You can sign in to the cloud-hosted guides after you activate your account through that email.

If the provider cannot provide your name and email to the IBM Developer Skill Network, you will be asked to create a regular IBM Developer Skills Network account.
--->
If the provider cannot provide your name and email to the IBM Developer Skill Network, you must create a regular IBM Developer Skills Network account.
OR
If the provider cannot provide your name and email to the IBM Developer Skill Network, we ask that you create a regular IBM Developer Skills Network account.

I am at least sixteen years of age.
--->
I am at least 16 years of age.

Login page

The OpenLiberty cloud-hosted guides
--->
The Open Liberty cloud-hosted guides

You can sign in with IBM Development Skills Network account or one of the following single sign-on providers.
--->
You can sign in with an IBM Development Skills Network account or through one of the following single sign-on providers.

I am at least sixteen years of age.
--->
I am at least 16 years of age.

The only way the JS is always running is when it is running on a setTimeOut(). This has to be changed ASAP as it could cause problems for users in the future. The reason why it is using setTimeOut() is because document.addEventListener("DOMContentLoaded", function() nor window.addEventListener("load", function() did not work and caused the JS to load before the HTML/window finished loading

Rename "quick-labs" to "cloud-hosted-guides" when ready to be consistent with formal name and other repo(s).

• Starting and preparing your cluster for deployment
  • minikube start not work
    • Does SN lab support minikube or DockerDesktop?

• Incorrect path given - under the Configuring your containers section this path is incorrect: cd guide-reactive-service-testing/start/system --> It should be instructing the user to cd into the inventory directory not the system directory

For the previous time the custom CSS and the JS have been stored in Daniels personal repo. However we should move this over to this repo and also consider moving over the whole eDX theme and store it here.

At this moment Landing pages have to be created manually. However (if landing pages will still be used), it would be a good idea to automate this process using github actions and requests.

The curl command in step 7 takes a while to run. We should add a text to the static guide which will let users know that this command will take a while to run.

In some cases, after a user clones and opens the guide in the IDE they can see loads of red files with an warming/error of "Incorrect Package Name".

e.g.
This is the issue:

This is what the issue causes:

Because of this users may think that their code is broken.

Talk to Skills Network about the warning message pointed out by Gilbert. See if possible to either remove or move to privacy policy.

Need to add an OL branding (image) at the top of the cloud-hosted guide