whimsical-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ru...@apache.org
Subject [whimsy] branch master updated: update RDoc for ASF::Person; prep podlings
Date Sun, 18 Jun 2017 20:23:47 GMT
This is an automated email from the ASF dual-hosted git repository.

rubys pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/whimsy.git


The following commit(s) were added to refs/heads/master by this push:
     new 2ee01db  update RDoc for ASF::Person; prep podlings
2ee01db is described below

commit 2ee01dbf97c3d259fa7047b4316360688cdcb7fe
Author: Sam Ruby <rubys@intertwingly.net>
AuthorDate: Sun Jun 18 16:23:11 2017 -0400

    update RDoc for ASF::Person; prep podlings
---
 lib/whimsy/asf.rb                          |  2 +-
 lib/whimsy/asf/auth.rb                     |  1 +
 lib/whimsy/asf/icla.rb                     |  3 ++
 lib/whimsy/asf/ldap.rb                     | 43 ++++++++++++++----------
 lib/whimsy/asf/mail.rb                     |  8 +++++
 lib/whimsy/asf/member.rb                   |  4 +++
 lib/whimsy/asf/nominees.rb                 |  3 ++
 lib/whimsy/asf/person.rb                   | 43 +++++++++++++++++++-----
 lib/whimsy/asf/person/override-dates.rb    | 53 +++++++++++++++---------------
 lib/whimsy/asf/{podlings.rb => podling.rb} |  3 --
 lib/whimsy/asf/watch.rb                    |  4 +++
 11 files changed, 111 insertions(+), 56 deletions(-)

diff --git a/lib/whimsy/asf.rb b/lib/whimsy/asf.rb
index 85a1f2e..68e29a7 100644
--- a/lib/whimsy/asf.rb
+++ b/lib/whimsy/asf.rb
@@ -10,7 +10,7 @@ require_relative 'asf/icla'
 require_relative 'asf/auth'
 require_relative 'asf/member'
 require_relative 'asf/site'
-require_relative 'asf/podlings'
+require_relative 'asf/podling'
 require_relative 'asf/person'
 require_relative 'asf/themes'
 
diff --git a/lib/whimsy/asf/auth.rb b/lib/whimsy/asf/auth.rb
index 1091ff6..167a7b9 100644
--- a/lib/whimsy/asf/auth.rb
+++ b/lib/whimsy/asf/auth.rb
@@ -43,6 +43,7 @@ module ASF
   end
 
   class Person
+    # return a list of ASF authorizations that contain this individual
     def auth
       @auths ||= ASF::Authorization.find_by_id(name)
     end
diff --git a/lib/whimsy/asf/icla.rb b/lib/whimsy/asf/icla.rb
index 0ea6ebc..50b7e88 100644
--- a/lib/whimsy/asf/icla.rb
+++ b/lib/whimsy/asf/icla.rb
@@ -199,14 +199,17 @@ module ASF
   end
 
   class Person
+    # ASF::ICLA information for this person.
     def icla
       @icla ||= ASF::ICLA.find_by_id(name)
     end
 
+    # setter for icla, should only be used by ASF::ICLA.preload
     def icla=(icla)
       @icla = icla
     end
 
+    # does this individual have an ICLA on file?
     def icla?
       @icla || ICLA.availids.include?(name)
     end
diff --git a/lib/whimsy/asf/ldap.rb b/lib/whimsy/asf/ldap.rb
index 243811f..0e435f2 100644
--- a/lib/whimsy/asf/ldap.rb
+++ b/lib/whimsy/asf/ldap.rb
@@ -116,7 +116,8 @@ module ASF
     end
 
     # connect to LDAP with a user and password; generally required for
-    # update operations.
+    # update operations.  If a block is passed, the connection will be
+    # closed after the block executes.
     def self.bind(user, password, &block)
       dn = ASF::Person.new(user).dn
       raise ::LDAP::ResultError.new('Unknown user') unless dn
@@ -497,6 +498,8 @@ module ASF
   class Person < Base
     @base = 'ou=people,dc=apache,dc=org'
 
+    # Obtain a list of people (committers).  LDAP filters may be used
+    # to retrieve only a subset.
     def self.list(filter='uid=*')
       ASF.search_one(base, filter, 'uid').flatten.map {|uid| find(uid)}
     end
@@ -529,83 +532,82 @@ module ASF
     end
 
     # return person only if it actually exits
-    def self.[] name
+    def self.[] id
       person = super
       person.attrs['dn'] ? person : nil
     end
 
