Mailing-List: contact dev-help@brooklyn.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@brooklyn.apache.org
From: Alex Heneveld <alex.heneveld@cloudsoftcorp.com>
Subject: Re: New `website` branch in brooklyn-docs
To: dev@brooklyn.apache.org
References: <CABQFKi0ceGfWH6cWkA65Qiq2WoGMUPT=ybUe0UwS26uKL4gHxA@mail.gmail.com>
 <98179534-c6ae-67f3-20e1-9493e4fe2a0a@CloudsoftCorp.com>
 <CABKEZSZyf2kz70rL6BQ=dGqMzTbHsrYLQZk-FGXvd_LezfTTXA@mail.gmail.com>
 <CABQFKi3Eh6+xP+JzOhG1Y6FdXyoTnR8i=gBrBWXENybuB6uV2w@mail.gmail.com>
Message-ID: <f39014a2-bd0b-cf76-be76-e3d76baff880@CloudsoftCorp.com>
Date: Wed, 1 Nov 2017 12:26:28 +0000
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.12; rv:45.0)
 Gecko/20100101 Thunderbird/45.5.1
MIME-Version: 1.0
In-Reply-To: <CABQFKi3Eh6+xP+JzOhG1Y6FdXyoTnR8i=gBrBWXENybuB6uV2w@mail.gmail.com>
Content-Type: text/plain; charset=utf-8; format=flowed
Content-Transfer-Encoding: 7bit
archived-at: Wed, 01 Nov 2017 12:26:42 -0000


Richard, All-

I think it's wrong to split user guide and other parts of the web site.

I don't see a good reason for it apart from us liking more bifurcations 
along technology lines (and these are evolving).  I don't see why 
sub-dirs aren't appropriate or are difficult.  (And was it really 
necessary to abandon the subdirs in order to support gitbooks?)

To me, `brooklyn-docs` is the canonical collection of resources that 
explain Brooklyn - what it is, how to use it, examples, reference, etc.  
The user experiences this through our web site. It is a coherent piece.  
The guide is a large chunk of this which has some unique aspects -- it 
is built differently (gitbooks, and generates PDF) and we maintain old 
versions of it (but not the website) but that is it.  To me that's not 
sufficient justification for the weight and tedium of a separate project.

Our project divisions should be things that are easily explained to new 
people coming to the website.  Explaining the difference between "guide" 
and "other-things-on-the-site" at this level is a bit obscure and 
certainly not important.  A division makes things harder for a casual 
contributor wanting to fix something (they have to know that difference 
and grep in two projects/branches). It also as noted makes it harder for 
us to add docs re features if these need to be done in two places.  
Thomas says we know how to have multiple PRs but they are still irritating!

Finally:  the lifecycle of the two IS pretty much the same as I see it.  
There are two classes of changes:

    * new features - these only apply the next release, so are not 
published - normal workflow is to push to master and not publish

    * fixes and non-code enhancements (eg listing new members) - these 
apply to the next release and the current version (and in the case of 
guide possibly older versions though updating this is less important) - 
normal workflow is to push to master branch and last-released branch, 
then publish last-released branch

These are the SAME for guide and for non-guide website content. The idea 
that we only have one branch for website feels wrong, as it either 
discourages non-guide updates for new features, or it risks publishing 
these updates before they make it in to a released version.  Efforts in 
that direction will backfire and make the risks Richard speaks of (wrong 
content live on our website) more likely IMO.  The one version 
difference is that older versions of the guide are included when 
publishing whereas older versions of non-guide content is not, but 
scripts take care of that, and it's a detail most users and developers 
don't need to know about it, so it doesn't seeem a good reason to 
introduce a project boundary.

So... if the publish/version lifecycle is the same, and change sets to 
both are common, and they make a coherent piece, then focussing on this 
dichotomy and splitting up the projects seems unfriendly to doc 
consumers and to contributors -- and these should be the primary audience.

Best
Alex


