CONTRIBUTING TO FACETS

General Rules

Versioning

Facets tries to follow a semantic versioning system, but with a slightly differt scheme than most projects. For Facets the version number represents:

gestault.major.minor

Techinically there can be a fouth build number, but we never use it for releases.

Commit Tags

When making a commit, it is helpful to add a commit tag to the end of the first line of commit message. Commit tags are single words wrapped in colons.

These are all rules of thumb, and no one expects them to be applied perfectly.

Documentation

Facets started when the only choice for API documentation was RDoc. So originally that's how methods were documented. Since then both YARD and Tomdoc have come along. And some of these documentation styles have crept into a number of methods. So right now, things are a bit messy. But going forward it looks like we are going to settle on Tomdoc as the official documentation style (but using the tomparse gem's extensions). Using Tomdoc will give us reasonable interoperability with both RDoc and YARD, both of which now have support for Tomdoc (albeit support is not 100% the same, but hopefully it's close enough).

Officially we publish documentation via rubydoc.info, which is the YARD server, and via the Facets website in Shomen JSON format.

When writing documentation for a method it is best to give a simple summary explanation, followed by some basic examples. Follow that up with deeper explanation if needed, including when and why the method could be useful.

Testing