From probinso at redhat.com Wed Sep 23 06:57:29 2015 From: probinso at redhat.com (Paul Robinson) Date: Wed, 23 Sep 2015 06:57:29 -0400 Subject: [jbossdeveloper] Updating quickstarts documentation between releases In-Reply-To: References: <705F5D1A-1E93-455E-92F3-3214A830C01A@redhat.com> <54AD43B7.3090705@redhat.com> <54B49EBF.90703@redhat.com> <7E48CC0E-C28B-4944-94DE-64394F3EB078@redhat.com> <54B6948C.4000409@redhat.com> Message-ID: 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 wrote: > > On 14 Jan 2015, at 16:08, Paul Gier wrote: > > On 01/13/2015 02:36 AM, Paul Robinson wrote: > > > On 13 Jan 2015, at 04:27, Paul Gier >> 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/ > > >. > 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 > >) > > 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 > 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) > > > > 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) -------------- next part -------------- An HTML attachment was scrubbed... URL: http://lists.jboss.org/pipermail/jbossdeveloper/attachments/20150923/fc80f028/attachment-0001.html From sgilda at redhat.com Wed Sep 23 07:03:36 2015 From: sgilda at redhat.com (Sande Gilda) Date: Wed, 23 Sep 2015 07:03:36 -0400 Subject: [jbossdeveloper] Updating quickstarts documentation between releases In-Reply-To: References: <705F5D1A-1E93-455E-92F3-3214A830C01A@redhat.com> <54AD43B7.3090705@redhat.com> <54B49EBF.90703@redhat.com> <7E48CC0E-C28B-4944-94DE-64394F3EB078@redhat.com> <54B6948C.4000409@redhat.com> Message-ID: <56028708.4050403@redhat.com> 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 > > wrote: > > >> On 14 Jan 2015, at 16:08, Paul Gier > > wrote: >> >> On 01/13/2015 02:36 AM, Paul Robinson wrote: >>> >>>> On 13 Jan 2015, at 04:27, Paul Gier >>> >>>> > 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/ >>>>>> >>>>>> >>>>>> . >>>>>> 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 >>>>>> >>>>> >) >>>>>> >>>>>> 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 >>> 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) >>> > > > 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) -------------- next part -------------- An HTML attachment was scrubbed... URL: http://lists.jboss.org/pipermail/jbossdeveloper/attachments/20150923/10c3ef5c/attachment-0001.html From probinso at redhat.com Wed Sep 23 07:11:05 2015 From: probinso at redhat.com (Paul Robinson) Date: Wed, 23 Sep 2015 07:11:05 -0400 Subject: [jbossdeveloper] Updating quickstarts documentation between releases In-Reply-To: <56028708.4050403@redhat.com> References: <705F5D1A-1E93-455E-92F3-3214A830C01A@redhat.com> <54AD43B7.3090705@redhat.com> <54B49EBF.90703@redhat.com> <7E48CC0E-C28B-4944-94DE-64394F3EB078@redhat.com> <54B6948C.4000409@redhat.com> <56028708.4050403@redhat.com> Message-ID: Thanks Sande, I believe Jason has this list of changes. Paul. On Wed, Sep 23, 2015 at 7:03 AM, Sande Gilda 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 > wrote: > >> >> On 14 Jan 2015, at 16:08, Paul Gier wrote: >> >> On 01/13/2015 02:36 AM, Paul Robinson wrote: >> >> >> On 13 Jan 2015, at 04:27, Paul Gier > >> 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/ >> >> > >. >> 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 >> >) >> >> 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 >> 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) >> >> >> >> 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