[sakai2-tcc] Proposal: how to get rid of the properties documentation staleness in 2.8

[Matthew Jones]

TL;DR - Sakai.properties are a mess. Requiring documentation to be updated
on a website will never work. A central location probably won't be updated
any more often than a website. Documenting these in a location that
developers already know (and love?) seems like the best thing to do. I can
(and am interested) to do some of this work, wouldn't mind a hand and/or
some motivation.

-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
I've just checked my email and there are already over 15 posts on this
subject, all with differing opinions. I'd researched quite a bit for this
and presented on this in Denver, and I *think* only Jean-Francois was there
out of all of the people who have commented so far. I'd talked to him a
little bit about it there, but haven't had much time to make progress on
this since the conference.

(Presentation)
https://prezi.com/secure/85cd86db6fa2dbb628d296604d038eb92728b43a/

I'm going to address a couple of the comments mentioned.

1) Anything on confluence, any other wiki or website is going to get stale.
It will not be updated regularly except by a few very motivated developers,
and even they may forget. A web documentation is good, but it should be
auto-generated from another source (like javadocs)

2) A central source already did exist (in the contrib project config-viewer)
but nobody ever updated anything there. [1] I would think it be unlikely to
be update any more often if it was in /svn/config. We're often having to
track down a few conversion scripts that are missed, and that already exists
in the reference/docs. That also would leave out contrib projects, so it
wouldn't be a catch-all solution. I had also merged in the few properties
changes that had been reported against config viewer [2], but these were few
and haven't been made in a long time.

Also as mentioned not everything in can commit to there.

3) We never had a good system for internationalizing descriptions.

4) Also, dynamic properties editing should be revived, similar to the work
with localization on (SAK-18678<http://jira.sakaiproject.org/browse/SAK-18678>
)

My idea:
I had discussed back in March locally with Zhen that we distribute all of
the properties/messages out of config-viewer into their local tools. I had
written a script to do this but never ran it. This would put the properties
the descriptions (which could be localized) into the space of each tool. So
that people working on them could modify/add as necessary in one common
place. The most obvious place was in the webapp/tools next to the tool
registration. We implemented this as a test in SAK-18076:

https://source.sakaiproject.org/svn/assignment/branches/SAK-18076/assignment-tool/tool/src/webapp/tools/
For example:
*sakai.assignment.properties.config* (contains all of the properties used in
the tool, all properties pre 2.7 are already available in config viewer)
properties.name.1=assignment.searchable_user_fields


properties.type.1=getStrings
properties.tool.1=assignment
properties.version.1=2.8
properties.configurable.1=Y
properties.rule.1=url
properties.qualifier.1=none
properties.nullable.1=Y
properties.default.1=sortname,eid,email

*sakai.assignment.propertiesMessages.config (contains the description of the
properties. Will be internationlized similar to the current system)
*

assignment.searchable_user_fields=The list of user attribute(s) that
instructor/grader can search in the list of submissions view in
Assignments tool. If null, the default setting is the list of "eid",
"email", and "sortname"

We could very easily create a website which would generate a *very nice*
listing of all of the properties organized by tool. (Which is much better
than those organized by first letter) All we would need to get this going
is.

A) Have a local copy of the configuration values in the tools. Get
ToolListener to load these files in a (yet uncreated) service/manager.

  - I'm working finishing the script to parse out specific tool propertiesfrom
config-viewer's property files and distribute them into each tool's webapp
directory.

  - I'll follow this up with a tool to search through your project to find
properties that might have been forgotten or missed by config-viewer (I
wrote this for the conference to generate the prezi)

B) Let the tool maintainers add new config properties as they create them in
one local (usual) space for their tools easily rather than putting them in
config viewer or confluence or somewhere that won't get updated

C) Possibly allow for a central location (ideally database) overriding of
descriptions, new properties for the config-viewer/editor
[1]
https://source.sakaiproject.org/contrib/config-viewer/trunk/properties/src/org/sakaiproject/configviewer/configViewer.properties
[2] http://jira.sakaiproject.org/browse/CNFV

On Thu, Sep 9, 2010 at 11:15 AM, Anthony Whyte <arwhyte at umich.edu> wrote:

> I recommend that we at a minimum:
>
> 1.  work to add all missing properties to the /config project's
> default.sakai.properties file (Beth, Chuck); retire sample.sakai.properties
> and docs/sakai.properties (Beth)
> 2.  given that many properties can be set in different and interesting ways
> (e.g., see SAK-18965) it may prove less than ideal to try to pack such
> explanatory text into a *.properties file (Noah); maintaining a second
> explanatory doc (as John Leasia used to do) may well continue to make sense.
>  That said, I prefer maintaining single files to sets of files.
> 3.  get a commitment from at least two people to work on updating and
> maintaining these files for 2.8 and also 2.7 according to an agreed upon
> format.
> 4.  treat a properties review like a conversion script review; it blocks
> the release until needed updates are added
> 5.  obtain a commitment from at least 2 individuals to take this work on
> for 2.8/2.7.
> 6.  ensure that committers have access to the files should be easy to
> arrange; besides svn-admins all MT members can commit to /config at present;
> adding others like the samigo team  can be done.
>
> As for "not too tough" an assignment--true enough I suppose but don't
> underestimate the time that it will take as well as the attention to detail
> required to update/correct these files.
>
> Anth
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://collab.sakaiproject.org/pipermail/sakai2-tcc/attachments/20100909/db5a5b61/attachment.html