[jbossdeveloper] Updating quickstarts documentation between releases

Wed Sep 23 07:11:05 EDT 2015

Thanks Sande,

I believe Jason has this list of changes.

Paul.

On Wed, Sep 23, 2015 at 7:03 AM, Sande Gilda <sgilda at redhat.com> wrote:

> 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>
> wrote:
>
>>
>> On 14 Jan 2015, at 16:08, Paul Gier <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 <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.
>>
>>
>> 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 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)
>>
>>
>>
>> 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 at lists.jboss.org
>> https://lists.jboss.org/mailman/listinfo/jbossdeveloper
>>
>
>
>
> --
> Paul
>
> -----
> Paul Robinson
> developers.redhat.com Lead
> JBoss Developer 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)
>
>
>

-- 
Paul

-----
Paul Robinson
developers.redhat.com Lead
JBoss Developer 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)
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.jboss.org/pipermail/jbossdeveloper/attachments/20150923/46c6fba0/attachment-0001.html 