113 lines
5.6 KiB
Markdown
113 lines
5.6 KiB
Markdown
# 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
|
|
|
|
|