The ClojureWerkz Blog

News and updates about ClojureWerkz projects

Clojure Documentation Project Progress Report: The Week of October 28th

TL;DR

The Clojure documentation project continues to make progress. Lion’s share of the work this week went into the Concurrency and Parallelism in Clojure guide which is now about 75% complete.

CDS Progress Report

The Clojure Documentation Site (a.k.a. CDS) publishes periodic reports (every week so far, possibly two weeks in the future) to give the Clojure community a better idea of what CDS shapes up to be and what it has to offer.

This is a report for the week ending October 28st, 2012.

New Content

This week was all improvements to existing guides, no new content merged. There is at least one new tutorial in the works by a contributor we’ve heard from, though.

Updates

By far most of the work merged this week went into the Concurrency and Parallelism guide.

It now covers topics such as

  • An overview of concurrency terminology and common hazards
  • Identity/Value separation in Clojure
  • atoms
  • agents
  • refs
  • vars
  • delays
  • futures
  • promises
  • dereferencing
  • some commonly used java.util.concurrent bits
  • other approaches to concurrency on the JVM available to Clojure through libraries

Language-level support for concurrent programming is one of the Clojure’s design goals so reading that guide is highly recommended.

Tutorials updated this week:

Other guides updated this week:

Thank You, Contributors

CDS would not be possible without the following people who make Clojure community a better place:

  • AtKaaZ
  • Ben Poweski
  • John Gabriele
  • Lee Hinman
  • Michael S. Klishin
  • Wes Freeman

You Can Help!

How It Works

We have a repository on GitHub that has Markdown files, toolchain setup instructions and several articles as well as stubs for several more articles. The stubs help contributors pick a topic to write about and not worry too much about article structure initially. Just pick something that you are very familiar with or interested in and write.

When you are done, submit a pull request on GitHub and someone from the existing contributors team will suggest improvements or merge your work. Pretty straightforward.

In order to make it easier for potential contributors to join the project, we will post a brief list of guides that do not require deep expertise and can benefit from contributions by complete beginners.

Existing Guides

Tutorials that need work:

Guides that have structure and good chunk of the content in place but still have holes you can help us plug:

These guides are new and cover advanced topics, so we need as much proof-reading as we can get from the community:

New Content

If you want to start working on one of those articles or have existing content you’ve authored that can be ported, please let us know on the Clojure mailing list.

Summary

CDS is 2-3 guides from covering the language “reasonably well”. There still are holes in various guides but mostly in the more advanced areas and expectedly will take longer to write.

Want to help us make things better? Join us!

Michael Klishin on behalf of the Clojure Documentation Team.

Langohr 1.0-beta10 Is Released

TL;DR

Langohr is a Clojure RabbitMQ client that embraces AMQP 0.9.1 Model.

1.0-beta10 is a development release with one fix release. We recommend all users to upgrade to it.

Changes in 1.0-beta10

langohr.basic/reject now correctly uses basic.reject

langohr.basic/reject now correctly uses basic.reject AMQP method and not basic.ack.

Contributed by @natedev.

Change Log

Langohr change log is available on GitHub.

Thank You, Contributors

Langohr is a ClojureWerkz Project

Langohr is part of the group of libraries known as ClojureWerkz, together with

  • Welle, a Riak client with batteries included
  • Monger, a Clojure MongoDB client for a more civilized age
  • Neocons, a client for the Neo4J REST API
  • Elastisch, a minimalistic well documented Clojure client for ElasticSearch
  • Quartzite, a powerful scheduling library

and several others. If you like Langohr, you may also like our other projects.

Let us know what you think on Twitter or on the Clojure mailing list.

The ClojureWerkz Team

Monger 1.3.0 Is Released

TL;DR

Monger is an idiomatic Clojure MongoDB driver for a more civilized age. It has batteries included, offers powerful expressive query DSL, strives to support every MongoDB 2.0+ feature and has sane defaults. It also has solid documentation.

1.3.0 is a minor 100% backwards-compatible release that includes an important bug fix in the updated MongoDB Java driver. We recommend all users to upgrade to it as soon as possible.

