[ruby-fs-stack] ruby-fs-stack 0.5.0 release!

[Jimmy Z]

I've just released a big update to the ruby-fs-stack gem. The newest
version is 0.5.0. Here is what has gone into this update:

1. Ruby Blocks!

Ruby blocks have been added to the person read. This allows you to do
the following:

# ids = [really big array of IDs]
running_total = 0
persons = com.familytree_v2.person ids, :parents => 'summary' do |
persons|
# this block will be executed for every 10 person records (or
person.max.ids limit)
running_total += persons.size
puts running_total
end

This gives you a bit of a hook into the person read for each time an
http call is successfully executed.

2. Better 500 Error Handling

Occasionally, the FamilySearch API will return 500 errors when it hits
a strange bit of data on a person. It often takes months for these
errors to be fixed, so the ruby-fs-stack now handles these errors
gracefully.

If the person read encounters a 500 error while performing a person
read on multiple IDs, it will break up the http read into single IDs
and attempt the reads one person at a time. It does this because it is
usually only one of the (x) records being requested that causes the
problem.

When the person read encounters a single record that returns a 500
error, it simply returns an empty Person record with the id and
requestedId filled with the requested ID.

3. Code Reorganization

All of the FamilyTree v2 functionality used to be contained in a
single familytree.rb file that was ~1500 lines of code. I've broken
this up into smaller files because this was becoming unwieldy.
Hopefully the new code reorganization will make the code more
approachable.

All RSpec tests are still passing, so no functionality should be
changing from the interface. The code is just organized more cleanly.

4. RSpec Reorganization

There used to be quite a mismatch between the files being tested and
the RSpec (*_spec.rb) files which tested their functionality. Now that
the familytree.rb is broken up into a better organized structure, the
rspec files have been reorganized to match the structure. If you use
TextMate, you should now be able to use the shortcut keys to toggle
between the RSpec test and its implementation code (ctrl + shift +
down_arrow).

==Future Plans/Desires

1. Performance Improvements

I really love having the ability to take an array of person IDs of any
size and throw it into the person method. I've found from my testing
that when I do this, the code spends considerable amounts of time
waiting for responses from the FamilySearch API. While FamilySearch is
continually making performance improvements on the API, I believe we
can still get things faster on the client if we take advantage of some
threading.

I'd like to propose spinning up at least 2 threads inside the person
read method if there are more than the person.max.ids requested. That
way, we can have two requests happening in parallel with the
FamilySearch API. We'll likely begin hitting the throttling limits
faster, but this is better than never hitting the throttling because
we'd have a larger overall throughput.

2. Fuller implementation

Some of the simple calls that should be implemented in the ruby-fs-
stack that currently aren't:

* Authorities Module (date, place, name)
* Identity v1 logout
* Identity v2 OAuth: The oauth 0.4.0 gem makes this easy, I'd like to
include it as a dependency of this gem.
* Identity v2 Session: Keeps the session alive.
* FamilyTree v2 Persona Reads: Ability to read personas
* FamilyTree v2 Persona Relationship Reads: Ability to read
relationships between personas
* FamilyTree v2 Person Separate Calls: Ability to move persona records
from one person to another or break them apart.
* Wiki API: (read, search, etc.)

If anyone is interested in helping this move forward a bit faster, I'd
be happy to spend some time with you to walk you through the library
and how you can help up. Implementation of new calls is actually
really easy and we should be able to scream through this stuff.

--
Jimmy Z