Re: [jbossdeveloper] Updating quickstarts documentation between releases

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(a)redhat.com <mailto:paul.robinson@redhat.com>> wrote: > On 14 Jan 2015, at 16:08, Paul Gier <pgier(a)redhat.com > <mailto:pgier@redhat.com>> 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> >>> <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.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 >>>>> <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/... >>>> >>>> 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 >>>>> <http://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. 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=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> >>>>> <mailto: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> >> <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) >> 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) _______________________________________________ jbossdeveloper mailing list jbossdeveloper(a)lists.jboss.org <mailto:jbossdeveloper@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=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)