[jbossdeveloper] Updating quickstarts documentation between releases

[Paul Gier]

On 01/13/2015 02:36 AM, Paul Robinson wrote:
> 
>> On 13 Jan 2015, at 04:27, Paul Gier <pgier at redhat.com
>> <mailto:pgier at 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.

> 
>>
>>>>
>>>> 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 at lists.jboss.org <mailto:jbossdeveloper at 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)
>