+    # list of LDAP attributes for this person, populated lazily upon
+    # first reference.
     def attrs
       @attrs ||= LazyHash.new {ASF.search_one(base, "uid=#{name}").first}
     end
 
+    # reload all attributes from LDAP
     def reload!
       @attrs = nil
       attrs
     end
 
-    def public_name
-      return icla.name if icla
-      cn = [attrs['cn']].flatten.first
-      cn.force_encoding('utf-8') if cn.respond_to? :force_encoding
-      return cn if cn
-      ASF.search_archive_by_id(name)
-    end
-
-    def asf_member?
-      ASF::Member.status[name] or ASF.members.include? self
-    end
-
-    def asf_officer_or_member?
-      asf_member? or ASF.pmc_chairs.include? self
-    end
-
+    # Is this person listed in the committers LDAP group?
     def asf_committer?
        ASF::Group.new('committers').include? self
     end
 
+    # determine if the person is banned.  If scanning a large list, consider
+    # preloading the <tt>loginShell</tt> attributes for these people.
     def banned?
       # FreeBSD uses /usr/bin/false; Ubuntu uses /bin/false
       not attrs['loginShell'] or %w(/bin/false bin/nologin bin/no-cla).any? {|a| attrs['loginShell'].first.include?
a}
     end
 
+    # primary mail addresses
     def mail
       attrs['mail'] || []
     end
 
+    # list all of the alternative emails for this person
     def alt_email
       attrs['asf-altEmail'] || []
     end
 
+    # list all of the PGP key fingerprints
     def pgp_key_fingerprints
       attrs['asf-pgpKeyFingerprint'] || []
     end
 
+    # list all of the ssh public keys
     def ssh_public_keys
       attrs['sshPublicKey'] || []
     end
 
+    # list all of the personal URLs
     def urls
       attrs['asf-personalURL'] || []
     end
 
+    # list of LDAP committees that this individual is a member of
     def committees
       weakref(:committees) do
         Committee.list("member=uid=#{name},#{base}")
       end
     end
 
+    # list of LDAP projects that this individual is a member of
     def projects
       weakref(:projects) do
         Project.list("member=uid=#{name},#{base}")
       end
     end
 
+    # list of LDAP groups that this individual is a member of
     def groups
       weakref(:groups) do
         Group.list("memberUid=#{name}")
       end
     end
 
+    # list of LDAP services that this individual is a member of
     def services
       weakref(:services) do
         Service.list("member=#{dn}")
@@ -617,6 +619,9 @@ module ASF
       "uid=#{name},#{ASF::Person.base}"
     end
 
+    # Allow artibtrary LDAP attibutes to be referenced as object properties.
+    # Example: <tt>ASF::Person.find('rubys').cn</tt>.  Can also be used
+    # to modify an LDAP attribute.
     def method_missing(name, *args)
       if name.to_s.end_with? '=' and args.length == 1
         return modify(name.to_s[0..-2], args)
@@ -642,6 +647,8 @@ module ASF
       end
     end
 
+    # update an LDAP attribute for this person.  This needs to be run
+    # either inside or after ASF::LDAP.bind.
     def modify(attr, value)
       ASF::LDAP.modify(self.dn, [ASF::Base.mod_replace(attr.to_s, value)])
       attrs[attr.to_s] = value
diff --git a/lib/whimsy/asf/mail.rb b/lib/whimsy/asf/mail.rb
index 5ce77a3..4cbcbe7 100644
--- a/lib/whimsy/asf/mail.rb
+++ b/lib/whimsy/asf/mail.rb
@@ -114,6 +114,7 @@ module ASF
   end
 
   class Person < Base
+    # find a Person by email address
     def self.find_by_email(value)
       value.downcase!
 
@@ -121,6 +122,9 @@ module ASF
       return person if person
     end
 
+    # List of inactive email addresses: currently only contains the address in
+    # <tt>iclas.txt</tt> if it is not contained in the list of active email
+    # addresses.
     def obsolete_emails
       return @obsolete_emails if @obsolete_emails
       result = []
@@ -132,10 +136,14 @@ module ASF
       @obsolete_emails = result
     end
 
+    # Active emails: primary email address, alt email addresses, and 
+    # member email addresses.
     def active_emails
       (mail + alt_email + member_emails).uniq
     end
 
+    # All known email addresses: includes active, obsolete, and apache.org
+    # email addresses.
     def all_mail
       (active_emails + obsolete_emails + ["#{id}@apache.org"]).uniq
     end
