Bug 1011842

Summary: Misprints and errors in quickstarts readme files
Product: [JBoss] JBoss Enterprise Application Platform 6 Reporter: Vladimir Rastseluev <vrastsel>
Component: QuickstartsAssignee: sgilda
Status: CLOSED CURRENTRELEASE QA Contact: Vladimir Rastseluev <vrastsel>
Severity: unspecified Docs Contact:
Priority: unspecified    
Version: 6.2.0CC: bsutter, pmuir, pslavice
Target Milestone: ER5   
Target Release: ---   
Hardware: Unspecified   
OS: Unspecified   
Whiteboard:
Fixed In Version: Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of: Environment:
Last Closed: 2013-12-15 16:18:01 UTC Type: Bug
Regression: --- Mount Type: ---
Documentation: --- CRM:
Verified Versions: Category: ---
oVirt Team: --- RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: --- Target Upstream Version:

Description Vladimir Rastseluev 2013-09-25 08:47:27 UTC
Description of problem:
There are several misprints and errors in README.md files in quickstarts

Version-Release number of selected component (if applicable):
EAP 6.2.0 ER3

How reproducible:
easy

1) in all quickstarts version "EAP 6.1" is used. Need to be updated as "EAP 6.2"

2) in README.md in quickstarts root directory:

a) in chapter "Configure Maven to Build and Deploy the Quickstarts"
used non-existing "cp" command on Windows. Use "copy" command instead.
b) "Start JBoss server" chapter is printed twice. Use "Start JBoss server with web profile" in second case.
c) lack list of quickstarts at all. Add it.
d) in chater "Configure the Driver Using the JBoss CLI Interactively"
there is 4. step needed e.g."
Execute reload operation
[standalone@localhost:9999 /] :reload"

3)in ejb-multi-server replace "6.1erver" by "6.2 server"

Comment 1 sgilda 2013-10-01 21:23:29 UTC
1. These quickstarts work in EAP 6.1 or later. I'm not sure we want want to remove the 6.1 version.

2.b) I was told to remove the 'Web Profile'. Changed it to 'Start the Default JBoss Server'

2.c) We not longer list them all here. They are located here: http://site-jdf.rhcloud.com/quickstarts/jboss-as-quickstart/

2.d) Added.

3. Modified to 6.1 or later and removed release numbers later in the test.

Fixes are in commit https://github.com/jboss-developer/jboss-eap-quickstarts/commit/4b463777f67cf82555ede0d9aa089656da429a41

Comment 2 Vladimir Rastseluev 2013-10-02 05:32:52 UTC
1) If we ship these quickstarts with EAP 6.2, we need to be correct. We need to replace "Start EAP 6.1 server" either by "Start EAP 6.2 server" or "Start EAP server" or even by "Start EAP 6.x server" in all readme.md files. Note, that some of these quickstarts weren't in EAP 6.1.

2.c) I'm looking at this from customer's POV.
It's ok, that developers know, where to find list of quickstarts, but customer have no clue, reading quickstarts documentation. 
This issue is related to https://bugzilla.redhat.com/show_bug.cgi?id=1011833 - customer doesn't have readme in html format thus there is no way for him to get required info, because readme.md files doesn't contain it.

Comment 3 sgilda 2013-10-02 11:45:49 UTC
1) While many of the quickstarts will work with EAP 6.0, others, like the ejb-security-propagation quickstart, only work with EAP 6.1 or later. So I don't think we can say EAP 6.x. 

I think the best bet is to remove the version from the ones that work with any release and leave the 'EAP 6.1' or later for the others. Would that work? I already did that for the the root README. Can you let me know if that looks OK to you? Here's the link: 

https://github.com/jboss-developer/jboss-eap-quickstarts/blob/master/README.md

It gives the release in only one place where it says: 
'These quickstarts run on Red Hat JBoss Enterprise Application Platform 6.1 or later'

2)c. The list of quickstarts has to be hard-coded in the root README in a table. It was extremely problematic because it had to be manually maintained. That's why we added meta data to each individual quickstart README file and the information is generated automatically on the JDF website here: 

http://site-jdf.rhcloud.com/quickstarts/jboss-as-quickstart/

We don't want to go back to the manual table in the README file as it's not at all readable in markdown. I could add a link in the root README to the generated table  though. Would that work for you? In other words:

For a full listing of the JBoss EAP quickstarts, refer to: http://site-jdf.rhcloud.com/quickstarts/jboss-as-quickstart/

Comment 4 Vladimir Rastseluev 2013-10-02 18:49:56 UTC
1) I agree, please remove version in all quickstarts readme.md
2)c. We need to give a customer something, the link you mentioned at least, so please add it to main readme.md

Comment 5 sgilda 2013-10-02 21:01:48 UTC
1) Product versions

We added metadata for the product versions:
Product Versions: EAP 6.1, EAP 6.2

Every file has something like this under 'System Requirements':
The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 6.1 or later. 

I removed all the other EAP version references.

2) Added a link to the page containing the list of all available quickstarts: http://site-jdf.rhcloud.com/quickstarts/get-started/

Comment 6 Vladimir Rastseluev 2013-10-04 02:33:00 UTC
2)c. I don't see link  http://site-jdf.rhcloud.com/quickstarts/get-started/ in ER4 version of README.md file. Moreover there is a text:

"The following is a list of the currently available quickstarts. The table lists each quickstart name, the technologies it demonstrates, gives a brief description of the quickstart, and the level of experience required to set it up. For more detailed information about a quickstart, click on the quickstart name."

and no list.

Comment 7 sgilda 2013-10-04 11:26:12 UTC
Right. This was fixed in the upstream master branch. Usually Paul puts in a request when he wants a merge. I am a little afraid to do a merge at this point because there have been so many changes made to master, including submodules and other things. I will merge the README file changes.

We need to talk to Paul when he gets back and find out if he wants an entire merge at this point in the release cycle.

Comment 8 Vladimir Rastseluev 2013-10-10 07:36:30 UTC
Verified on EAP 6.2.0 ER5