[sakai2-tcc] Fwd: Proposal: how to get rid of the properties documentation staleness in 2.8
Jean-Francois Leveque
jean-francois.leveque at upmc.fr
Wed Oct 6 02:56:48 PDT 2010
I'm afraid we might already or soon will be past early alpha.
Will help when I can but cannot lead or contribute on a regular basis yet.
Please send us updates and information about help needed when you can, Matt.
Cheers,
J-F
Anthony Whyte a écrit :
> The presentation is cool.
>
> https://prezi.com/secure/85cd86db6fa2dbb628d296604d038eb92728b43a/
>
> My suggestion is less so but still I think worth doing. I would think
> we work on it during the early part of the alpha phase. We leverage
> Matt's property sniffer script and produce a file that lists all
> properties in the same manner as Atkins used to do. We capture three
> more bits of data (properties.description, properties.default and
> properties.ticket) as time permits. We then write an output script that
> auto generates a default.sakai.properties. It's basically an audit of
> our properties that we then use to generate our default.sakai.properties
> file.
>
> We do this in a branch. We review it. If the branch output is as good
> we merge it to /config and use it for 2.8.0. If not we refine it for 2.8.1.
>
> If all goes well we will end up with a default.sakai.properties file
> which is actually comprehensive. But this is only for the interim as
> Matt's goal is to relocate properties in the tool webapps and let the
> ToolListener load these properties courtesy of a yet undeveloped
> service. (see the bottom of this thread for his ideas).
>
> At the same time Matt is encouraged to work on his more comprehensive
> solution which he puts in trunk for 2.9.0 but hopefully for some future
> 2.8 maintenance release.
>
> Cheers,
>
> Anth
>
>
> On Sep 21, 2010, at 3:54 PM, May, Megan Marie wrote:
>
>> 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> [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
>> <mailto: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.
More information about the sakai2-tcc
mailing list