Meeting minutes 15 Feb [was Re: Meeting minutes 8 Feb]

ellie timoney ellie at fastmail.com
Mon Feb 15 18:16:59 EST 2016


> Ellie,
> Could you expand on the "complicated questions"?

I can try -- to a certain extent they're complicated cause I'm not
entirely sure how to express them to myself yet either.

It's mostly around conflicting goals and finding the least bad
compromise, I guess.

I think the main useful things we get out of the current segregated
approach are:

  * granularity of commit access
  * distinct build tools for distinct tasks
  * existing/known workflows
  * uncluttered commit histories
(sing out if there's more, I don't work on the cyrus-docs repo heavily)

And main pain points we get from it are:

  * lack of relationship between documentation and code (which version
  of the code does a version of documentation apply to? did this code
  change have a corresponding documentation change? was this
  documentation change fixing a bug in documentation, or tracking a
  change in behaviour? etc)
  * the need to include documentation (man pages, install docs, release
  notes, READMEs, etc) in release distributions that is, increasingly,
  authoritatively managed in the cyrus-docs repository
  * the need to include documentation (some install docs) on the website
  that is authoritatively managed in the cyrus-imapd repository
  * the need to include documentation (some man pages) on the website
  that is auto-generated from source in the cyrus-imapd repository
(anything else?)

And I guess what we want from combining the two repositories is:

  * resolution of some/all of the pain points
  * minimal introduction of new pain points
  * hopefully some way to keep some of the useful aspects

I did a little research yesterday into some of our options for combining
the two repositories into one.  There's a few:

1) just add the current cyrus-docs files to the cyrus-imapd repository
2) use a subtree merge to bring cyrus-docs and its history into
cyrus-imapd
3) keep the cyrus-docs repository separate, but add it to the
cyrus-imapd repository as a submodule
4) something similar to a subtree merge, but manually
(probably something else?)

Note that no matter which approach we take here, there'll be a
non-trivial piece of work in integrating the build systems.  I'm pretty
comfortable that I can manage this -- I seem to have spent a fair bit of
time wrangling our autoconf setup so far -- it'll just be fiddly, and
therefore not quickly finished.

With option 1 we would lose the commit history of cyrus-docs; I'm
assuming that's unacceptable.  Otherwise, it's the least complicated
option.

With option 2 we keep the commit history of cyrus-docs, with some
caveats: as I understand it, tracing the history is difficult/fiddly
(but not impossible)

With option 3, we keep most of the benefits of the segregated
repositories.  I'm led to believe submodules are
kind of a pain to work with, but I suspect that can be encapsulated with
some custom tooling + maintainer-mode-only autoconf rules, and will
hopefully not bleed over into normal development/documentation
workflows.  We wouldn't really gain a clear relationship between doc
revisions/code revisions, but we also don't have that now.

With option 4, we might be able to get a clearer/more coherent history
than with a subtree merge, but we also might not.  I picture this
involving an index-filter to move the cyrus-docs files into a unique
subdirectory, plus some remote juggling and a big merge.  I'm not
entirely clear how this differs from a subtree merge, but some stack
overflow discussions sort of implied that it does and that under some
circumstances this was preferable.

There's more research required (like, actually trying out the different
merge types to see what happens in practice) before I could conclusively
recommend one way or another.  I haven't done this sort of thing before,
has anyone else?

Part of me is leaning towards option 3, except that like 80% of what
I've ever heard about submodules could be summarised as "considered
harmful", and I have no experience with them myself to counterbalance
that.

But the really fiddly thing here is always going to be the fact that we
need to build most of the man pages from rst files, but we need to build
some of them (and thus their corresponding web pages...) from imapd
source files.  Taken broadly, i.e. treating "man pages" as a homogenous
collection, that's a cyclical dependency.  Squishing it all together
(options 1, 2, 4) makes that relatively easy to resolve just with
autoconf, but option 3 will need tooling/process work.

Cheers,

ellie

On Tue, Feb 16, 2016, at 01:15 AM, Nic Bernstein via Cyrus-devel wrote:
> On 02/15/2016 05:34 AM, Nicola Nye via Cyrus-devel wrote:
> > Nicola
> > <...>- Next task: look at integrating the docs repo into the source 
> > repo so that we can single-source things like man pages into man files 
> > for release packaging as well as html for the website.
> >
> > Ellie
> > - Been thinking about implications of merging docs/source repos, Has 
> > uncovered some complicated questions with no clear answers yet.
> 
> Ellie,
> Could you expand on the "complicated questions"?
> 
> I spent some time last week working my way through the mailing list 
> traffic from the past several months, and getting my head back into 
> Cyrus space.  The new stuff on cyrusimap.org looks good.  Now I'm trying 
> to figure out how and where I can jump back in to this whole squirrelly 
> docs project.
> 
> Yours,
>      -nic
> 
> -- 
> Nic Bernstein                             nic at onlight.com
> Onlight Inc.                              www.onlight.com
> 6525 W Bluemound Rd., Ste 24              v. 414.272.4477
> Milwaukee, Wisconsin  53213-4073          f. 414.290.0335
> 


More information about the Cyrus-devel mailing list