On 14 Jan 2015, at 16:08, Paul Gier <pgier@redhat.com> wrote:

On 01/13/2015 02:36 AM, Paul Robinson wrote:

On 13 Jan 2015, at 04:27, Paul Gier <pgier@redhat.com
<mailto:pgier@redhat.com>> wrote:

On 01/07/2015 08:33 AM, Sande Gilda wrote:

On 01/07/2015 05:29 AM, Paul Robinson wrote:

Paul,

I think you are the right person for this, but I could be wrong…

On JBoss Developer we index quickstarts for each product and render
some of the documentation (README.md, CONTRIBUTING.md, for example) on
the site. Here’s an
example:http://www.jboss.org/quickstarts/eap/contributing/
<http://www.jboss.org/quickstarts/eap/contributing/>
<http://www-stg.jboss.org/pr/714/build/1464/quickstarts/eap/contributing/>.
We index the latest release of each quickstart from the related
Quickstart repo in the JBoss Developer GitHub organisation. It’s
important that we index the release, as we know it has been QA’d
against the latest product GA on the site.

However, there are several cases where broken links exist in the
documentation that we are indexing. Notice the ‘Fork’ link
on http://www.jboss.org/quickstarts/eap/contributing/. This is due to
a broken link in the source
content:
https://github.com/jboss-developer/jboss-eap-quickstarts/blob/6.3.0.GA/CONTRIBUTING.md.
This is easy to fix at source, but we would need to wait for the next
quickstarts release (in this case EAP 6.4.0.GA) before JBoss Developer
can consume the fix. Broken links are bad for user experience and
adversely affect SEO, so we’d rather get them fixed sooner.

The CONTRIBUTING guide was moved to a common location to make it easier
to maintain and share across products:
https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONTRIBUTING.md

I moved quite a few files to the common location to make updates easier.
The list is here:
https://github.com/jboss-developer/jboss-developer-shared-resources/tree/master/guides

Since this file doesn't ship with a product, we can update it as needed.

One solution would be to allow documentation only changes to be made
to quickstarts between releases. In the example above, we would create
a commit (fixing the broken link) on top of the 6.3.0.GA release
(https://github.com/jboss-developer/jboss-eap-quickstarts/releases/tag/6.3.0.GA)
and then tag it as a new release. I think we’d have to use some naming
convention to indicate it was just docs that changed. JBoss Developer
would then index the new tag in order to consume the fix.

Should we create a new branch for these issues, for example,
6.3.1-develop and 6.3.1? Is it possible to create a new quickstart
distribution after GA?

It's probably up to QA and PM whether we want to deliver an updated zip
with the patch stream (6.3.x).  I think we don't do it now just because
they don't want the extra effort of testing it. I think we're pretty
much free to do what we want in the git repo, so we could create a
maintenance branch, although I'm not sure how we share that with the
customers.

So how about we limit these changes to just documentation (no code
fixes) and only to critical items like broken links. We make the changes
in the JBoss Developer GitHub repo and consume these changes on the
JBoss Developer site.

QA and PM can ship these updated QS if they want, with the patch
releases of the product.

Customers can go to JBoss Developer for the latest fixes to the QS docs.
If they really want a new release, that’s gone through QA, then they
would need to take that up with whoever manages their contract (not sure
on the process for that, but hopefully you get my point).

That's fine with me.

Great. Does this need adding to some guidlines somewhere?

Is this the right thing to do?

Paul.

--
Paul Robinson
JBoss Developer Team Lead (www.jboss.org
<http://www.jboss.org/> <http://www.jboss.org <http://www.jboss.org/>>)

Free/busy
info:
https://www.google.com/calendar/embed?src=probinso%40redhat.com&ctz=Europe/London

JBoss, a Division of Red Hat
Registered in England and Wales under Company Registration No. 03798903
Directors:Michael Cunningham (US), Charles Peters (US), Matt Parson
(US), Paul Hickey (Ireland)



_______________________________________________
jbossdeveloper mailing list
jbossdeveloper@lists.jboss.org <mailto:jbossdeveloper@lists.jboss.org>
https://lists.jboss.org/mailman/listinfo/jbossdeveloper

Paul.

--
Paul Robinson
JBoss Developer Team Lead (www.jboss.org <http://www.jboss.org>)

Free/busy
info: https://www.google.com/calendar/embed?src=probinso%40redhat.com&ctz=Europe/London

JBoss, a Division of Red Hat
Registered in England and Wales under Company Registration No. 03798903
Directors:Michael Cunningham (US), Charles Peters (US), Matt Parson
(US), Paul Hickey (Ireland)

Paul.

-- 
Paul Robinson

JBoss Developer Team Lead (www.jboss.org)

Free/busy info: https://www.google.com/calendar/embed?src=probinso%40redhat.com&ctz=Europe/London

JBoss, a Division of Red Hat
Registered in England and Wales under Company Registration No. 03798903
Directors:Michael Cunningham (US), Charles Peters (US), Matt Parson (US), Paul Hickey (Ireland)

_______________________________________________
jbossdeveloper mailing list
jbossdeveloper@lists.jboss.org
https://lists.jboss.org/mailman/listinfo/jbossdeveloper