Unifying the Cyrus World

Patrick Goetz pgoetz at mail.utexas.edu
Sun Dec 27 09:45:34 EST 2015


Was this issue ever resolved?  I'm still finding the documentation split 
between cyrus.foundation and cyrusimap.org, and it's incomplete in both 
places.

On 09/16/2015 08:50 PM, Nicola Nye wrote:
> Dear Cyrus folks,
> After nominally completing the migration of the docs from the wiki at
> cyrusimap.org onto the sphinx repository at docs.cyrus.foundation, I
> worked out there was a whole bunch of existing services at cyrusimap.org
> that were non-trivial to relocate. Which, after some discussion at the
> Cyrus hangout, we felt that retaining cyrusimap.org as our primary (and
> sole) presence made more sense.
> Equally, there are some documentation issues that are affected by our
> current straddling of two worlds. Read on for a discussion of the issues
> and down to the options and recommendation.
> I'd love to have your input (particularly Nic Bernstein on the docs
> angle!) if you agree or disagree so we can make for a more unified Cyrus
> presence.
> *Issues*
> 1) Branding
> We are currently split across two internet presences: cyrus.foundation
> and cyrusimap.org. This is confusing. We should only have one.
> The cyrus.foundation domain name is not of real use as there is a
> pre-existing entity (The Cyrus Foundation) of the same name.
> Swapping our internet domain name presence from cyrusimap.org to
> cyrus.foundation is no longer a significant driver as a result,
> especially as cyrusimap.org is already indexed and linked to around the
> net and is unambiguous. (Yes, Cyrus does so much more than just imap,
> but it's the primary association)
> Currently services are split across the two domains - git repos,
> phabricator and authoritative online docs on cyrus.foundation, while
> downloads, bugzilla and generated docs are on cyrusimap.org.
> 2) Docs logistics
> The docs repo is separate to source which is causing friction keeping
> man pages updated.
> We want man pages in two formats: *nix for actual man pages to ship and
> install with cyrus, and html for web presentation.
> Nice to have: ship a snapshot of all current docs (not just man pages)
> along with source distribution.
> 3) Sphinx vs wiki
> We have been working towards making the content on cyrus.foundation to
> be the most up to date. This is using Sphinx, which allows us to
> generate, from the same source, man pages as well as web pages. (And
> even pdf or single page html). So we get nicer output format options.
> Clearer history in the git log than you get from wiki.
> Cyrusimap docs are held in mediawiki. Not so great for man pages. But
> it's much easier for third party contributor to pitch in and help out:
> they don't need to learn rst, they don't need a phabricator account,
> they don't need to navigate git.
> *Possible solutions*
> In all cases it seems clear that we should stop using the
> cyrus.foundation domain and ideally services that are hosted there be
> shifted to live alongside cyrusimap.org for ease of access.
> There are a number of @cyrus.foundation email accounts that would need
> to be dealt with for Chris Davies' testing.
> Option 1: Single domain, unify git repos, use sphinx everywhere
> --------------------------------------------------------------------------------
> Moving the git repo to cyrusimap (or anywhere) isn't hard. (a job for Bron)
> Get rid of separate cyrus-docs repo. Put cyrus-docs stuff back inside
> cyrus-imapd/docs for easier man page generation and tagging of docs
> versions with source, and shipping of current docs with source.
> Put sphinx on cyrusimap to replace the wiki. This requires either:
>
>  1.
>     working out how to set up the existing generated docs for use with
>     sphinx,
>  2.
>     or make all the stuff in cyrus-imapd/doc into rst so it works with
>     sphinx. We can still ship the built html.
>
> Option 2: Single domain, unify git repos, use wiki for docs
> -----------------------------------------------------------------------------
> Put sphinx on cyrusimap.org just for generating man page html. Leave the
> existing wiki where it is for documentation. (Requires porting the page
> updates I made from cyrus.foundation onto the wiki).
> This means the only thing left in the cyrus-docs git repo would be the
> man pages, at which point it makes more sense to put them back into the
> cyrus-source repo.
> We can still ship docs with the release if we tie in a wiki export into
> the release-building process. (A job for Ellie and I)
> Option 3: Single domain, separate git repos, use sphinx for docs
> ----------------------------------------------------------------------------------
> Move all services to cyrusimap.org, but still leaves us with all the
> docs logistics and sphinx and wiki chafe points. Not recommended.
> *Recommendation*
> I am leaning towards suggesting option 2. Anything that makes
> documentation support easier is a good! But we'd still like to retain
> the usefulness of sphinx for generating two output formats from single
> source man pages.
> *What Now?
> *
> Discuss! I imagine those folks who come to the Hangout in the next few
> meetings will kick it around and we'll come to a decision next week.
>     Nicola


More information about the Cyrus-devel mailing list