New Developer Documentation

[Bron Gondwana]

So as we keep running into the same problems over and over again for new people, it becomes obvious that we need to document the process for a new developer to get from zero to first accepted commit.

I'll work with Nicola on this tomorrow as well, but here's a rough overview of the bits that I want to cover.

Overview: the components

* Cyrus IMAPd: https://git.cyrus.foundation/diffusion/I/
* Cyrus SASL: https://git.cyrus.foundation/diffusion/S/
* Cassandane: https://git.cyrus.foundation/diffusion/C/
* Caldav Tester: http://calendarserver.org/wiki/CalDAVTester
* IMAPTest: http://www.imapwiki.org/ImapTest
* Arcanist / phabricator integration

Dependencies / Pre-requisite:

* Debian / Ubuntu
* Fedora / Redhat

Running a basic server:

What I want to do here is get you up and running with a local instance of Cyrus with a basic incoming and outgoing mail flow.  I don't care if it's a docker image with everything else and a checkout of a point in time, but it would be great to have everyone with a "real" environment that you can run a Cyrus master build in and actually use as an email / caldav / carddav server with all the bits and pieces.

* setting up sasl auth daemon
* setting up SSL certificates
* setting up lmtp daemon delivery
* setting up imapd / pop3d to listen

More than basic:

* Event Source (we need a listener that just logs events to syslog)
* Murder
* Replication
* Alt Namespace / UnixHS
* Search (squat, xapian, ...)
* Split meta
* Archive partition
* Conversations
* DAV / HTTP
* ...

Gotchas:

* automake / configure versions and issues
* old dependencies
* configuration variables
* file permissions
* init scripts
* external stuff: authentication and SSL
* Perl modules and versions/paths
* install paths and finding bin/library files
* ...

Welcome to the Cyrus IMAPd source code:

* cmulocal - m4 macros for automake - used to be shared with Cyrus-SASL
* configure.ac - automake configure template
* com_err - (system vs this one... issues)
* contrib - is anything still useful in here? (well, drydock of course)
* cunit - unit tests (still on little coverage, need more!)
* depot - looks like old testing stuff, still used?
* doc - various out-of-date documentation, also doc/internal
* imap - tons of stuff, see below
* imtest - simple program to test if authentication and SSL is set up correctly
* lib - tons of stuff, see below
* lib*.pc.in - pkgconfig files for the 3 libraries, see below
* Makefile.am - automake makefile template
* master - control program (to be called cyr_master eventually) which manages all the daemons, servers and periodic tasks for a running Cyrus instance
* netnews - programs for nntp service
* notifyd - notify protocol listener (event source and sieve notifications)
* perl - perl libraries for Cyrus, used by cyradm, managesieve client and annotator daemon
* ptclient - ldap/kerberos group fetcher (I think, I don't use it)
* sieve - sieve protocol handling - separate from lmtpd because it used to be a standalone package
* snmp - just a single shell script, collect stats (I don't use SNMP either)
* SMakefile - probably unused junk
* timsieved - again, since sieve was separate, standalone daemon for sieve protocol server
* tools - various helpers in states of disrepair

More:

* A guide to lib and imap individual files
* A guide to master
* the three libraries (libcyrus_min, libcyrus, libcyrus_sieve)
* the imap directory library (libcyrus_imap)

* configure options and why to choose them
* optional dependencies (particularly the ones which aren't upstream or aren't recent upstream - e.g. libical, xapian)

* an overview of the files that a running Cyrus creates and their formats

* an overview of the major datastructures used within the code, and how they are used

* coding style, git commit messages, all that good stuff

* how to use phabricator, git branches on github or similar, or even patches emailed to the mailing list to communicate.

* the usual open-source thing of "if your change isn't a basic part of what we were already planning, are you planning to be around to support it - and can you justify why it's in the best interests of the project to have your change included".

* meetings, IRC channels, mailing lists, how to be part of the community.

That's a rough overview for now.  I'll start fleshing out bits of this once I've had a chat to Nicola about how best to lay it out and include it into the current website.

Bron.

-- 
  Bron Gondwana
  brong at fastmail.fm