Re: [jbossdeveloper] Updating quickstarts documentation between releases

On 14 Jan 2015, at 16:08, Paul Gier <pgier(a)redhat.com&gt; wrote: On 01/13/2015 02:36 AM, Paul Robinson wrote: > >> On 13 Jan 2015, at 04:27, Paul Gier <pgier(a)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/CO.... >>>> 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/... >>> >>> 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/... >>> >>> 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...) >>>> 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=E... >>>> >>>> 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(a)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=E... > > 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) >