Changes in 1.3.0

monger.core/disconnect!

monger.core/disconnect! closes the default database connection.

Ragtime 0.3.0

Ragtime dependency has been updated to 0.3.0.

MongoDB Java Driver Update

MongoDB Java driver dependency has been updated to 2.9.2. This includes an important concurrency bug fix: JAVA-660.

Cheshire Support

monger.json and monger.joda-time will now use Cheshire if it is available. clojure.data.json is no longer a hard dependency (but 0.1.x versions are still supported if available).

Recently released clojure.data.json version 0.2.0 completely breaks public API and is not supported. We recommend all users prefer Cheshire when possible.

ClojureWerkz Support 0.7.0

ClojureWerkz Support library is upgraded to 0.7.

Change Log

We recommend all users to upgrade to 1.3.0 as soon as possible.

Monger change log is available on GitHub.

Monger is a ClojureWerkz Project

Monger is part of the group of libraries known as ClojureWerkz, together with

  • Welle, a Riak client with batteries included
  • Elastisch, a minimalistic Clojure client for ElasticSearch
  • Neocons, a client for the Neo4J REST API
  • Langohr, a Clojure client for RabbitMQ that embraces the AMQP 0.9.1 model
  • Quartzite, a powerful scheduling library

and several others. If you like Monger, you may also like our other projects.

Let us know what you think on Twitter or on the Clojure mailing list.

@michaelklishin on behalf of the ClojureWerkz Team

Elastisch 1.0.2 Is Released

TL;DR

Elastisch is a battle tested, small but feature rich and well documented Clojure client for ElasticSearch. It supports virtually every Elastic Search feature and has solid documentation.

1.0.2 is a bug fix release. We recommend all users to upgrade to it.

