Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
The SQL meta-chainsaw
Perl
branch: patch-1

This branch is 2 commits ahead, 947 commits behind dbsrgits:current/blead

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
examples
lib
maint
script
t
xt
.gitignore
.mailmap
.travis.yml
CONTRIBUTING
Changes
MANIFEST.SKIP
Makefile.PL
README.pod

README.pod

NAME

DBIx::Class::Manual::Dev::TODO - TODO list of S through XXL tasks for eager young minds

DESCRIPTION

This document attempts to centralize the collective knowledge about various DBIx::Class TODO tasks, ranging from sketches of mundane bugfixes to minutes of heated design discussions.

You can jump straight to the "small" LIST OF OUTSTANDING TASKS. If, however, you plan to edit this document, please read the "HOW TO EDIT THIS DOCUMENT" section first, as parts of this POD double as machine parseable metadata.

Note for GitHub Users

If you are visiting the DBIx-Class project on GitHub you may be surprised to find this unorthodox "README". What you are seeing is GitHb rendering a symlink pointing to the latest revision of DBIx::Class::Manual::Dev::TODO in the currently selected git branch (normally master). Fork this, hack away, and send us a pull request :)

TODOs

Extensions / New Features

DateTime Manipulation DSL

DEP:"-op and -func SQLA operators"

DEP:"Blead/Maint separation"

BL:0.08400

Very sound design, tested on/supports enough databases to be releaseable. Currently contains some nasty hacks (e.g. inclusion of a $storage object reference in the $sql_maker object), but the API is solid and doesn't contain obvious WTFs. Unfortunately it very heavily relies on the -op functionality which does suffer from multiple inconsistencies, which make it unfit for a general release (see the linked DEP). We could potentially release this as a part of the blead cycle without addressing the other issues, however an official release can not happen before the ambiguity of the fundamentals is resolved.

-op and -func SQLA operators

NS

These are currently present in several forms in both the SQLA and the DBIC trees (neither of the branches has been merged yet). Frew is the author of pretty much all of this, and was supposed to clean things up leaving only one branch in the SQLA repo.

The actual obstacle to merging this is the ambiguity of what happens on bindtype information clashes, and how does the bindtype propagate further down the callstack in case the -op/-func are not the only thing in a RHS chain. So far it seems that the Data::Query's architecture is capable of sidestepping this issue entirely, but nobody has investigated this yet.

Relationship arguments

DEP:"Cleanup/rewrite DBI::Class::ResultSet::_merge_joinpref_attr()"

