On 02/15/2016 03:16 PM, ellie timoney via Cyrus-devel wrote:
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 n...@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
As a consumer, I'd like to say a couple of things.
1. I really REALLY don't want to see it become difficult, on my end, to
get the right versions of the libsasl2 docs on download. Apparently
quite a few pages disappeared between 1.5.28 and 2.1.26, but those pages
still appear in other places (including Solaris, possibly-corrected for
2.N.N) I don't view them as "part of" imap.
2. I've got some severe formatting problems displaying saslauthd(8) ,
which I hope is unique to that file and not a trend. saslauthd.8
appears to be pre-roff'd, it looks like the others are not.
