<div dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote">On Wed, Dec 6, 2017 at 12:07 PM, Laura Fitzgerald <span dir="ltr"><<a href="mailto:lfitzger@redhat.com" target="_blank">lfitzger@redhat.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr">Hi all,<div><br></div><div>I have recently gone through the process of publishing documentation for AeroGear Digger to <a href="http://aerogear.org" target="_blank">aerogear.org</a>.</div><div><br></div><div>The process for adding docs for digger was as follows:</div><div><br></div><div>- Make changes on Feature Branch over a period of time.</div><div>- At some point merge lots of commits (difficult to review) from Feature Branch to master.</div><div>- This publishes to <a href="http://staging.aerogear.org" target="_blank">staging.aerogear.org</a> (build needs to be manually triggered in Jenkins)</div><div>- At some point merge master (again with lots of commits) to production branch</div><div>- This publishes to <a href="http://aerogear.org" target="_blank">aerogear.org</a> (build needs to be manually triggered)</div><div><br></div><div>Out of this we attempted to improve the process by adding development steps to the README [1] outlining that </div><div>-> each change should be verified on it's own -> merged to master -> and then merged to production</div><div>removing the wait time and merges which involved lots of commits and changes.</div><div><br></div><div><b>I think there are a few things we can do to make this better. (simpler)</b></div><div><br></div><div><i>1) How?</i></div><div><br></div><div>Remove the production branch (and related steps) altogether. </div><div><br></div><div><i>Why?</i></div><div><br></div><div>- All this documentation is done in the open. </div><div>- All branches are visible to all users/developers. </div><div>- <a href="http://staging.aerogear.org" target="_blank">staging.aerogear.org</a> is not private so I don't see that we gain something by having this step.</div></div></blockquote><div><br></div><div>it was usful when preparing new looks or new contents (e.g. redesign / new releases with new contents)</div><div><br></div><div><br></div><div>but I am fine having all that live, or on branches - there is no problem viewing ascii doc via GH </div><div><br></div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><div>- Changes can be verified locally by building the website using the steps in the README [2] before being merged to master.</div><div><br></div><div><i>2) How?</i></div><div>Automate the publishing of the site</div><div><br></div><div><i>Why?</i></div><div>Right now the building of the site has to be triggered manually via a Jenkins instance on cloudbees. If we remove production and enforce that all changes are fully verified before being merged to master then we can automate that any new changes are published immediately once merged to master.</div><div><br></div><div><i>3) How?</i></div><div>Add some sort of versioning to the documentation. This could be in the form of tagging the repo once we have a release of a product.</div><div><br></div><div><i>Why?</i></div><div>If we are always publishing docs once a change is made to the product then we should version the documentation so we know which version of the docs matches older versions of the product.</div><div><br></div><div>~~~~~~~~~~~</div><div><br></div><div>I'm really interested in some feedback on this. Let me know what you think. Is there a better/simpler way to do it than I suggested?</div></div></blockquote><div><br></div><div><br></div><div>generally +1 on this move</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><div><br></div><div><div>[1] <a href="https://github.com/aerogear/aerogear.org/blob/master/README.md#development-steps" target="_blank">https://github.com/<wbr>aerogear/aerogear.org/blob/<wbr>master/README.md#development-<wbr>steps</a></div><div>[2] <a href="https://github.com/aerogear/aerogear.org/blob/master/README.md#building" target="_blank">https://github.com/<wbr>aerogear/aerogear.org/blob/<wbr>master/README.md#building</a></div>-- <br><div class="m_-7851608390867779307gmail_signature"><div dir="ltr"><div><div dir="ltr"><div dir="ltr"><div dir="ltr"><br><p style="color:rgb(0,0,0);font-family:overpass,sans-serif;font-weight:bold;margin:0px;padding:0px;font-size:14px;text-transform:uppercase"><span>LAURA</span> <span>FITZGERALD</span></p><p style="font-family:overpass,sans-serif;margin:0px;font-size:10px;color:rgb(153,153,153)"><a href="https://www.redhat.com/" style="color:rgb(0,136,206);margin:0px;text-decoration:none" target="_blank">Red Hat <span>Mobile</span></a></p><span style="font-family:overpass,sans-serif;font-size:10px;margin:0px;color:rgb(153,153,153)"><p style="margin:0px">Communications House, Cork Road</p></span><span style="color:rgb(0,0,0);font-family:overpass,sans-serif;font-size:medium"></span><span style="color:rgb(0,0,0);font-family:overpass,sans-serif;font-size:medium"><p style="font-size:10px;margin:0px;color:rgb(153,153,153)">Waterford City, Ireland X91NY33</p></span><span style="color:rgb(0,0,0);font-family:overpass,sans-serif;font-size:medium"></span><p style="font-family:overpass,sans-serif;margin:0px 0px 6px;font-size:10px;color:rgb(153,153,153)"><span style="margin:0px;padding:0px"><a href="mailto:lfitzger@redhat.com" style="color:rgb(0,136,206);margin:0px;text-decoration:none" target="_blank">lfitzger@redhat.com</a> </span> <span>IM: <span>lfitzgerald</span></span></p><table border="0" style="color:rgb(0,0,0);font-family:overpass,sans-serif;font-size:medium"><tbody><tr><td width="100px"><a href="https://red.ht/sig" target="_blank"><img src="https://www.redhat.com/files/brand/email/sig-redhat.png" width="90" height="auto"></a></td></tr></tbody></table><table border="0" style="color:rgb(0,0,0);font-family:overpass,sans-serif;font-size:medium"><tbody><tr><td width="100px"><br></td></tr></tbody></table></div></div></div></div></div></div>
</div></div>
<br>______________________________<wbr>_________________<br>
aerogear-dev mailing list<br>
<a href="mailto:aerogear-dev@lists.jboss.org">aerogear-dev@lists.jboss.org</a><br>
<a href="https://lists.jboss.org/mailman/listinfo/aerogear-dev" rel="noreferrer" target="_blank">https://lists.jboss.org/<wbr>mailman/listinfo/aerogear-dev</a><br></blockquote></div><br><br clear="all"><div><br></div>-- <br><div class="gmail_signature" data-smartmail="gmail_signature"><div dir="ltr"><div>Matthias Wessendorf <br><br>blog: <a href="http://matthiaswessendorf.wordpress.com/" target="_blank">http://matthiaswessendorf.wordpress.com/</a><br>twitter: <a href="http://twitter.com/mwessendorf" target="_blank">http://twitter.com/mwessendorf</a></div></div></div>
</div></div>