[sakai2-tcc] Fwd: Proposal: how to get rid of the properties documentation staleness in 2.8
May, Megan Marie
mmmay at indiana.edu
Tue Sep 21 12:54:51 PDT 2010
Hi Anth,
I'm not 100% following (but I've been in training all day so I'm a bit fuzzy anyway). It sounds like there was a presentation about this . . can someone provide a link to it?
Also, it sounds like the proposed interim solution is to make changes to 2.8.0. What is the timing we're looking at for including these changes?
Megan
From: sakai2-tcc-bounces at collab.sakaiproject.org [mailto:sakai2-tcc-bounces at collab.sakaiproject.org] On Behalf Of Anthony Whyte
Sent: Tuesday, September 21, 2010 12:59 PM
To: sakai2-tcc at collab.sakaiproject.org Committee Coordination
Subject: [sakai2-tcc] Fwd: Proposal: how to get rid of the properties documentation staleness in 2.8
I'd like to suggest the following interim approach regarding handling properties while Matt works towards his vision of 1) relocating properties to tools, 2) reinvigorating the config viewer/editor projects, 3) get the ToolListener to load the relocated properties in as yet undeveloped a service/manager.
1) create a single property "input" file using the format pioneered by Tony Atkins for config viewer in configViewer.properties (perhaps with a new name)
https://source.sakaiproject.org/contrib/config-viewer/trunk/properties/src/org/sakaiproject/configviewer/configViewer.properties
2) add three more keys:
properties.default (i.e., default value)
properties.description
properties.ticket (e.g., SAK-18042, if easily available)
3) Using the configViewer.properties (probably good up to 2.6.0) as a base add, at a minimum, all properties listed in the current /config default.sakai.properties and any new properties required for 2.8.0
4) Search and add additional missing properties and their default values preferably using a tool Matt hinted at in his proposal:
"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)"
5) Write a script to auto-generate a new default.sakai.properties file (the output file) from the "input" file for use in the final release of 2.8.0. Each entry would have the following format (or thereabouts):
# properties.tool [if prev value = curr value skip]
# properties.ticket: properties.description [if the ticket info is null or blank drop the colon and space; if property.description is null or blank ignore]
# type = properties.type (e.g., bean, string, boolean, enum)
properties.name<http://properties.name> = properties.default
Rerunning the script on a regular basis to ensure the output file is up-to-date is the achilles heel but we can manage this.
6. Let this work feed into Matt's work on his broader proposal for either 2.9 or 2.8.1.
Cheers,
Anthony
Begin forwarded message:
From: Anthony Whyte <arwhyte at umich.edu<mailto:arwhyte at umich.edu>>
Date: September 20, 2010 10:57:47 AM EDT
To: Severance Charles <csev at umich.edu<mailto:csev at umich.edu>>, Jones Matthew <jonespm at umich.edu<mailto:jonespm at umich.edu>>
Subject: Fwd: [sakai2-tcc] Proposal: how to get rid of the properties documentation staleness in 2.8
I just watched Matt's Denver presentation. Nicely done and quite funny. I like the suggestions but since we don't as yet have a service to load the redistributed tool properties and the code freeze is fast approaching perhaps we could do the following:
1. add three more keys
properties.default (i.e., default value)
properties.description
properties.ticket (e.g., SAK-18042)
2. finish/test/run Matt's script to redistribute tool properties to local tools using the config viewer format
3. look for post-2.6 properties and add them. Define properties.default and whenever possible properties.description and properties.ticket. This I assume will take some time.
4. write a script that reads the tool property files and writes out the name, default, ticket and description (at a minimum); other values such as type might prove useful to print out)
# properties.tool [if prev value = curr value skip]
# properties.ticket: properties.description [if the ticket info is null or blank drop the colon and space]
# properties.type (e.g., bean, string, boolean, enum)
properties.name<http://properties.name/> = properties.default
repeat . . .
This file will form the basis of a revised default.sakai.properties file for 2.8.0.
5. work on the new properties loader service for 2.8.1 or 2.9.
6. work on an updated config editor/viewer for 2.8.1 or 2.9
7. whenever the new service/tool goes into production we can retire default.sakai.properties.
To summarize, we leverage Matt's initial work to auto generate default.sakai.properties for 2.8.0. We do 1-4 for 2.8.0; 5-7 we talk further on a timeline for implementation.
If you like this I will send an email to the TCC with my proposal today.
cheers,
Anth
Begin forwarded message:
From: Matthew Jones <jonespm at umich.edu<mailto:jonespm at umich.edu>>
Date: September 9, 2010 11:49:10 AM EDT
To: Anthony Whyte <arwhyte at umich.edu<mailto:arwhyte at umich.edu>>
Cc: Noah Botimer <botimer at umich.edu<mailto:botimer at umich.edu>>, "sakai2-tcc at collab.sakaiproject.org<mailto:sakai2-tcc at collab.sakaiproject.org> Coordination Committee" <sakai2-tcc at collab.sakaiproject.org<mailto:sakai2-tcc at collab.sakaiproject.org>>
Subject: Re: [sakai2-tcc] Proposal: how to get rid of the properties documentation staleness in 2.8
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 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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://collab.sakaiproject.org/pipermail/sakai2-tcc/attachments/20100921/0808e202/attachment-0001.html
More information about the sakai2-tcc
mailing list