[openspending-dev] OpenSpendingJS structure and going forward

[Rufus Pollock]

On 25 May 2014 21:44, Tryggvi Björgvinsson <tryggvi.bjorgvinsson at okfn.org>wrote:

>  On sun 25.maí 2014 20:19, Tryggvi Björgvinsson wrote:
>
> So, basically we have:
>
>   * |src/utils| - common core code
>
>
> I wouldn't call this "core" code. These are utils that can be used by the
> visualisations. For example, formatting amounts, color palettes etc. and
> also the code that wraps the OpenSpending aggregation API (which is
> probably why you refer to this as "core").
>

I call these core for that reason: they are basically a JS wrapper for the
API plus some common utils across visualizations.

Let me reiterate the logic here: reducing cognitive complexity for
contributors. A given contributor will often only be building on a

I also get we want to reduce cognitive complexity for users of the viz but
that isn't solved by having stuff in one repo. Its solved by having good
documentation, a plugin for wordpress, a single compiled JS file etc (which
are orthogonal but very important concerns).

|bob  # the query builder (?)
>
>
> OpenSpending core functionality
>

So could this go from openspending.js then?


>  browser # data browser (?)
>
> OpenSpending core functionality.
> When https://github.com/openspending/openspending/issues/797 has been
> fixed in OpenSpending core, we can remove this functionality as it will no
> longer be used.
>

Right though it could be useful in its own right (maybe ...).

[snip]

>     The Future
>
> Here's a proposal for discussion:
>
>   * Core JS library (no visualizations) lives in openspending.js (could
>     keep openspendingjs name but rename might be useful to symbolize change)
>   * Every visualization gets its own separate repo named e.g.
>     |openspending.{vizname}.js|
>
>
> I don't agree. I think we should keep them in OpenSpendingJS. We are now
> doing releases of OpenSpendingJS (we're up to version 0.4.0) which allow
> everyone to very easily add OpenSpendingJS visualisations to their sites.
>
> The only thing needed is to add the javascript and the css file to the
> page and then you can get the OpenSpending treemap on your page with
> something like this:
>
> <div class="treemap" data-dataset="my-dataset-id"
> drilldowns="cofog1,cofog2,cofog3" year="2014"></div>
>
> (you could also instantiate it with a javascript call:
>
> $('jquery-selector').treemap({data: {dataset:'my-dataset-id',
> drilldowns:['cofog1', 'cofog2', 'cofog3'], year: 2014} });
>

That's great. I think we're getting a bit confused between developer
experience and "deployer/user" experience. I totally agree that deployer
experience should remain simple. That doesn't require us to have a single
repo.

All that said: I should say I'm perfectly happy for us to keep working in
this repo as long as we could simplify a bit more and update the docs. At
the moment I think it is pretty tough to see how one can contribute.

>  Lastly some process points:
>
>   * We should complete clean-up of this repo asap (possibly in tandem
>     with doing the split-out)
>
> Agreed. We need to get OpenSpending core components out and into
> OpenSpending core, preferably by making bob the builder use the most recent
> release of OpenSpendingJS and benefit from the simple javascript/jquery
> calls, but anything works now.
>

OK.

>    * Anyone can develop a new viz but for it to live in openspending
>     orgnanization it needs to "approved" (i.e. checked for quality,
>     documentation, and that there is an ongoing maintainer).
>
> Yes, but that shouldn't be made harder than making a pull request as it is
> now.
>

Agreed.

>    * We document the set of visualizations people can use off-the-shelf
>     somewhere prominent
>
>
> We already have a ticket for this thanks to Michael:
> https://github.com/openspending/openspendingjs/issues/62
>

Understood but you'd have the simplicity of a simple README per viz. I mean
of course we can merge this into one mega-README in openspendingjs but it
does increase cognitive complexity.


>        Why?
>
>   * Core code is more clearly demarcated from apps/viz and can be
>     maintained more easily going forward. It also can become a core
>     dependency that people can more easily use in their own work without
>     getting caught up in viz stuff
>
>
> I think I might be misunderstanding what you mean by core code. What do
> you feel the core code should be?
>

I think its the API wrapper plus common core utils (I'm not exactly sure
what you have more than the API wrapper but I'm sure there is some stuff).

>    * By splitting out visualizations we make them easier to work on and
>     more clearly distinct. Dependencies are also clearer etc.
>
> Why? I think this would make everything even more difficult to work with.
> I would actually rather want us to trim down the repos in our github
> organisation instead of spreading thin over a lot of them.
>

I generally like the "one repo for roughly one purpose" approach as I think
it makes it easier for people though I acknowledge you then need some
overview place (e.g. we have dev.openspending.org which has an overview).


> I would love to hear other people's thoughts on this. Where would you like
> to see OpenSpendingJS go?
>

thanks for the thoughtful comments and I should emphasize I'm very happy to
see us just improve openspendingjs for the time being but I was struggling
a bit to understand how it all fit together.

Rufus
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.okfn.org/pipermail/openspending-dev/attachments/20140526/ebb4c090/attachment-0002.html>