Skip to content

Commit

Permalink
adding more documentation about contributing and pointer to clojars r…
Browse files Browse the repository at this point in the history
…elease
davegolland committed Apr 1, 2014

Verified

This commit was created on GitHub.com and signed with GitHub’s verified signature. The key has expired.
1 parent 5950940 commit 107eb47
Showing 2 changed files with 48 additions and 8 deletions.
17 changes: 17 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
# Contributing

Contributions to fnhouse are very welcome.

Please file bug reports on [GitHub](https://github.com/prismatic/fnhouse/issues).

For questions, feature requests, or discussion, please post on the Plumbing [mailing list](https://groups.google.com/forum/#!forum/prismatic-plumbing) for now.

Contributions are preferred as GitHub pull requests on topic branches. If you want to discuss a potential change before coding it up, please post on the mailing list.

Fnhouse is relatively well-tested. Before submitting a pull request, we ask that you:

* please try to follow the conventions in the existing code, including standard Emacs indentation, no trailing whitespace, and a max width of 95 columns
* rebase your feature branch on the latest master branch
* ensure any new code is well-tested, and if possible, any issue fixed is covered by one or more new tests

To run the tests, run `lein test :all` in the root directory of the project.
39 changes: 31 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,11 @@
![fnhouse!](https://raw.github.com/wiki/prismatic/fnhouse/images/fnhouse.jpg)

Leiningen dependency (Clojars): `[prismatic/fnhouse "0.1.0"]`

**This is an alpha release. The API and organizational structure are
subject to change. Comments and contributions are much appreciated.**


fnhouse
=======

@@ -23,9 +30,9 @@ Here is an example fnhouse handler:
This handler is implemented in terms of a keyword function (`defnk`) introduced in
the [Plumbing](https://github.com/Prismatic/plumbing) library.
Using [Schema](https://github.com/Prismatic/schema), fnhouse
handlers can specify the type of their input arguments: in the example above, `body` is declared to be of type `Entity`.
handlers can specify the type of their input arguments: in the example above, `body` is declared to be of type `EntryData`.
The handler explicitly declares the resources on which it depends: `guestbook`.
The Schema annotations on the arguments to the handler allow for
The Schema annotations on the arguments to the handler allow for
schema checking to validate that the inputs have the right structure.


@@ -34,7 +41,7 @@ The entirety of fnhouse consists of a small number of files
that play nicely together, but can be easily substituted, if need be.
To see an example use of fnhouse, check out guesthouse, the guestbook example.

## schemas.clj
### schemas.clj

Defines Schemas for `Handlers` and `HandlerInfo`.
The `HandlerInfo`
@@ -48,7 +55,7 @@ It specifies:
- source map information specifying the source code location where the handler is defined
- optionally it can also specify additional, arbitrary, user-defined annotations

## handlers.clj
### handlers.clj

Defines `nss->handlers-fn`, which
takes a map from path prefix string to namespace symbol.
@@ -59,7 +66,7 @@ takes a map from path prefix string to namespace symbol.
(which is just a sequence of `schemas/AnnotatedHandlers` -- a handler function paired with `HandlerInfo` that describes it).


## middleware.clj
### middleware.clj

Defines the `coercion-middleware` function, which takes an `AnnotatedHandler`, an
input-coercer, and an output coercer. These coercers are functions from schema
@@ -72,13 +79,13 @@ a long schema), and outputs will be clientized to match the output schemas as
specified by the output-coercer. If custom coercion is not needed, (constantly
nil) can be passed as a no-op coercer.

## routes.clj
### routes.clj

Defines the `root-handler` function, which takes a seq of `AnnotatedHandler`s, and
returns a single handler that routes the request to the appropriate handler
while binding `:uri-args` in the request to the appropriate path segments.

## docs.clj
### docs.clj

A proof of concept, ultra-primitive HTML doc generation from a fnhouse API spec,
including schemas and per-namespace handler doc pages.
@@ -88,7 +95,7 @@ It also defines a handler `$:page$GET` that can serve up the HTML
generated by the `all-docs` function.


# Example: Guesthouse
## Example: Guesthouse

The [guesthouse example](examples/guesthouse),
demonstrates how each of the components of fnhouse can be used in order to generate a
@@ -103,3 +110,19 @@ webserver look at the `start-api` method of
[core.clj](examples/guesthouse/src/guesthouse/core.clj).
To see `start-api` in action, check out the corresponding
[core_test.clj](examples/guesthouse/test/guesthouse/core_test.clj).

# Community

Please feel free to join the Plumbing [mailing list](https://groups.google.com/forum/#!forum/prismatic-plumbing) to ask questions or discuss how you're using Schema.

For announcements of new releases, you can also follow on [@PrismaticEng](http://twitter.com/prismaticeng) on Twitter.

We welcome contributions in the form of bug reports and pull requests; please see `CONTRIBUTING.md` in the repo root for guidelines.

# Supported Clojure versions

Fnhouse is currently supported on Clojure 1.5.1.

# License

Copyright (C) 2013 Prismatic and Contributors. Distributed under the Eclipse Public License, the same as Clojure.

0 comments on commit 107eb47

Please sign in to comment.