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: RDoc comments for Podling and Project
Date Sun, 18 Jun 2017 23:54:12 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 bb26e40  RDoc comments for Podling and Project
bb26e40 is described below

commit bb26e40e77a7abaccc06d96fd2dab0ce34db4a88
Author: Sam Ruby <rubys@intertwingly.net>
AuthorDate: Sun Jun 18 19:53:19 2017 -0400

    RDoc comments for Podling and Project
---
 lib/whimsy/asf/ldap.rb    | 19 ++++++++-----
 lib/whimsy/asf/mail.rb    |  1 +
 lib/whimsy/asf/podling.rb | 68 ++++++++++++++++++++++++++++++++++++++++-------
 3 files changed, 73 insertions(+), 15 deletions(-)

diff --git a/lib/whimsy/asf/ldap.rb b/lib/whimsy/asf/ldap.rb
index 0e435f2..d449ccf 100644
--- a/lib/whimsy/asf/ldap.rb
+++ b/lib/whimsy/asf/ldap.rb
@@ -771,6 +771,7 @@ module ASF
   class Project < Base
     @base = 'ou=project,ou=groups,dc=apache,dc=org'
 
+    # obtain a list of projects from LDAP
     def self.list(filter='cn=*')
       ASF.search_one(base, filter, 'cn').flatten.map {|cn| Project.find(cn)}
     end
@@ -820,14 +821,18 @@ module ASF
       self.members = committers
     end
 
+    # setter for members, should only be called by #preload.
     def members=(members)
       @members = WeakRef.new(members)
     end
 
+    # setter for owners, should only be called by #preload.
     def owners=(owners)
       @owners = WeakRef.new(owners)
     end
 
+    # list of committers on this project.  Stored in LDAP as a <tt>member</tt>
+    # attribute.
     def members
       members = weakref(:members) do
         ASF.search_one(base, "cn=#{name}", 'member').flatten
@@ -836,6 +841,8 @@ module ASF
       members.map {|uid| Person.find uid[/uid=(.*?),/,1]}
     end
 
+    # list of owners on this project.  Stored in LDAP as a <tt>owners</tt>
+    # attribute.
     def owners
       owners = weakref(:owners) do
         ASF.search_one(base, "cn=#{name}", 'owner').flatten
@@ -844,13 +851,13 @@ module ASF
       owners.map {|uid| Person.find uid[/uid=(.*?),/,1]}
     end
 
-    # remove people from a project as owners and members
+    # remove people from a project as owners and members in LDAP
     def remove(people)
       remove_owners(people)
       remove_members(people)
     end
 
-    # remove people as owners of a project
+    # remove people as owners of a project in LDAP
     def remove_owners(people)
       @owners = nil
       removals = (Array(people) & owners).map(&:dn)
@@ -861,7 +868,7 @@ module ASF
       @owners = nil
     end
 
-    # remove people as members of a project
+    # remove people as members of a project in LDAP
     def remove_members(people)
       @members = nil
       removals = (Array(people) & members).map(&:dn)
@@ -872,13 +879,13 @@ module ASF
       @members = nil
     end
 
-    # add people to a project as members and owners
+    # add people to a project as members and owners in LDAP
     def add(people)
       add_owners(people)
       add_members(people)
     end
 
-    # add people as owners of a project
+    # add people as owners of a project in LDAP
     def add_owners(people)
       @owners = nil
       additions = (Array(people) - owners).map(&:dn)
@@ -889,7 +896,7 @@ module ASF
       @owners = nil
     end
 
-    # add people as members of a project
+    # add people as members of a project in LDAP
     def add_members(people)
       @members = nil
       additions = (Array(people) - members).map(&:dn)
diff --git a/lib/whimsy/asf/mail.rb b/lib/whimsy/asf/mail.rb
index 4cbcbe7..520942a 100644
--- a/lib/whimsy/asf/mail.rb
+++ b/lib/whimsy/asf/mail.rb
@@ -183,6 +183,7 @@ module ASF
   end
 
   class Podling
+    # base name used in constructing mailing list name.
     def mail_list
       name
     end
diff --git a/lib/whimsy/asf/podling.rb b/lib/whimsy/asf/podling.rb
index a6aced3..6d5906a 100644
--- a/lib/whimsy/asf/podling.rb
+++ b/lib/whimsy/asf/podling.rb
@@ -4,9 +4,40 @@ require 'psych'
 require_relative '../asf'
 
 module ASF
+
+  # Represents a podling, drawing information from both podlings.xml and LDAP.
+
   class Podling
     include Enumerable