Allow passing of relationship arguments for individual search invocations. Currently proposed syntax is something like:

  $cd_rs->search({}, {
    join => [
      {
        artist => { -alias => 'ar', -join_type => 'left',
          cds => {
            tracks => { -alias => 'tr' },
          },
          paintings => {},
        },
        tracks => { -join_type => 'inner',
          # example custom coderef relspec, args passed to it determine threshold
          # of "platinum" to be reflected in the ON clause
          # the -rel_args key does not yet exist (due to no way of passing it)
          platinum_single_cd => { -rel_args => [...] }, 
        },
      },
      { genre => { -alias => 'g' } },
    ],
  };

The goal is to be able to modify any part of a join condition on the fly, allowing for much better flexibility. It will solve two of the most commonly requested issues "how do I change left to inner" (the current answer is "register a new relationship") and "how do I change the resulting alias" (there is currently no answer to this at all). Also will allow for a common infrastructure to pass options to custom relationship coderefs (the current practice is to have a pesky global somewhere that is local()ised to a certain value before the query takes place). Lastly it will allow explicit overriding of join conditions to take place on long nested left-join chains. The current (API consistent) behavior is to switch any join to left after a left join is encountered in the chain. This is done so that merely adding join/prefetch attributes will not affect the contents of the "left part" of the resultset.

Refactoring / Cleanup / Architectural improvements

Data::Query migration

Thanks to mst Data::Query is now much closer to reality than it may seem. In fact it fully passes the entire original SQLA test suite and is ready for an attempt of porting DBIC to the new architecture. The only really burning outstanding issue is how to encode the concept of "dialect" in an instance of D::Q. The approach attempted by Frew in the "DateTime_Manipulation_DSL" branch turns out way too ugly and entangled.

What needs to be done to get this project moving further is getting a checkout of the dq branch of the SQL::Abstract repo and attempting to run the DBIC test suite against it. DBIx::Class::SQLMaker hooks many of the internals of SQL::Abstract which are gone in that branch, so a lot of rewriting will need to take place. An upside is that our test coverage of these codepaths is beyond excellent, so as long as all tests pass you can be 98% sure the job is all done.

Cleanup/rewrite DBI::Class::ResultSet::_merge_joinpref_attr()

This code is well tested (it even has a dedicated test file to just test its output, t/91merge_joinpref_attr.t), however it is very weirdly written and hence hard to maintain. It will also need to learn about dash-prefxed hash keys being names in order to support "Relationship arguments".

SQL::Statement driver support

SineSwiper put the required modules in a gist here:

  https://gist.github.com/4217691

Need to extract them out and write tests for them. He also has stub files for the ones that need them:

  DBIx::Class::Storage::DBI::*
  * = AnyData, CSV, DBM, PO, SNMP, Sys, TreeData

HOW TO EDIT THIS DOCUMENT

Anyone (developer or not) is welcome and encouraged to extend and/or change this document. No idea is too small or too big, even a standalone =head3 is appreciated as it can serve as a seed for further discussion/writeup. The idea is to have a wiki-like process without the headaches of maintaining an actual wiki, and more importantly having the contents of said "wiki" always usable offline. If you are adding/modifying entries in this document, please try to follow the style of already existing TODOs. Also fill in as much information as possible, and don't hesitate to be overly technical - after all this document is intended for developers, and is expected to be quite large and in places quite complex. More info is always better than less.

No attempt has been made yet to sort individual tasks in each TODO section, though ideas on how to do this for better readability are more than welcome.

Todo section

Branching and subsequent merging

The TODO POD section of the master branch contains a commented-out =head2 titled Branch Merge Requirements (it is the first =head2 following the "TODOs" =head1). When a branch is made, authors and/or reviewers should uncomment this heading and add notes on what work is still necessary before merging back to mainline. It is possible that after a merge the heading will not be reverted to its original form, however there is a sanity-check implemented by maint/dbic_todo (and invoked bu the make dist target) which will catch this to prevent CPAN dissemination (perhaps this particular bit warrants a git pre-commit hook protecting master?)

Metadata

To stay in the perl-mandated laziness framework, this document doubles as a holder of metadata on the significance of individual issues. The maint/dbic_todo script executed as part of make dist will stop the dist-building process if it detects any unresolved issues as indicated below.

Flags for each =head3 paragraph are declared as individual elements within an =over / =back block immediately following the =head3. No POD markup is permitted for the flag-lines (no intermediate =item elements). However each line is still separate by double-space (\n\n) as required by the POD specification.

The flags are simple key/value pairs with : separating each key from its value. All flags supplied have their values aggregated in an arrayref. Both the value and the separator : are optional. If a flag value is not supplied its value will be an empty arrayref. Each flag has a short name in addition to its canonical one.

To put it in perl-speek each TODO and its flags are parsed by:

  my $todos;

  while( $todo_pod =~ /
    ^=head3 \s+ ( [^\n]+ ) \n \n              # description as head3
    (?: ^=over \s+ (.+?) \s+ ^=back \n \n )?  # possible flags
  /xmsg) {

    die "Duplicate TODO $1\n" if $todos->{$1};

    $todos->{$1} = [
      defined $2
        ? split /\s*\n+\s*/, $2
        : ()
    ];
  }

Currently recognized flags (and their short names) are:

  • Blocker (BL)

    This is the most important flag. The value is the version at which the blocker goes in effect. If no value is specified, a "full blocker" is assumed - i.e. any release is blocked until this issue is resolved. The version is specified as a perl decimal only - e.g. 0.08200, without leading v or other characters. The distmaker aborts the creation of a tarball if a blocker is found for the version being currently packaged. The idea is to make it dead easy to answer the annoying question "Is master ready to release?".

  • Regression (RG)

    Indicates the issue is a known regression. Optionally indicates in which version the regression was first introduced. It is always preferred to have no known regressions, but in the real world drinking beer trumps chasing bugs, so some known regressions may remain unfixed for some (extended period of) time.

  • Depends (DEP)

    The fix for this issue depends on something else. You can use L</[relevant issue head3 title]> constructs to link to the proper issue if it is listed in this document.

  • RT_Entry (RT)

    The described TODO is a result of (or is independently described by) the RT ticket with the specified number. This flag serves only as a reminder for the maintainers to close the corresponding tickets when the issue is resolved.

  • Needs_Specification (NS)

    Indicates that this is just a floating idea that still needs an actual specification. Ideally such specification comes in the form of a branch, containing a set of failing tests indicating what things should eventually look like.

  • Request_For_Comments (RFC)

    Indicates the presence of a proof of concept (ideally some code with a passing/failing test demonstrating intended behavior), for which the original author is soliciting discussion from other developers before delving into cleaning this idea up for eventual merging.

  • Signed_Off (SIG)

    Indicates which core developers have signed-off on a particular idea/plan

  • ...

    If a (sensible) need arises for more flags - just add them :) Note that you will need to adjust the flag list in maint/dbic_todo as well.

It is important to note that this is a novel experiment in POD semantic overloading abuse, and as such the declaration, format and meaning of individual flags can and probably will be changed down the road. However, if this is to happen the body of text existing at the time will be properly recoded into the newly agreed upon style, and this instruction section will be updated as well.

Something went wrong with that request. Please try again.