[jbossdeveloper] Updating quickstarts documentation between releases

[Sande Gilda]

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-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?
>
> Is this the right thing to do?
>
> 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
> https://lists.jboss.org/mailman/listinfo/jbossdeveloper

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.jboss.org/pipermail/jbossdeveloper/attachments/20150107/077d76b0/attachment.html