qb 0.3.12 → 0.3.13

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: cad865997a7d3c28a43696a18d61845343640f57
-  data.tar.gz: 862f3381e5233eb4958e534beeeeb6e8713f70b5
+  metadata.gz: 5303c21f22149b8a6ae1bccb85b6ab0c298eabe5
+  data.tar.gz: 192ae9200cbcc58a3ac5accc4fbd46f13f08a2f5
 SHA512:
-  metadata.gz: e84892a7b62dad0a3f7d4dfb4a5aa5dd5c865a3412ef8b6f1e1f70ada799e61b3f7397511a8e3aa6275c3927ff0c32c21fd1aae179bc6551689d2251db047275
-  data.tar.gz: c40a7c516e791e845d335ad3a8aa31dfc8537c3a5f7d72010cd28f1e2bd4dc04fe40c829fd600f974e72ec3f27e035dce51fbd3e1d06744c1b3b9c00a34db310
+  metadata.gz: 51454accde596eab43cd5311cab5eb302b56dfe443694817486261cc56a1da02eff5db83a2ea53668eb2b0efaa344b02c5c81fbee41de7bffec280e348d09aa4
+  data.tar.gz: 59244ecbf50690bee88196083a711716d4ed4aca587e465d61531977b801a37d213db82a0b763a7c47800a384074bb92eacd9eaaabf83a074d248d1a94ef4d4c

data/.yardopts

@@ -1,5 +1,7 @@
---markup markdown
+--output-dir=./doc/site
+--markup=markdown
 lib/**/*.rb
 dev/packages/gems/nrser/lib/**/*.rb
 -
 README.md
+doc/**/*.md

data/README.md

@@ -1,48 +1,64 @@
-# qb #
+QB
+==============================================================================
 
-qb is all about projects. named after everyone's favorite projects.
+QB is all about projects. Named after everyone's favorite projects.
 
-## meta/qb.yml ##
+QB works by running [Ansible][] plays. So you can think about it as "quarterback" if you happen to be from the corner of the world where that makes any sense.
 
-if this file exists in a role `qb` sees it will make that role available.
+You generally want to read these docs at
 
-the contents of this file allow you to configure how `qb` uses the role.
+<http://www.rubydoc.info/gems/qb/>
 
-### null values ###
+where the links are more likely to work.
 
-values set to `null` are treated like they're not there at all. to tell QB
-*not* to do something assign `false`.
+Or, if you're working from a local clone, by booting the [yard][] server via
 
-### var_prefix ###
+    bundle exec yard server
 
-declare prefix to be added to variable names from the command line for
-use in the role.
+and opening
 
-because all variables are pretty much global in ansible, you really want to prefix all your variables names to try and achieve uniqueness. the way i've been doing that is to prefix them with the 'namespaceless' part of the role name.
+<http://localhost:8808>
 
-for example, if you have a role named `qb.project`, the 'namespace' would be `qb` and the 'namespaceless' part would be `project`. it has been my convention to then name the role variables `project_*`, like `project_owner`, `project_name`, etc..
 
-`var_prefix` therefore defaults to the 'namespaceless' part of the role name, so that a call like
+<!-- References & Further Reading: -->
 
-    qb qb.project --owner=nrser --name=blah
+[Ansible]: https://www.ansible.com/
+[yard]: https://yardoc.org/
 
-will pass variables
 
-    project_owner: "nrser"
-    project_name: "blah"
+------------------------------------------------------------------------------
+Quickies
+------------------------------------------------------------------------------
 
-to the `qb.project` role.
+1.  Status: **UNSTABLE**
+    
+    A bit past experimental, but still actively exploring API and features. Any and every thing subject to breaking changes until we hit `1.0`. Generally trying to bump the minor version with larger changes, but not paying a huge amount of attention to it. Being used personally and in projects and organizations I work with.
 
-however, this setting allows you to specify an alternative prefix. 
+2.  Compatibility: **OSX/macOS-only**
+    
+    Though it would probably run fine on Linux, if not other \*nix as well.
 
-if this is set to `null` the default will be used.
+3.  Installation
+    
+    Head over to {file:doc/getting_started.md Getting Started}.
 
-### default_dir ###
+4.  More Info
+    
+    There is some semblance of an {file:doc/intro.md Introduction} available to get indignant about.
 
-every invocation of `qb` must have a directory it's targeting where it will place a `.qb-options.yml` if applicable. this directory is passed to the role as the `dir` option
 