On 31/10/2017 15:19, Richard Downer wrote:
> Hi Alex, Mark, sorry for the late reply.
>
> Alex - you make fair points. It does somewhat obscure the location of the
> website and complicate raising PRs.
>
> I think that a separate repo is probably the best long-term solution, but I
> didn't want to rush into it - creating repos is cheap (Infra can do that
> relatively easily) but deleting repos is nearly impossible for legal policy
> reasons. So I wanted to make sure we were making the right decision for a
> docs/website split before we commit to a separate repo.
>
> I'm not convinced of your argument about website_0.12 etc. IMO the website
> has a lifecycle which is independent of releases and as a general rule
> there should only ever be one website branch. Having multiple copies of the
> website on different branches with content for different purposes is a
> recipe for confusion. Such confusion risks updates on the website appearing
> and disappearing when the site is regenerated different branches, either
> accidentally or when content is not merged to all appropriate branches. If
> we do want to have a holding space for "v.Next" content on the main site,
> then I think there are other ways of handling this.
>
> Could I suggest we remain with the current setup (different branch in docs
> repo) for the short term, until we are absolutely happy with our new
> arrangement, and then switch to a new brooklyn-website repo (or alternative
> if we don't like the new arrangement)? My thoughts are that this would
> happen once we've made a 1.0 release and tested out all the process, or to
> set a deadline if a 1.0 release starts getting pushed out, but I'm happy to
> hear thoughts on this.
>
> Richard.
>
>
> On 27 October 2017 at 10:15, Mark McKenna <m4rkmckenna@apache.org> wrote:
>
>> Richard , Alex
>>
>> I think its fine on a branch short term (few weeks)
>>
>> I think we should follow the pattern from other projects and split our
>> website into its own repository.
>>
>> Alex I think the technology of the website and the docs should diverge ie
>> we choose the best technology for each.
>>
>> RE PRs ... splitting the site / docs makes the most sense as we deal with
>> making prs across Brooklyn's numerous repositories
>>
>>
>> Mark
>>
>>
>>
>> On 27 October 2017 at 09:01, Alex Heneveld <alex.heneveld@cloudsoftcorp.
>> com>
>> wrote:
>>
>>> Sorry - I really don't like website being hidden on a branch.
>>>
>>> Why?
>>>
>>> * It's non-obvious and one more thing to remember (or forget, or explain)
>>> * Primary reason for branching (in my view) is lifecycle, and here the
>> two
>>> have very similar versioning and release lifecycles: master for both will
>>> be relevant to master of codebase, where eg v0.12.0 will be relevant to
>>> last release of 0.12.0 and what is live; there will be times we want to
>>> update what is live with something more reason relevant to that version,
>>> but we'll do that by pushing to 0.12, and we can release (publish) that
>>> immediately unlike code, but what we _can't_ assume for both is that
>> master
>>> can always be published, because we may have added unreleased features to
>>> docs for both site and guide; with site in a `website` branch we will
>> have
>>> to have branches there eg `website_0.12` alongside `0.12` of guide
>>> * PRs become more difficult, remembering which branch to open them
>> against
>>> and merge against
>>> * PRs become even more difficult if adding a feature which goes onto both
>>> the site and into the docs (which we should do more of), we add to one
>>> branch, switch branches add to the other, then open PRs for both branches
>>> * Ideally they converge to use the same technology (not both gitbook and
>>> markdown) so if in the same project they can share themes and utils etc;
>> if
>>> in different branches we have to cherry-pick between branches (always
>>> opening and reviewing 2 identical PRs!)
>>>
>>> My ideal would be different subdirs but if they really need to be
>> separate
>>> then we could do a different project (resolves reasons 1 2 3 and
>> improves 4
>>> and 5)
>>>
>>> Best
>>> Alex
>>>
>>>
>>>
>>> On 26/10/2017 14:04, Richard Downer wrote:
>>>
>>>> All,
>>>>
>>>> Following on from Thomas's gitbook work[1] - now merged[2] - it means
>> that
>>>> the brooklyn-docs `master` branch does not contain the public website
>>>> (just
>>>> the documentation).
>>>>
>>>> In those threads it was discussed that most branches would remove the
>>>> website, and a separate branch would be used to store the public website
>>>> (a
>>>> bit like how GitHub pages used a `gh-pages` branch for a repository's
>>>> publis website). I'm assuming that the acceptance and merging of
>> gitbooks
>>>> is passive consensus of this concept too.
>>>>
>>>> Therefore, I've created a new branch in the Apache brooklyn-docs repo
>>>> called `website`, which is taken from `master` immediately prior to the
>>>> merge of the gitbook conversion.
>>>>
>>>> If anybody disagrees with this passive consensus approach and thinks
>> that
>>>> this branch is a bad idea, then please feel free to speak up. After all,
>>>> source control means that things can always be undone :-)
>>>>
>>>> Expect a forthcoming PR on the `website` branch to remove the
>>>> documentation
>>>> files and leave just the website files (like the opposite of Thomas's
>> PR).
>>>> Richard.
>>>>
>>>> [1]
>>>> https://lists.apache.org/thread.html/760a3e2fdefaff8d8ac4ea3
>>>> f98a45060fbaa0d886fa57c8f44e4742e@%3Cdev.brooklyn.apache.org%3E
>>>> [2] https://github.com/apache/brooklyn-docs/pull/222
>>>>
>>>> ---------- Forwarded message ----------
>>>> From: <richard@apache.org>
>>>> Date: 26 October 2017 at 13:50
>>>> Subject: [brooklyn-docs] Git Push Summary
>>>> To: commits@brooklyn.apache.org
>>>>
>>>>
>>>> Repository: brooklyn-docs
>>>> Updated Branches:
>>>>     refs/heads/website [created] e1d08e53c
>>>>
>>>>