-    attr_accessor :name, :resource, :resourceAliases, :status, :description, :mentors, :champion,
:reporting, :monthly
+
+    # name of the podling, from podlings.xml
+    attr_writer :name
+
+    # name of the podling, from podlings.xml
+    attr_accessor  :resource
+
+    # array of aliases for the podling, from podlings.xml
+    attr_accessor  :resourceAliases
+
+    # status of the podling, from podlings.xml.  Valid values are
+    # <tt>current</tt>, <tt>graduated</tt>, or <tt>retired</tt>.
+    attr_accessor  :status
+
+    # description of the podling, from podlings.xml
+    attr_accessor  :description
+
+    # list of userids of the mentors, from podlings.xml
+    attr_accessor  :mentors
+
+    # userid of the champion, from podlings.xml
+    attr_accessor  :champion
+
+    # list of months in the normal reporting schedule for this podling.
+    attr_accessor  :reporting
+
+    # if reporting monthly, a list of months reports are expected.  Can also
+    # ge <tt>nil</tt> or an empty list.  From podlings.xml.
+    attr_accessor  :monthly
 
     # three consecutive months, starting with this one
     def quarter
@@ -42,7 +73,8 @@ module ASF
       # - longname
     end
 
-    # map resource to name
+    # name for this podling, originally from the resource attribute in
+    # podlings.xml.
     def name
       @resource
     end
@@ -52,12 +84,13 @@ module ASF
       @resource
     end
 
-    # map name to display_name
+    # display name for this podling, originally from the name attribute in
+    # podlings.xml.
     def display_name
       @name || @resource
     end
 
-    # parse startdate
+    # date this podling was accepted for incubation
     def startdate
       return unless @startdate
       # assume 15th (mid-month) if no day specified
@@ -67,7 +100,8 @@ module ASF
       nil
     end
 
-    # parse enddate
+    # date this podling either retired or graduated.  <tt>nil</tt> for
+    # current podlings.
     def enddate
       return unless @enddate
       # assume 15th (mid-month) if no day specified
@@ -77,6 +111,7 @@ module ASF
       nil
     end
 
+    # number of days in incubation
     def duration
       last = enddate || Date.today
       first = startdate || Date.today
@@ -100,7 +135,7 @@ module ASF
       self.reporting + self.monthly
     end
 
-    # list of podlings
+    # list of all podlings, regardless of status
     def self.list
       incubator_content = ASF::SVN['asf/incubator/public/trunk/content']
       podlings_xml = "#{incubator_content}/podlings.xml"
@@ -125,10 +160,13 @@ module ASF
       @list
     end
 
+    # list of current podlings
     def self.current
       list.select { |podling| podling.status == 'current' }
     end
 
+    # last modified time of podlings.xml in the local working directory,
+    # as of the last time #list was called.
     def self.mtime
       @mtime
     end
@@ -160,12 +198,12 @@ module ASF
       return self.send name if self.respond_to? name
     end
 
-    # list of PPMC owners
+    # list of PPMC owners from LDAP
     def owners
       ASF::Project.find(id).owners
     end
 
-    # list of PPMC members
+    # list of PPMC committers from LDAP
     def members
       ASF::Project.find(id).members
     end
@@ -214,6 +252,9 @@ module ASF
       return true if list.start_with?("incubator-#{_name}-")
     end
 
+    # status information associated with this podling.  Keys in the hash return
+    # include: <tt>:ipClearance</tt>, <tt>:sourceControl</tt>, <tt>:wiki</tt>,
+    # <tt>:jira</tt>, <tt>:proposal</tt>, <tt>:website</tt>,
<tt>:news</tt>
     def podlingStatus
       # resource can contain '-'
       @resource.untaint if @resource =~ /\A[-\w]+\z/
@@ -244,7 +285,11 @@ module ASF
       end
     end
 
-    # Return the instance as a hash
+    # Return the instance as a hash.  Keys in the hash are:
+    # <tt>:name</tt>, <tt>:status</tt>, <tt>:description</tt>,
+    # <tt>:mentors</tt>, <tt>:startdate</tt>, <tt>:champion</tt>,
+    # <tt>:reporting</tt>, <tt>:resource</tt>, <tt>:resourceAliases</tt>,
+    # <tt>:sponsor</tt>, <tt>:duration</tt>, and <tt>:podlingStatus</tt>
     def as_hash # might be confusing to use to_h here?
       hash = {
           name: @name,
@@ -280,6 +325,11 @@ module ASF
       hash
     end
 
+    # status information associated with this podling.  Keys in the hash return
+    # include: <tt>:issueTracker</tt>, <tt>:wiki</tt>, <tt>:jira</tt>,
+    # <tt>:proposal</tt>, <tt>:asfCopyright, <tt>:distributionRights</tt>,
+    # <tt>:ipClearance</tt>, <tt>:sga</tt>, <tt>:website</tt>,
+    # <tt>:graduationDate</tt>, <tt>:resolution</tt>
     def default_status
       {
           issueTracker: 'jira',

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

Mime
View raw message