-this is often the project's root folder, and can sometimes be assembled from the values of other parameters.
+<!-- References & Further Reading: -->
 
-### vars ###
+[Homebrew]: https://brew.sh/
 
-TODO
+[Ansible Installation]: http://docs.ansible.com/ansible/latest/intro_installation.html
+
+
+------------------------------------------------------------------------------
+Help!
+------------------------------------------------------------------------------
+
+Common Issues:
+
+1.  `qb run` Command Issues
+    1.  {file:doc/common_issues/qb_run/slow_gather_facts.md "Gathering Facts" is *really slow* (FQDN lookup problem)}

data/ansible.cfg

@@ -2,3 +2,10 @@
 
 roles_path = ./dev/scratch
 retry_files_enabled = False
+
+# Will cause Ansible to cache facts at `//tmp/facts_cache/localhost` in JSON
+# format. Useful when you want to see what it's caching and play with using the
+# cache
+# gathering = explicit
+# fact_caching = jsonfile
+# fact_caching_connection = ./tmp/facts_cache

data/doc/common_issues/qb_run/slow_gather_facts.md

@@ -0,0 +1,51 @@
+Common Issue: "Gathering Facts" is *really slow* (FQDN lookup problem)
+==============================================================================
+
+Like, 30 seconds kind of slow..!
+
+I've encountered this when the system hostname is *not fully-qualified*, resulting in a DNS query (that seemingly times out after - you guessed it - 30 seconds) in attempt to figure out the hosts' Fully-Qualified Domain Name (FQDN).
+
+The culprit in this case is a call to Python's `socket.getfqdn()`, which can be found when Ansible is gathering the `platform` facts at
+
+<https://github.com/ansible/ansible/blob/v2.4.1.0-1/lib/ansible/module_utils/facts/system/platform.py#L49>
+
+You can test if this is an issue with the following terminal command:
+
+    time python -c 'import socket; print(socket.getfqdn())'
+
+You want that to return really quickly, and should see something like:
+
+    $ time python -c 'import socket; print(socket.getfqdn())'
+    nrser-mbp.local
+
+    real	0m0.394s
+    user	0m0.015s
+    sys	0m0.021s
+
+If it obviously takes a long time and you see result more like
+
+    $ time python -c 'import socket; print(socket.getfqdn())'
+    nrser-mbp
+
+    real	0m30.028s
+    user	0m0.013s
+    sys	0m0.008s
+
+then it's definitely a problem and is **single-handedly slowing fact gathering to a crawl**.
+
+The reason it's happening is because the system's `HostName` is not fully-qualified - notice the `nrser-mbp.local` output in the fast time and the `nrser-mbp` in the slow one.
+
+The remedy is to add the `.local` to the `HostName`:
+
+    sudo scutil --set HostName "$(scutil --get LocalHostName).local"
+
+and you're all set!
+
+> This assumes you get something reasonable out of `scutil --get LocalHostName`... you can of course just manually stick your hostname in there too.
+
+If you have a specific hostname/network setup where `.local` doesn't make sense, you're of course going to have to do something more complicated, probably involving your local DNS resolution and/or network DNS, but the basic idea remains: get `socket.getfqdn()` to go fast.
+
+
+Credit where credit is due:
+
+1.  https://apple.stackexchange.com/questions/175320/why-is-my-hostname-resolution-taking-so-long

data/doc/getting_started.md

