darcs repository web UI and hosting app. This is the main darcsden trunk, which also runs hub.darcs.net. (http://hub.darcs.net)

root / src

Notes and conventions for darcsden developers.

File layout:

 src/                 - main files for executables
  DarcsDen/           - routes, general utilities
   Backend/           - permanent and transient backends (couchdb, redis, local files, etc)
   Handlers/          - handlers (aka "controllers")
    RepoHandlerUtils/ - helpers for repository handlers
    UserHandlerUtils/ - helpers for user handlers
   Instance/          - the `DenInstace` typeclass and instances
   Pages/             - pages (aka views/templates)
   State/             - data types, utilities, and persistence (aka models)
 web-server/          - the `darcsden` executable
 ssh-server/          - the `darcsden-ssh` executable
 test-harness/        - selenium tests
 test-http/           - wreq tests

Other directories:

 manifests/           - vagrant support
 public/              - static files for web app
 tests/               - some test data

File names:

For the most part, we keep file names unique. Sometimes this makes file names a little more verbose or redundant, but it makes things clearer and helps with code navigation. Having 4-6 files named User.hs, Repository.hs, Util.hs etc. was confusing.

Generally, we allow "repo" as a synonym for "repository" in darcsden. In file names, the short form is used, eg RepoHandlers.hs. In darcsden code, currently both forms are used. Darcs code uses the long form.

Code naming:

Handler, page, and state-related functions follow some naming conventions to keep things organised and help with navigation.

Routes are the url paths the web app responds to. They are defined and associated with handlers in Handlers.hs. Eg "login", ":user/:repo".

Handlers are the functions called to serve each route. They run in the Snap monad, and most of them take a session as their last parameter. They are defined in Handlers/*.hs. Their naming is similar to Yesod handlers: "get" or "post", a meaningful camelcase name often similar to the route, "Atom" or "Json" if the output format is either of those, and a final "R" (for Route handler). Eg getLoginR, getRepoR, postAddFileR.

Pages are the HTML or Atom output served by most handlers. They are represented internally as functions taking a session and returning a HSP XML block. These functions have names usually similar to the route and handler, followed by "P", and they use the Page type alias. The P suffix and Page type denote a complete page. Eg loginP, repoP.

Page fragments are HSP XML blocks used as part of pages. These do not use the Page type alias and their names do not end with "P" (they could end with "Html" or "Xml"). Eg issueLinks, renderIssue.