Changes in 1.0.2

  • Count API now uses GET for requests without the query part (GH issue #5)
  • Count API No Longer Ignores Mapping Types (GH issue #6)

We recommend all users to upgrade to 1.0.2 as soon as possible.

Elastisch change log is available on GitHub.

Thank You, Contributors

Kudos to Vesa Marttila for reporting both issues fixed in this release.

Elastisch is a ClojureWerkz Project

Elastisch is part of the group of libraries known as ClojureWerkz, together with

  • Welle, a Riak client with batteries included
  • Monger, a Clojure MongoDB client for a more civilized age
  • Neocons, a client for the Neo4J REST API
  • Langohr, a Clojure client for RabbitMQ that embraces the AMQP 0.9.1 model
  • Quartzite, a powerful scheduling library

and several others. If you like Elastisch, you may also like our other projects.

Let us know what you think on Twitter or on the Clojure mailing list.

The ClojureWerkz Team

Clojure Documentation Project Progress Report, Oct 21th

TL;DR

The Clojure documentation project continues to progress nicely. Several guides now have more than 2/3rds of the content written and the team begins to tackle harder guides such as Concurrency and Parallelism in Clojure.

CDS Progress Report

Not so long we announced the new Clojure Documentation Site (a.k.a. CDS) effort. Now we publish periodic reports (every week so far, possibly two weeks in the future) to give the Clojure community a better idea of what CDS shapes up to be and what it has to offer.

This is a report for the week ending October 21st, 2012.

Overview

This week was spent mostly refining and expanding the material we’ve added last week. This means there are fewer commits and the diff is smaller but a lot more time went into reading and editing.

There was, however, some new content, too.

New Content

This week we started working on the first out of 3 “advanced” guides: Concurrency and Parallelism in Clojure. It is a very broad topic, with lots of material to write and some areas not-so-trivial to explain to absolute beginners. At the same time, it covers some of the key Clojure design decisions and some of the most attractive points of the language, so we are happy to work extra hard on this subject. And it’s always good to review your own understanding of concurrency by writing this content.

Updates

A number of guides is getting pretty close to be considered “75% done”:

Thank You, Contributors

CDS would not be possible without the following people who make Clojure community a better place:

  • Daniel Jomphe
  • Gareth Jones
  • John Gabriele
  • Lee Hinman
  • Michael S. Klishin
  • Robert Randolph

You Can Help!

How It Works

We have a repository on GitHub that has Markdown files, toolchain setup instructions and several articles as well as stubs for several more articles. The stubs help contributors pick a topic to write about and not worry too much about article structure initially. Just pick something that you are very familiar with or interested in and write.

When you are done, submit a pull request on GitHub and someone from the existing contributors team will suggest improvements or merge your work. Pretty straightforward.

In order to make it easier for potential contributors to join the project, we will post a brief list of guides that do not require deep expertise and can benefit from contributions by complete beginners.

Existing Guides

Tutorials that need work:

Guides that have structure and good chunk of the content in place but still have holes you can help us plug:

These guides are new and cover advanced topics, so we need as much proof-reading as we can get from the community:

New Content

If you want to start working on one of those articles or have existing content you’ve authored that can be ported, please let us know on the Clojure mailing list.

Summary

CDS is getting to the point of being a really useful resource to newcomers. We still have a very long way to go before Clojure documentation can be considered excellent but close enough to the point when it can be recommended to newcomers without feeling bad about it.

Want to help us make things better? Join us!

On behalf of the Clojure Documentation Team

Clojure Documentation Project Progress Report: The Week of October 14th

TL;DR

The Clojure documentation project started off quite actively. With several new guides and a dozen of contributors, the resource is already quite useful to newcomers to the language. We believe this is directly related to our straightforward contribution process.

CDS Progress Report

A week ago we announced the new Clojure Documentation Site (a.k.a. CDS) effort. The level of activity in the first week exceeded our expectations and we thought it may be a good idea to publish periodic reports (every week or two) to give the Clojure community a better idea of what CDS shapes up to be and what it has to offer.

So lets start. This is a report for the week ending October 14th, 2012.

In a Gist

In the first week of CDS, we have added

  • 2 new tutorials and 6 new and 2 expanded guides
  • About 4,000 lines of changes in the content directory (does not include CSS or toolchain-related changes)
  • 14 merged pull requests
  • 13 contributors
  • About 1,400 unique visitors
  • About 6,000 page views with average visit duration of 2 minutes and 10 seconds

In addition, we have ironed out first issues in the contribution process and set up an IRC channel (#clojure-doc on irc.freenode.net) when contributors coordinate their work.

New Content

New tutorials:

New guides:

Updates

Improved guides:

Thank You, Contributors

CDS would not be possible without the following people who make Clojure community a better place:

  • Gareth Jones
  • John Gabriele
  • Claudio Perez Gamayo
  • gsnewmark
  • Phil Hagelberg
  • Lee Hinman
  • Michael Klishin
  • Julson Lim
  • Jake McCrary
  • Max Penet
  • Oleksandr Petrov
  • Robert Randolph
  • Yogthos

You Can Help!

How It Works

We have a repository on GitHub that has Markdown files, toolchain setup instructions and several articles as well as stubs for several more articles. The stubs help contributors pick a topic to write about and not worry too much about article structure initially. Just pick something that you are very familiar with or interested in and write.

When you are done, submit a pull request on GitHub and someone from the existing contributors team will suggest improvements or merge your work. Pretty straightforward.

In order to make it easier for potential contributors to join the project, we will post a brief list of guides that do not require deep expertise and can benefit from contributions by complete beginners.

Existing Guides

Tutorials that need work:

Guides that have structure and good chunk of the content in place but still have many holes you can help us plug:

New Content

If you want to start working on one of those articles or have existing content you’ve authored that can be ported, please let us know on the Clojure mailing list.

But It Takes Forever/I’m Not A Good Writer/[Insert Your Excuse Here]

If you need examples of what’s possible, here’s what 2 ClojureWerkz core team members could produce in about 6 months in their spare time:

Both ClojureWerkz core team members are not native English speakers. You certainly can contribute even if you allocate 30 minutes per week for it.

Other Ecosystem Documentation Improvements

CDS is about improving Clojure documentation all around the spectrum: from tutorials to language guides to documentation about important parts of the ecosystem. One of the fundamental building blocks of the Clojure ecosystem is Leiningen. There were two improvements to Leiningen documentation this week:

Summary

CDS is shaping up quite nicely. With over a dozen of contributors and 8 piece of content contributed the first week, the progress has exceeded our expectations. The Clojure community still has very long way to go with respect to documentation but this is encouraging.

And, you can help!

On behalf of the Clojure Documentation Team

Announcing a New Clojure Documentation Project

This blog is about ClojureWerkz libraries news and developments but this blog post is about something else. Something more important, actually.

TL;DR

Several community members are working on a new Clojure documentation site that looks to improve the situation around Clojure documentation and in particular make contributing documentation significantly easier:

  • Hosted on GitHub
  • Is not covered by the Clojure Contributor Agreement
  • Written in Markdown
  • Provides tutorials and in-depth guides on language features
  • Covers the ecosystem: libraries, tooling, development practices

Announcing Community-Driven Clojure Documentation Site (CDS)

As communities around open source technologies grow, they hit road bumps every now and then. For Clojure, the main limiting factor right now is documentation. This is suggested by both the data from the most recent The State of Clojure survey and the general community sentiment.

Current Clojure documentation is in bad shape primarily because there are no documentation guides. It’s fair to say that clojure.org is useless to beginners. To add insult to injury, the current Clojure Contributor Agreement process make it impossible to contribute documentation or any content to clojure.org without first mailing a piece of paper to USA.

A few community members thought it does not have to be this broken and decided to start a new, completely community-driven documentation site. It has an uninventive name, Clojure Documentation Site (CDS) and available at clojure-doc.org.

Next lets take a look at what the goals are and how it will be different from the broken system Clojure has in place today.

How It Works

We have a repository on GitHub that has Markdown files, toolchain setup instructions and several articles as well as stubs for several more articles. The stubs help contributors pick a topic to write about and not worry too much about article structure initially. Just pick something that you are very familiar with or interested in and write.

When you are done, submit a pull request on GitHub and someone from the existing contributors team will suggest improvements or merge your work. Pretty straightforward.

What CDS Covers

CDS’ goal is to cover more than just the language. It is certainly cruicially important to have good tutorials and comprehensive guides on Clojure. But when using Clojure in real world projects, you will need to know about the JVM ecosystem, Leiningen, how to write tests, what libraries are out there, how to profile code, JVM tooling for ops, how to develop and distribute libraires, and much more.

So there is group of articles about “the Ecosystem stuff”: think Leiningen, popular libraries or how to use VisualVM to find hot spots and investigate concurrency hazards in your apps.

This means that if you feel that documenting sequences is boring but excited about the ops side of software engineering, you can still contribute to CDS and enjoy the process.

When documenting various tools, sometimes it makes more sense to just link to existing documentation, which is what we do for Leiningen.

What We Have So Far

CDS is a very young project (less than two weeks old) but we already have some content written by the core team and community contributors:

Call to Arms

If your company uses Clojure or has interest in adopting it and has “open source Fridays”, “hacker time” or something similar, consider contributing to CDS. This will literally benefit the entire Clojure community, all the current and future users.

Not only every single Clojure user benefits from better documentation, it also gets outdated way slower than much of open source code out there. In our opinion, contributing documentation for a programming language is one of the best ways to invest of your OSS time budget.

No contribution is too small: feel free to suggest grammar improvements, better code examples, submit pull requests with just one new paragraph or even a couple of spelling corrections. Editing and proof-reading is also a great way to contribute.

If you have design and/or frontend development skills, you are more than welcome to make CDS more legible, easy to navigate, and simply better looking.

But It Takes Forever/I’m Not A Good Writer/[Insert Your Excuse Here]

If you need examples of what’s possible, here’s what 2 ClojureWerkz core team members could produce in about 6 months in their spare time:

Both ClojureWerkz core team members are not native English speakers. Everybody can help. Imagine what Clojure documentation may look like in a few months if CDS accumulates 10-15 active contributors and about as many proof-reading content.

Low-hanging Fruits

There are currently several articles that already have their structure in place, what is left is writing the content and code examples. For example, you don’t have to be a genius or a Clojure expert to write articles about

If you want to start working on one of those articles or have existing content you’ve authored that can be ported, please let us know on the Clojure mailing list.

What CDS is Not

CDS does not try to cover API reference. clojuredocs.org covers that pretty well already.

Wrapping Up

Clojure documentation is the limiting factor for community growth. The existing contribution process is inadequate for documentation. This led a group of community members to start a new project, with as low a barrier to entry as possible. We already have some results to show and looking for your help!

Announcing Langohr Documentation Guides

TL;DR

Langohr is a RabbitMQ Clojure client that embraces AMQP 0.9.1 model.

While Langohr is not yet quite ready for 1.0, it is past all major breaking changes and the doc site are in good enough shape to announce them.

A Brief History Lesson

Langohr is a RabbitMQ Clojure client that embraces AMQP 0.9.1 model. ClojureWerkz started with Langohr and it has served us well over the last 16 months or so. Before starting Langohr, ClojureWerkz core team members already had years of experience working with (and on) 3 other RabbitMQ clients:

However, up until now it’s lacked the key feature ClojureWerkz projects share: documentation guides. Fortunately, not any more.

Langohr Documentation Guides Are Here!

There is a good thing about starting Langohr documentation work later: Langohr benefits from amqp gem documentation guides that we’ve gotten good feedback on. In the end we decided to adapt amqp gem guides for Langohr, revisit and edit them and contribute any improvement that come to mind back to the Ruby client documentation.

Today we are happy to report that most of the work is already done and available at clojurerabbitmq.info:

Getting started

This is your typical Getting Started guide, covering things like RabbitMQ installation, adding Langohr as a dependency to your project, basic concepts and a few examples to demonstrate key features:

  • The “Hello, world” of messaging
  • Blabbr, a Twitter-like one-to-many topology example
  • Weathr, an n-to-m topology example

AMQP Concepts

This article covers AMQP 0.9.1 model, concepts and protocol structure. It is not client-specific and now lives on rabbitmq.com so we simply link to it.

Conneciting To The Broker

This guide covers:

  • How to connect to RabbitMQ with Langohr
  • How to use connection URI to connect to RabbitMQ (also: on Heroku)
  • How to open a channel
  • How to close a channel
  • How to disconnect

Queues and Consumers

This is the key article for applications that primarily consume messages.

For example:

  • How to declare AMQP queues with Langohr
  • Queue properties
  • How to declare server-named queues
  • How to declare temporary exclusive queues
  • How to consume messages (“push API”)
  • How to fetch messages (“pull API”)
  • Message and delivery properties
  • Message acknowledgements
  • How to purge queues
  • How to delete queues
  • Other topics related to queues

Exchanges and Publishing

This is another long article that covers multiple topics relavant for apps that mostly produce messages.

It covers:

  • Exchange types
  • How to declare AMQP exchanges with Langohr
  • How to publish messages
  • Exchange propreties
  • Fanout exchanges
  • Direct exchanges
  • Topic exchanges
  • Default exchange
  • Message and delivery properties
  • Message routing
  • Bindings
  • How to delete exchanges
  • Other topics related to exchanges and publishing

Together with the Queues guide, this is the bulk of Langohr documentation.

There are also several smaller guides most of which are not yet ready. They will be added as the time permits.

The Road To 1.0

Langohr 1.0 is still a few months away. The API is largely locked down but we take a conservative stance and try to be careful about calling things “done”. There is still a number of features we’d like to add before the big 1.0 release and a number of small documentation guides still remain to be written.

Thank You Contributors

We would like to thank people who have helped make Langohr documentation better by reviewing our drafts, suggesting improvements, correcting the grammar and simply encouraging us to take this project through to completion:

If you’d like to contribute, all the docs are open source and available on GitHub. Fork away and submit us a pull request when you are done.

News and Updates

If you’d like to follow Langohr progress, new releases and updates are announced on Twitter. Langohr also has a mailing list, feel free to ask questions and report issues there.

Langohr is a ClojureWerkz Project

Langohr is part of the group of libraries known as ClojureWerkz, together with

  • Elastisch, a minimalistic well documented Clojure client for ElasticSearch
  • Welle, a Riak client with batteries included
  • Monger, a Clojure MongoDB client for a more civilized age
  • Neocons, a client for the Neo4J REST API
  • Quartzite, a powerful scheduling library

and several others. If you like Langohr, you may also like our other projects.

Let us know what you think on Twitter or on the Clojure mailing list.

The ClojureWerkz Team

Elastisch 1.0: A Minimalistic, Well Documented Clojure Client for ElasticSearch

Elastisch 1.0 is here!

TL;DR

Elastisch 1.0 is a battle tested minimalistic feature rich and well documented client for ElasticSearch. It supports virtually every Elastic Search feature and has solid documentation that covers Elastic Search and Lucene concepts and terminology as well as the actual library.

After 10 months of work, several alphas, betas and two RCs, Elastisch is ready to go 1.0.

What’s In The Box

Here’s what Elastisch supports out of the box:

  • Complete support for indexing operations
  • (Almost) complete support for querying, with the exception of multi-search
  • Support for all the query and filter types
  • Straightforward and consistent API that closely follows ElasticSearch REST API
  • Solid documentation (our favorite feature)
  • Facets (faceted search)
  • Percolation support
  • Administrative operations on indexes

To our knowledge, the only feature Elastisch does not support yet is multi-search, which is used relatively rarely. Minimalistic does not have to mean primitive: Elastic Search has many features and Elastisch users should be able to easily benefit from them.

Learn more in the Getting Started guide and the rest of the docs.

Documentation

Solid documentation is one of the goals of ClojureWerkz libraries and Elastisch is no exception. We believe that documentation guides are more important than API reference because they are useful to people with all levels of expertise. Elastic Search’s own documentation is not bad but very reference-oriented. So for Elastisch, we took extra time to delay the 1.0 release and write more detailed guides that introduce you to concepts, terminology, the analysis process, many query types and other numerous features Elastic Search has:

  • Getting Started guide is a typical Getting Started guide with brief introductions, code examples and links to documents that provide more information.
  • Mapping and Indexing guide covers many topics related to indexing, analysis, analyzers, mapping types
  • Querying guide covers querying, types of queries, filters, and so on
  • Facets guide covers faceted search, what it is good for, what Elastic Search has to offer and how to use it with Elastisch
  • Percolation guide covers many things related to percolation

We hope this content will be useful as an intro to Elastic Search concepts for developers working in languages other than Clojure and eventually can be used for Elastic Search’s own doc guides.

We would like to thank Karel Minarik (the author of Tire) for proof-reading early versions of the guides and Clinton Gormeley for Elastic::Model docs that we secretly have been stealing bits and ideas from. The Elastic Search community is very nice and the feedback from other client library maintainers helped us improve Elastisch a lot.

Development, Issue Tracking, Supported Clojure Versions

Elastisch targets Clojure 1.3+ and tested against 3 Clojure versions (1.4, 1.3, 1.5-master-SNAPSHOT) x 3 JDKs on travis-ci.org.

The source is available on GitHub. We also use GitHub to track issues. If you want to contribute, there is a section on our workflow in the README.

License

Elastisch is released under the Eclipse Public License, the same as Clojure.

News and Updates

New releases and updates are announced on Twitter. Elastisch also has a mailing list, feel free to ask questions and report issues there.

Elastisch is a ClojureWerkz Project

Elastisch is part of the group of libraries known as ClojureWerkz, together with

  • Welle, a Riak client with batteries included
  • Monger, a Clojure MongoDB client for a more civilized age
  • Neocons, a client for the Neo4J REST API
  • Langohr, a Clojure client for RabbitMQ that embraces the AMQP 0.9.1 model
  • Quartzite, a powerful scheduling library

and several others. If you like Elastisch, you may also like our other projects.

Let us know what you think on Twitter or on the Clojure mailing list.

The ClojureWerkz Team