Var versioning

[zk]

Adding version support requires changes in several parts of the app:

• Schema changes
  • Moving everything except for libarary, ns, and name from the functions table to a function_versions table.
  • Adding a version column to the function_versions table.
• Updating site logic to use function.latest_version / function.versions where appropriate.
• Updating UI to provide links on the function.html.erb page to view previous versions.
  • Only having links to versions which have changed from the previous version, keying off the docstring.
• Updating cd-analyzer
  • Importing to new schema
  • Still removing vars that are no longer in the codebase (?)

[zk]

Trying to decide how to proceed with moving the data.

No function version data exists in the DB right now, so I'll start by adding the ability to parse and store to the analyzer, and add a version column to the functions table. Then, write a migration to add the function_versions table, and populate that table with data from the functions table.

Effectively, whatever data exists in the functions table (including the new version column) will become the first version of that var as far as CD is concerned.

[zk]

Updated clojuredocs-analyzer to store version in the newly created functions.version column.

Core import: http://gist.github.com/605416
Contrib import: http://gist.github.com/605424

Also imported ring, version was added correctly.

clojuredocs-analyzer commit

[zk]

Migrations are done, schema now looks like this:

function                  function_versions
--------------            --------------------------
library         <------   function_id
ns                        doc
name                      source
etc                       etc

I also considered keeping line / file / doc / etc in the functions table, and only fetch older versions when requested by the user. This would get rid of the join that will be made every time somebody requests a function, but I'll leave that as a future optimization path.

[zk]

clojuredocs-analzyer has been updated to import to the new versioning schema: analyzer commit

As of now, all libraries that are run through the analyzer now have their version numbers parsed as well (only lein supported atm). New versions are now stored only if the version number on the lib is different than previous versions.

Long-term todos:

• Version sorting (sorts by created_at date for now)

Next up is importing older versions of core and contrib for test data to implement the versions UI on top of.

[zk]

Just ran an import of 1.3.0-alpha1, 801 vars vs 781 vars in 1.2.0

Looks like the unchecked-* vars were removed: http://gist.github.com/610976 (line 1655)

The analyzer will have to be changed, vars should no longer be removed.

[zk]

So a bit of churn here.

Instead of the changes outlined above, I've gone the simpler route of adding version columns to the libraries, namespaces, and functions tables. Additionally I've added a current column to the libraries table to specify the primary version of a specific library.

I feel that, while not as correct as the functions -> function_versions (and libraries -> library_versions, namespaces -> namespace_versions) method, it's simpler to reason about.

Relevant changes are in the var-versioning-simple branch.

Also, a bit of work on the UI has been done:

macroexpand-1 1.2.0 screenshot

macroexpand-1 1.3.0-alpha1 screenshot

Side note: URLs have been prettified so

http://clojuredocs.org/v/1808

becomes

http://clojuredocs.org/clojure_core/current/clojure.core/macroexpand-1

and

http://clojuredocs.org/v/1927

becomes

http://clojuredocs.org/clojure_core/current/clojure.core/even_q

[zk]

Switched from using the word 'current' to 'stable' to describe the latest production version of a library.

Versioning UI updates

Clojure 1.2.0 is the 'stable' version here:

Stable version var page

Stable version var page showing drop-down

After clicking on permalink (notice version number of stable gets added to url)

After clicking on non-stable version

Switched 'stable' version to 1.3.0-alpha1:

Stable version

Non-stable version

[zk]

Finished up var-versioning, rebased into master