diff --git a/lib/whimsy/asf/member.rb b/lib/whimsy/asf/member.rb
index 50152e2..174ed76 100644
--- a/lib/whimsy/asf/member.rb
+++ b/lib/whimsy/asf/member.rb
@@ -163,16 +163,20 @@ module ASF
   end
 
   class Person
+    # text entry from <tt>members.txt</tt>.  If <tt>full</tt> is
<tt>true</tt>,
+    # this will also include the text delimiters.
     def members_txt(full = false)
       prefix, suffix = " *) ", "\n\n" if full
       @members_txt ||= ASF::Member.find_text_by_id(id)
       "#{prefix}#{@members_txt}#{suffix}" if @members_txt
     end
 
+    # email addresses from members.txt
     def member_emails
       ASF::Member.emails(members_txt)
     end
 
+    # Person's name as found in members.txt
     def member_name
       members_txt[/(\w.*?)\s*(\/|$)/, 1] if members_txt
     end
diff --git a/lib/whimsy/asf/nominees.rb b/lib/whimsy/asf/nominees.rb
index 9b100a1..bd81cb0 100644
--- a/lib/whimsy/asf/nominees.rb
+++ b/lib/whimsy/asf/nominees.rb
@@ -4,6 +4,8 @@ module ASF
 
   class Person < Base
   
+    # Return a hash of nominated members.  Keys are ASF::Person objects,
+    # values are the nomination text.
     def self.member_nominees
       begin
         return Hash[@member_nominees.to_a] if @member_nominees
@@ -31,6 +33,7 @@ module ASF
       nominees
     end
 
+    # Return the member nomination text for this individual
     def member_nomination
       @member_nomination ||= Person.member_nominees[self]
     end
diff --git a/lib/whimsy/asf/person.rb b/lib/whimsy/asf/person.rb
index 5480438..b021a8c 100644
--- a/lib/whimsy/asf/person.rb
+++ b/lib/whimsy/asf/person.rb
@@ -1,11 +1,13 @@
-#
-# support for sorting of names
-#
-
 require_relative 'person/override-dates.rb'
 
 module ASF
 
+  #
+  # An instance of this class represents a person.  Data comes from a variety
+  # of sources: LDAP, <tt>asf--authorization-template</tt>, <tt>iclas.txt</tt>,
+  # <tt>members.txt</tt>, <tt>nominated-members.txt</tt>, and
+  # <tt>potential-member-watch-list.txt</tt>.
+
   class Person
     # sort support
 
@@ -61,6 +63,7 @@ module ASF
       name.strip.gsub /[^\w]+/, '-'
     end
 
+    # generational suffixes
     SUFFIXES = /^([Jj][Rr]\.?|I{2,3}|I?V|VI{1,3}|[A-Z]\.)$/
 
     # rearrange line in an order suitable for sorting
@@ -76,20 +79,44 @@ module ASF
       name.reverse.join(' ').downcase
     end
 
+    # return name in a sortable order (last name first)
     def sortable_name
       Person.sortable_name(self.public_name)
     end
 
     # determine account creation date.  Notes:
-    #  *) LDAP info is not accurate for dates prior to 2009.  See
-    #     person/override-dates.rb
-    #  *) createTimestamp isn't loaded by default (but can either be preloaded
-    #     or fetched explicitly)
+    # *  LDAP info is not accurate for dates prior to 2009.  See
+    #    person/override-dates.rb
+    # *  createTimestamp isn't loaded by default (but can either be preloaded
+    #    or fetched explicitly)
     def createTimestamp
       result = @@create_date[name] 
       result ||= attrs['createTimestamp'][0]
       result ||= ASF.search_one(base, "uid=#{name}", 'createTimestamp')[0][0]
       result
     end
+
+    # return person's public name, searching a variety of sources, starting
+    # with iclas.txt, then LDAP, and finally the archives.
+    def public_name
+      return icla.name if icla
+      cn = [attrs['cn']].flatten.first
+      cn.force_encoding('utf-8') if cn.respond_to? :force_encoding
+      return cn if cn
+      ASF.search_archive_by_id(name)
+    end
+
+    # Returns <tt>true</tt> if this person is listed as an ASF member in
+    # _either_ LDAP or <tt>members.txt</tt>.
+    def asf_member?
+      ASF::Member.status[name] or ASF.members.include? self
+    end
+
+    # Returns <tt>true</tt> if this person is listed as an ASF member in
+    # _either_ LDAP or <tt>members.txt</tt> or this person is listed as
+    # an PMC chair in LDAP.
+    def asf_officer_or_member?
+      asf_member? or ASF.pmc_chairs.include? self
+    end
   end
 end
