<commit_before>= Traka

A Rails 3+ plugin for simple tracking of changes to resources over time.

Traka will keep track of *create*, *update* and *destroy* over time in your application. It uses a simple versioning
system so you can complie groups of changes into blocks.

Changes that cancel each other out will be automatically cleansed from a changeset. For example, if one record is
created and then destroyed later in the same changeset, the two will cancel each other out.

Traka is useful in conjunction with APIs that need to be able to have simple versioning. For example, your app
neds to send out a changeset when a new version of the data is published. This way your API can send just the data
that has been created/updated/destroyed instead of sending out everything every time.

== Install

  gem install traka
  rails g traka:install

== Use

Add the following to each model you want to keep track of:

  is_trakable

Each model should have a string "uuid" column. If you want to use a different column name, just specify it:

  is_trakable :traka_uuid => "code"

To access the current set of staged changes:

  TrakaChange.staged_changes ## => [traka_change_record, ...]

Each TrakaChange record can be resolved to the original record (except "destroy"):

  TrakaChange.staged_changes.first.get_record ## => record

To fetch a changeset across multiple versions. Assuming current version is 5, to get changes from v2 onwards:

  TrakaChange.changes_from(2) ## => [traka_change_record, ...]

Or just get changes from v2 to v4:

  TrakaChange.changes_in_range(2, 4) ## => [traka_change_record, ...]

The above methods will automatically cleanse obsolete changes. To see everything:

  TrakaChange.changes_from(2, false)        ## => [traka_change_record, ...]
  TrakaChange.changes_in_range(2, 4, false) ## => [traka_change_record, ...]

To see the current version:

  TrakaChange.latest_version

To publish a new version:

  TrakaChange.latest_version       ## => 1
  TrakaChange.publish_new_version!
  TrakaChange.latest_version       ## => 2<commit_msg>Added examples to README<commit_after>= Traka

A Rails 3+ plugin for simple tracking of changes to resources over time.

Traka will keep track of *create*, *update* and *destroy* over time in your application. It uses a simple versioning
system so you can complie groups of changes into blocks.

Changes that cancel each other out will be automatically cleansed from a changeset. For example, if one record is
created and then destroyed later in the same changeset, the two will cancel each other out.

Traka is useful in conjunction with APIs that need to be able to have simple versioning. For example, your app
neds to send out a changeset when a new version of the data is published. This way your API can send just the data
that has been created/updated/destroyed instead of sending out everything every time.

== Install

  gem install traka
  rails g traka:install

== Setup

Add the following to each model you want to keep track of:

  is_trakable

Each model should have a string "uuid" column. If you want to use a different column name, just specify it:

  is_trakable :traka_uuid => "code"

== Use

To access the current set of staged changes:

  TrakaChange.staged_changes ## => [traka_change_record, ...]

Each TrakaChange record can be resolved to the original record (except "destroy"):

  TrakaChange.staged_changes.first.get_record ## => record

To fetch a changeset across multiple versions. Assuming current version is 5, to get changes from v2 onwards:

  TrakaChange.changes_from(2) ## => [traka_change_record, ...]

Or just get changes from v2 to v4:

  TrakaChange.changes_in_range(2, 4) ## => [traka_change_record, ...]

The above methods will automatically cleanse obsolete changes. To see everything:

  TrakaChange.changes_from(2, false)        ## => [traka_change_record, ...]
  TrakaChange.changes_in_range(2, 4, false) ## => [traka_change_record, ...]

To see the current version:

  TrakaChange.latest_version

To publish a new version:

  TrakaChange.latest_version       ## => 1
  TrakaChange.publish_new_version!
  TrakaChange.latest_version       ## => 2

== Example

Assuming models called Product and Car exist.

  a = Product.create(:name => "Product 1")
  b = Product.create(:name => "Product 2")
  c = Car.create(:name => "Car 1")

  TrakaChange.staged_changes  ## => [TrakaChange<create>, TrakaChange<create>, TrakaChange<create>]

  b.name = "<NAME>"
  b.save

  # The "update" above is filtered out because we already know to fetch "b" because it's just been created.
  TrakaChange.staged_changes  ## => [TrakaChange<create>, TrakaChange<create>, TrakaChange<create>]

  TrakaChange.publish_new_version!

  b.destroy
  a.name = "<NAME>"
  a.save

  TrakaChange.staged_changes                 ## => [TrakaChange<destroy>, TrakaChange<update>]
  TrakaChange.staged_changes.last.get_record ## => a

  a.name = "<NAME>"
  a.save

  # The update above is filtered because we already know "a" has been updated in this changeset.
  TrakaChange.staged_changes                 ## => [TrakaChange<destroy>, TrakaChange<update>]
  TrakaChange.staged_changes.last.get_record ## => a

  # All interactions with "b" are filtered out because we've created and destroyed it in the same changeset: v1+v2.
  TrakaChange.changes_from(1) ## => [TrakaChange<create>, TrakaChange<create>, TrakaChange<update>]

See the unit tests for a bunch more examples.
{'fraction_non_alphanumeric': 0.08148284088823637, 'fraction_numerical': 0.005872637181134153, 'mean_word_length': 4.102996254681648, 'pattern_counts': {'":': 0, '<': 19, '<?xml version=': 0, '>': 47, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2296422', 'n_tokens_mistral': 1617, 'n_tokens_neox': 1547, 'n_words': 651}