Bug 1011842 - Misprints and errors in quickstarts readme files
Misprints and errors in quickstarts readme files
Status: CLOSED CURRENTRELEASE
Product: JBoss Enterprise Application Platform 6
Classification: JBoss
Component: Quickstarts (Show other bugs)
6.2.0
Unspecified Unspecified
unspecified Severity unspecified
: ER5
: ---
Assigned To: sgilda
Vladimir Rastseluev
:
Depends On:
Blocks:
  Show dependency treegraph
 
Reported: 2013-09-25 04:47 EDT by Vladimir Rastseluev
Modified: 2017-10-09 20:10 EDT (History)
3 users (show)

See Also:
Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of:
Environment:
Last Closed: 2013-12-15 11:18:01 EST
Type: Bug
Regression: ---
Mount Type: ---
Documentation: ---
CRM:
Verified Versions:
Category: ---
oVirt Team: ---
RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: ---


Attachments (Terms of Use)

  None (edit)
Description Vladimir Rastseluev 2013-09-25 04:47:27 EDT
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 17:23:29 EDT
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 01:32:52 EDT
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 07:45:49 EDT
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 14:49:56 EDT
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 17:01:48 EDT
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-03 22:33:00 EDT
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 07:26:12 EDT
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 03:36:30 EDT
Verified on EAP 6.2.0 ER5

Note You need to log in before you can comment on or make changes to this bug.