@@ -0,0 +1,84 @@
+Getting Started with QB
+==============================================================================
+
+Meant to help get you up and running.
+
+-----------------------------------------------------------------------------
+Prerequisites
+-----------------------------------------------------------------------------
+
+1.  macOS (OSX)
+    
+    The only thing it's developed, tested and used on at this point, though I don't see any fundamental reason it won't run on \*nix.
+    
+    Exactly zero Windows support.
+    
+    I'm running `10.12.6` "Sierra" right now, and it's not tested in anything else because I'm not aware of any reasonably cheap and easy way to test on a variety of macOS versions.
+    
+2.  [Homebrew][]
+    
+        /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
+    
+    Not totally necessary if you already have all the other prereqs setup or want to figure out how to do so on your own.
+    
+3.  Python 2 (for Ansible)
+    
+        brew install python2
+    
+    Should come with `pip2`. I haven't used anything except `2.7.X`, currently on `2.7.13`.
+    
+4.  [Ansible][Ansible Installation]
+    
+    I use the latest stable version available through `pip2`:
+    
+        pip2 install ansible
+    
+    I think we need at least `2.1.2`, and may need something higher by now. Using `2.4.1.0` right now, which you can explicitly install like:
+    
+        pip2 install ansible==2.4.1.0
+    
+    Basically have been upgrading whenever I hit bugs or try to use a feature just to find it isn't in my version, which has been... often.
+    
+5.  Recent Ruby
+    
+    QB uses refinements, so the Ruby `2.0.0` that ships on recent versions of macOS won't suffice. Currently testing against `2.3.4`.
+    
+    I use [rbenv][], something like:
+    
+        brew install rbenv
+        rbenv init # and follow instructions
+        rbenv install 2.3.4 # or whatever
+        rbenv global 2.3.4
+    
+6.  Recent Node.js
+    
+        brew install node
+    
+    I think Node is only used right now for the [semver][] package, so if you don't use any of the version functionality in QB you probably don't need it?
+
+
+<!-- References & Further Reading: -->
+
+[Homebrew]: https://brew.sh/
+
+[Ansible Installation]: http://docs.ansible.com/ansible/latest/intro_installation.html
+
+[rbenv]: https://github.com/rbenv/rbenv
+
+[semver]: https://www.npmjs.com/package/semver
+
+
+-----------------------------------------------------------------------------
+Installation
+-----------------------------------------------------------------------------
+
+It's just gem from there:
+
+    gem install qb
+
+
+-----------------------------------------------------------------------------
+Usage
+-----------------------------------------------------------------------------
+
+Yeah TODO someday maybe.

data/doc/intro.md

