[jbossdeveloper] Updating quickstarts documentation between releases
Sande Gilda
sgilda at redhat.com
Wed Sep 23 07:03:36 EDT 2015
Hi Paul,
I'll talk to Paul Gier about the best way to do this. In the meantime,
do you have a list of changes that need to be made to the README files?
Thanks,
Sande
On 09/23/2015 06:57 AM, Paul Robinson wrote:
> I'm resurrecting this thread, as it's being discussed on:
> https://issues.jboss.org/browse/RHD-722
>
>
> On Wed, Jan 14, 2015 at 11:52 AM, Paul Robinson
> <paul.robinson at redhat.com <mailto:paul.robinson at redhat.com>> wrote:
>
>
>> On 14 Jan 2015, at 16:08, Paul Gier <pgier at redhat.com
>> <mailto:pgier at redhat.com>> wrote:
>>
>> 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>
>>>> <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.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
>>>>>> <http://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
>>>>>> <http://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
>>>>>> <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>
>>>>>> <mailto: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>
>>> <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 <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
> developers.redhat.com <http://developers.redhat.com> Lead
> JBoss Developer 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)
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.jboss.org/pipermail/jbossdeveloper/attachments/20150923/10c3ef5c/attachment-0001.html
More information about the jbossdeveloper
mailing list