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 <m4rkmcke...@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: <rich...@apache.org>
Date: 26 October 2017 at 13:50
Subject: [brooklyn-docs] Git Push Summary
To: comm...@brooklyn.apache.org
Repository: brooklyn-docs
Updated Branches:
refs/heads/website [created] e1d08e53c