diff --git a/lib/whimsy/asf/person/override-dates.rb b/lib/whimsy/asf/person/override-dates.rb
index a7bd34d..2527491 100644
--- a/lib/whimsy/asf/person/override-dates.rb
+++ b/lib/whimsy/asf/person/override-dates.rb
@@ -1,30 +1,31 @@
-# Corrected creation dates for accounts created before May 2009
-#
-# On the 7th July 2004, a common format for account creation notifications to
-# PMCs (Subject: [NOTICE] Account created: First Last (uid)) was introduced.
-# By grepping the private mail archives for these, creation dates between
-# 20040707 and 20090519 have be found.
-#
-# In 2002 and 2003, many but not all creation requests were sent to root or
-# the pmc with a format "Preferred userid: (uid)" or "Username: (uid)", these
-# have also been found from grepping private mail archives (but a few we may
-# treat the requested date as the creation date). Not all creation requests
-# from this period are covered though, as the request email format wasn't
-# required.
-#
-# Other dates have been found from scanning SVN logs for the earliest
-# appearance of the availid. These are indicated with a comment giving the revision number
-# It's not known how accurate these dates are.
-#
-# For those accounts with the "dummy" creation date set in LDAP of 20090519,
-# where no other PMC request or notification emails have been found via
-# grep, a "more likely" default of 20040701 dummy value is set as an override.
-#
-# TODO fix the default dates
-#
-# See https://issues.apache.org/jira/browse/WHIMSY-63
-
 class ASF::Person
+
+  # Corrected creation dates for accounts created before May 2009
+  #
+  # On the 7th July 2004, a common format for account creation notifications to
+  # PMCs (Subject: [NOTICE] Account created: First Last (uid)) was introduced.
+  # By grepping the private mail archives for these, creation dates between
+  # 20040707 and 20090519 have be found.
+  #
+  # In 2002 and 2003, many but not all creation requests were sent to root or
+  # the pmc with a format "Preferred userid: (uid)" or "Username: (uid)", these
+  # have also been found from grepping private mail archives (but a few we may
+  # treat the requested date as the creation date). Not all creation requests
+  # from this period are covered though, as the request email format wasn't
+  # required.
+  #
+  # Other dates have been found from scanning SVN logs for the earliest
+  # appearance of the availid. These are indicated with a comment giving the
+  # revision number It's not known how accurate these dates are.
+  #
+  # For those accounts with the "dummy" creation date set in LDAP of 20090519,
+  # where no other PMC request or notification emails have been found via
+  # grep, a "more likely" default of 20040701 dummy value is set as an override.
+  #
+  # TODO fix the default dates
+  #
+  # See https://issues.apache.org/jira/browse/WHIMSY-63
+
   @@create_date = {
     "aadamchik"=>"20060414170210Z",
     "aaf"=>"20080522205123Z",
diff --git a/lib/whimsy/asf/podlings.rb b/lib/whimsy/asf/podling.rb
similarity index 99%
rename from lib/whimsy/asf/podlings.rb
rename to lib/whimsy/asf/podling.rb
index 1a5862b..a6aced3 100644
--- a/lib/whimsy/asf/podlings.rb
+++ b/lib/whimsy/asf/podling.rb
@@ -327,7 +327,4 @@ module ASF
       Podling.namesearch[display_name]
     end
   end
-
-  # more backwards compatibility
-  Podlings = Podling
 end
diff --git a/lib/whimsy/asf/watch.rb b/lib/whimsy/asf/watch.rb
index 8e691aa..337d8d1 100644
--- a/lib/whimsy/asf/watch.rb
+++ b/lib/whimsy/asf/watch.rb
@@ -2,6 +2,9 @@ module ASF
 
   class Person < Base
   
+    # Return a hash of individuals in the member watch list.  Keys are
+    # ASF::Person objects, values are the text from
+    # <tt>potential-member-watch-list.txt</tt>..
     def self.member_watch_list
       return @member_watch_list if @member_watch_list
 
@@ -29,6 +32,7 @@ module ASF
       @member_watch_list = member_watch_list
     end
 
+    # This person's entry in <tt>potential-member-watch-list.txt</tt>.
     def member_watch
       text = Person.member_watch_list[self]
       if text

-- 
To stop receiving notification emails like this one, please contact
['"commits@whimsical.apache.org" <commits@whimsical.apache.org>'].

Mime
View raw message