@@ -0,0 +1,67 @@
+A Rough Introduction to QB
+==============================================================================
+
+Ok, So WTF Is It?
+------------------------------------------------------------------------------
+
+QB is a wrapper around [Ansible Roles][] (Ansible's principle unit of code generalization and reuse) that provides a [command line interface][] (here-after referred to as the *CLI*, which just means you use it from the *terminal* or *console* or *shell* or whatever you call the thing you type commands into) for running roles on-the-fly.
+
+Instead of writing an [Ansible playbook][] file along with all the necessary [configuration][Ansible configuration] you can just open up a terminal and tell it what you want to do, and QB finds the roles, sets up the paths and host, builds the playbook, and runs it.
+
+It also provides help on which roles are available, what they do, and what arguments and options they accept, along with a mess of other features and functionality aimed to make it nicer and easier to write and run Ansible roles that manage your project state.
+
+QB is written in Ruby and distributed as a gem. This is kinda a pain-in-the-ass because Ansible is written in Python, so they can't share a runtime, and Ruby doesn't naturally compile/package into a binary, so you end up dealing with [rbenv][] and getting all the paths pointing the the right version and all that other fuss.
+
+But hey, Ruby just *feels good man*, and at least it has it's packaging, pathing, distribution and environment management a far-sight better together than Python (in, like, my opinion... I find RubyGems, Bundler, `Gemfile` and `rbenv` a lot less troublesome than `pip`, `virtualenv`, `requirements.txt` and the dreaded `site-packages`).
+
+
+<!-- References & Further Reading: -->
+
+[command line interface]: https://en.wikipedia.org/wiki/Command-line_interface
+
+[Ansible Roles]: http://docs.ansible.com/ansible/latest/playbooks_reuse_roles.html
+
+[Ansible playbook]: http://docs.ansible.com/ansible/latest/playbooks.html
+
+[Ansible configuration]: http://docs.ansible.com/ansible/latest/intro_configuration.html
+
+[rbenv]: https://github.com/rbenv/rbenv
+
+
+-----------------------------------------------------------------------------
+Why Would You Want To Do A Stupid Thing Like That?
+-----------------------------------------------------------------------------
+
+Basically, [idempotence][]. I want the human (that's you!) to say how things should be and the computer to do what needs to be done (and only what needs to be done) to make it like that.
+
+Ansible:
+
+1.  Has a big library of idempotent functionality (that they call [modules][Ansible Modules]) covering a lot of common system resources and states (and they're pretty well documented).
+    
+2.  Uses a very easy to understand execution paradigm (here's a list of stuff, go through it in order).
+    
+3.  Is reasonably easy to extend in simple and useful ways, like writing modules, roles, and the more common plugin types.
+
+On the downside, Ansible:
+
+1.  Is extremely slow to execute `localhost`-targeted playbooks (by CLI standards).
+    
+2.  Is difficult to extend in complex and useful ways (mostly due to the nearly-complete lack of [Python API][Ansible Python API] documentation).
+    
+    Trying to write vars and action plugins falls in this category for me, along with most the other "look at the source and maybe you can find something kinda like what you want and then screw around off that until it sorta works" stuff.
+    
+3.  Generally greets you with a old-school-PHP-esque awkwardness once you wade in past the kiddie pool, seemingly due to a similar legacy of an extremely simple system that had things *resembling* common programing features bolted on without always lining up the holes or tightening the screws.
+    
+    See: parametrized roles when all variables are kinda maybe global; modules without any concept of extension or composition, etc.
+
+
+So, QB tries to make using all that Ansible stuff easier for your everyday tasks and work around some of the wonkiness a bit.
+
+
+<!-- References & Further Reading: -->
+
+[Idempotence]: https://en.wikipedia.org/wiki/Idempotence
+
+[Ansible Modules]: http://docs.ansible.com/ansible/latest/list_of_all_modules.html
+
+[Ansible Python API]: http://docs.ansible.com/ansible/latest/dev_guide/developing_api.html

data/doc/notes/2018.01.06.ansible_devel_submodule.md

@@ -0,0 +1,29 @@
+Ansible `devel` Branch as a Submodule
+==============================================================================
+
+I've forked the [devel][ansible/ansible@devel] branch of [ansible/ansible][] (where activer development happens) at ansible/ansible@b7bf98cd to [nrser/ansible][] (maintaining `devel` as the active and default branch) and added as a submodule at `//packages/python/ansible`.
+
+Because:
+
+1.  I specifically needed `include_role` to properly template it's `name` parameter, which is fixed in `devel` and presumably slated to land in `2.5` but broken in `2.4`. Which leads me too...
+    
+2.  Stuff is broken in Ansible *all the time*. Like no other production software I've ever used. There are nearly [4,000 open issues on GitHub][Ansible issues]. Which has painfully and eventually led me to
+    1.  Since the release versions are so riddled with bugs (sorry guys, it just really is), might as well use the active development version and at least be able to take advantages of fixes as soon as possible.
+        
+        This is my first excursion into using `devel`, so I'm yet to see if this results in a better or worse experience, but at this point I'm willing to try.
+        
+    2.  I'm going to need to fix and improve things myself.
+
+This is super experimental, and going to be behind configuration options for the time being and excluded from the gem package, so it will only be available in development, but I think it's quite possibly the only real path forward to build reliable and sane software that takes advantage of Ansible's expansive module library.
+
+
+<!-- References & Further Reading: -->
+
+[ansible/ansible]: https://github.com/ansible/ansible
+
+[ansible/ansible@devel]: https://github.com/ansible/ansible/tree/devel
+
+[nrser/ansible]: https://github.com/nrser/ansible
+
+[Ansible issues]: https://github.com/ansible/ansible/issues
+

data/doc/qb_roles.md

@@ -0,0 +1,155 @@
+QB Roles
+==============================================================================
+
+QB roles are [Ansible roles][] that can be run via `qb run`. An Ansible role is a QB role if it has a [QB Metadata](#QB_Metadata) file - `meta/qb.yml` or `meta/qb`.
+
+
+<!-- References & Further Reading: -->
+
+[Ansible Roles]: http://docs.ansible.com/ansible/latest/playbooks_reuse_roles.html
+
+
+------------------------------------------------------------------------------
+Creating QB Roles
+------------------------------------------------------------------------------
+
+The easiest way to create QB roles is to use QB's `qb/role/qb` role (say *that* five times fast!):
+
+    qb run qb/role/qb DIRECTORY [OPTIONS]
+
+Since `run` is the default QB CLI command and role names are inferred from partial matches whenever possible, this is commonly shortened to:
+
+    qb role/qb DIRECTORY [OPTIONS]
+
+Which will work unless your roles path contains other roles with 'role/qb' in their name.
+
+This will generate a `DIRECTORY/meta/qb.yml` file with common keys and values for you to start from, as well as some notes and links.
+
+
+> **Example**
+> 
+> To create a new role named `me/my_new_role` at `./roles/me/my_new_role` run
+> 
+>     qb role/qb ./roles/me/my_new_role
+> 
+
+
+As always, you can check out the `qb/role/qb` options via
+
+    qb role/qb -h
+
+
+------------------------------------------------------------------------------
+QB Metadata
+------------------------------------------------------------------------------
+
+QB metadata is a dictionary structure mapping string keys to mixed values that provides QB-specific role configuration.
+
+**_A role is a QB role if (and only if) it has QB metadata._**
+
+
+### Metadata File Location and Format ###
+
+Metadata is provided via one of two file paths (relative to the role's root directory `<role_path>`):
+
+1.  `<role_path>/meta/qb.yml`
+    
+    Metadata provided in static [YAML][] format. This is default method and should be used unless the metadata needs to be created dynamically on each role run (in ways not covered by the value options themselves).
+    
+2.  `<role_path>/meta/qb` (*executable*)
+    
+    Metadata provided by running an executable. The file must be marked as executable for the current system user.
+    
+    The executable is fed a [JSON][] encoding of the options collected form the CLI `run` command on `STDIN`.
+    
+    The executable should write the computed metadata to `STDOUT` in [YAML][] or [JSON][] format and exit successfully.
+    
+    > QB uses the [Ruby YAML library][] to parse the result, which accepts `JSON` as well.
+    
+    If `meta/qb` can't compute metadata, it should exit with an error status and write any error feedback to `STDERR` (though feedback might not be nicely relayed to the CLI user yet).
+
+Right now, please don't provide both. At some point I'll handle this case, probably by raising an error, but for the moment I'm not sure how it's (not) handled.
+
+> Role metadata is loaded by the {QB::Role#load_meta} function, which is called on demand when accessing the {QB::Role#meta} attribute.
+
+
+<!-- References & Further Reading: -->
+
+[YAML]: http://yaml.org/
+[JSON]: https://www.json.org/
+[Ruby YAML library]: http://ruby-doc.org/stdlib/libdoc/yaml/rdoc/YAML.html
+
+******************************************************************************
+
+
+### Conventions ###
+
+#### `null` and Missing Metadata Values ####
+
+**_QB treats keys set to `null` and missing keys identically._**
+
+`null` is the same as not being there at all. I feel like this simplifies things. Departures from this behavior are considered bugs.
+
+Generally, to tell QB *not* to do something assign `false`.
+
+******************************************************************************
+
+
+### Recognized Metadata Keys ###
+
+This section lays out recognized keys and their acceptable values.
+
+All keys are optional unless otherwise stated, though if present their values must be acceptable or errors will be raised when you try to run the role.
+
+
+#### default_dir ####
+
+Define a *strategy* (or list of *strategies*) to find a suitable default for
+the `DIRECTORY` command line argument - which becomes the `qb_dir` variable in Ansible - when running a QB role.
+
+> The role's `default_dir` metadata value is converted into a directory path in {QB::Role#default_dir}.
+
+In brief, the *strategy* value can be:
+
+1.  `null` (or missing)
+    -   `DIRECTORY` arg must be provided on CLI.
+2.  `false`
+    -   No `DIRECTORY` arg is used and none will be accepted.
+3.  `cwd`
+    -   Use directory `run` command was run in.
+4.  `git_root`
+    -   Use the root of the Git repo working directory is a part of.
+5.  `{exe: <path:string>}`
+    -   Run the executable at `path` and use output.
+6.  `{find_up: <rel_path:string>}`
+    -   Walk up directories from current looking for `rel_path`.
+7.  `{from_role: <role:string>}`
+    -   Use the value from another role.
+8.  `Array`
+    -   Try each strategy until one works.
+
+See {file:doc/qb_roles/metadata/default_dir.md} for strategy details and examples.
+
+
+#### var_prefix ####
+
+Declare prefix to be prepended to role CLI option names to form their Ansible variable name.
+
+Because all variables are pretty much global in Ansible, you really want to prefix all your variables names to try and achieve uniqueness. the way i've been doing that is to prefix them with the 'namespaceless' part of the role name.
+
+For example, if you have a role named `qb.project`, the 'namespace' would be `qb` and the 'namespaceless' part would be `project`. it has been my convention to then name the role variables `project_*`, like `project_owner`, `project_name`, etc..
+
+`var_prefix` therefore defaults to the 'namespaceless' part of the role name, so that a call like
+
+    qb qb.project --owner=nrser --name=blah
+
+will pass variables
+
+    project_owner: "nrser"
+    project_name: "blah"
+
+to the `qb.project` role.
+
+However, this setting allows you to specify an alternative prefix. 
+
+If this is set to `null` (or missing) the default behavior will be used.