Skip to content

Latest commit

 

History

History
112 lines (82 loc) · 5.57 KB

CONTRIBUTING.md

File metadata and controls

112 lines (82 loc) · 5.57 KB
Raw

CONTRIBUTING TO FACETS

General Rules

  • Facets methods must have no external dependencies. (The only possible exception to this is if the functor gets spun-off as a separate gem along with related methods, but for now that hasn't happened.)

  • Each method must be in it's own file of the same name. If the method ends with = or ? just leave it off the file name.

  • On rare occasion two or more methods can be very tightly related. In these cases the methods can all go in a single file under the name of the method considered most significant. Usually files for the other methods should still be created that simply require the main file.

  • Methods must be tested both via a Lemon unit test and as a QED demo. The Lemon unit tests are for testing a method in detail whereas the QED demos are for demonstrating usage.

  • Facets is divided into two parts, core and standard libraries. Almost all of the core library can be loaded at once using require 'facets' The standard library (also called the more library) must be required per-script.

  • Some core methods are included on a trial basis, and these are not necessary loaded automatically with require 'facets'. These should be documented as such in the method comments.

  • Standard libraries that are not extensions of existing standard libraries do not have to be divvied up into individual method files. But note that full classes and/or modules are less likely to make it into Facets, as these sorts of additions to Facets are only for very basic sorts of things. Otherwise they'd deserve their own gem.

  • When submitting new methods for consideration, it is best if each method (or tightly related set of methods) is in it's own pull request. If you have only one method to submit then a simple commit will do the trick. If you have more than one it best to use separate branches. Let me emphasizes this point because it makes it much more likely that your pull request will be merged. If you submit a bunch of methods in a single pull request, it is very likely that it will not be merged even if methods you submitted are accepted!!!

  • Don't be discouraged when you get feedback about a method that isn't all sunshine and roses. Facets has been around long enough now that it needs to maintain a certain degree of quality control, and that means serious discernment about what goes into the library. That includes having in depth discussions the merits of methods, even about the best name for a method --even if the functionality has been accepted the name may not.

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.

  • If the commit is only a documentation change, then and :doc:.
  • If it is only a change to tests then add :test:.
  • If the change only effects project build or config files then add :admin:.
  • If the change fixes a bug that was reported via the issue system be sure to reference the issue number in the message using # and add a :bug: tag.
  • For actual code changes, if the change is very minor and not something anyone would notice, you can use :tweak:, if you want.
  • If the change would require a minor version change than use :minor:.
  • But if a change is a significant change to the API, and thus will require a major version change, then end the message with :major:.

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

  • Methods in lib/core/facets/{class}/{method}.rb will be tested in test/foo/{class}/test_{method}.rb.
  • If lib/core/facets/{class}/{method}.rb consists only of a require statement, no test file is expected.
  • If lib/core/facets/{class}/{method}.rb consists only of a require and an alias, then test/foo/{class}/{method}.rb, only needs to test the existence of the alias and not the underlying code. But it's okay if the alias is tested further.
  • Methods in lib/core/facets/{class}/{method}.rb will be demoed in demo/core/{class}/{method}.md.
  • Require only files will have a full demo of it's method or methods. Code in a single file may be split into multiple demos, named after the method. This is to promote discoverability in the documentation.
  • Demos of aliases will have a simple demo, and a reference to the file it aliases