On Wed, Jun 7, 2017 at 5:05 PM, sebb <[email protected]> wrote: > On 7 June 2017 at 21:05, Shane Curcuru <[email protected]> wrote: >> sebb wrote on 6/7/17 3:34 PM: >>> cttee1 = ASF::Committee.preload >>> cttee2 = ASF::Committee.load_committee_info >>> >>> cttee1 gets the LDAP committee info >>> >>> cttee2 gets info from committee-info.txt
My point at the bottom of this email is that cttee1 and ctte2 gets info from both places. >From a user of this API point of view, a committee is an object. The caller of the API doesn't generally need to worry about whether that data is from LDAP or committtee info or whatever beyond some initial preloading for performance reasons. >From an implementation point of view, parsing committee-info is a completely different task than calling LDAP (which has common concerns such as retrying). The current library tries to present a unified outward view while partitioning the implementation based on the data source. That being said, if you see a better approach: go for it! - Sam Ruby >> I think the underlying issue is having sufficiently organized and >> explanatory developer docs about the ASF module so that new developers >> can figure out how best to use the models, which offer a lot of data. >> >> The whimsy environment is powerful because it has direct access to all >> sorts of great ASF data. But for a new developer, it's not easy to >> figure out if you should try pulling from an ASF::* class by the API, >> read one of the public_*.json files, or read the source directly >> yourself. Similarly, we now have enough developers and independent >> tools that changes in the ASF:: classes and elsewhere may affect other >> developers. >> >> There certainly are code examples scattered around, but I still just >> voodoo-copypastaed this line from officers/acreq.cgi when I needed a >> list of TLP PMC names: >> >> pmcs = ASF::Committee.list.map(&:name).sort - NON_PMC_UNIX_GROUPS > > I replaced it with ASF::Committee.load_committee_info because the LDAP > Committee class does not have the correct capitalisation. > Nor is the list of LDAP committee groups the canonical list of PMCs. > >> For my case, I don't care about details or even data freshness: I simply >> want the fastest accurate list of all TLP names, (and separately, the >> accurate list of current podling names). > > In which case committee-info.json would be sufficient. > [One can use the approach in the collate-minutes script which loads > the local copy if present, and fetches the URL if not.] > >> - Do we have a preferred ruby class doc style? >> >> - Is there anything else really important to document besides the ASF:: >> gem/classes and the content/structure of the public*.json files (which >> are used by other websites now too)? > > That's really a separate issue. > >>> >>> I find this rather confusing, and it seems to me that it is >>> error-prone and a bit of a maintenance headache, because the Committee >>> class is now defined in multiple files. If the same method name is >>> defined in two classes, which one will be used? I suspect it will >>> depend on the order the files are loaded. >>> >>> Similar considerations apply to the Person class >>> >> >> >> -- >> >> - Shane >> https://www.apache.org/foundation/marks/resources
