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

[Jean-Francois Leveque]

Hi all,

Sorry for being so late on this being quite busy but today I've found 
undocumented properties and thought it was a good time to use the small 
spare time I have on this.

If you want to know which undocumented in 
http://confluence.sakaiproject.org/display/DOC/Sakai+Properties+Reference+-+Full 
properties I've found, they are timeoutDialogEnabled and 
timeoutDialogWarningSeconds and documented in 
http://source.sakaiproject.org/viewsvn/portal/trunk/portal-impl/impl/src/java/org/sakaiproject/portal/charon/handlers/TimeoutDialogHandler.java?view=markup

Comments follow. I've removed parts of Matthew's mail to keep only the 
comments' context.

Matthew Jones a écrit :
> 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.

...

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

Maybe we could use something similar to the detection done in SAK-18678 
on QA servers to learn about properties requested by the code when it's 
used.

> 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. 

We could at least ask what tool leads, MT included, think about this.

> 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 have 2 files and only one is supposed to be translated. This leaves 
us with having to find a way to get tool titles in their translations 
globally.

My only other comment is about the file naming. I thin they should share 
a common prefix. Using the tool ID such as sakai.assignment.grades is a 
good idea. I'd like a second part like configProperties and a third part 
with config for the file that doesn't have to be translated and 
properties for the file that has to. This makes:
sakai.assignment.grades.configProperties.config and 
sakai.assignment.grades.configProperties.properties

What do you think?

> 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.

There are properties that are used across tools. Maybe we should change 
the naming of properties so that listing by tools and by first letter 
would both make sense.

> 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 
> properties from 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 
> <mailto: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