From 107eb47acacaf15361d2ae3166f4da607b7df528 Mon Sep 17 00:00:00 2001 From: davegolland Date: Tue, 1 Apr 2014 11:22:22 -0700 Subject: [PATCH] adding more documentation about contributing and pointer to clojars release --- CONTRIBUTING.md | 17 +++++++++++++++++ README.md | 39 +++++++++++++++++++++++++++++++-------- 2 files changed, 48 insertions(+), 8 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..e2dbc46 --- /dev/null +++ b/CONTRIBUTING.md @@ -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. diff --git a/README.md b/README.md index 9ddb788..326c3e9 100644 --- a/README.md +++ b/README.md @@ -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.