jro_apps/redmine Commit - r2536:c2dfffd7f267

Added some RDoc documentation for some models....

Eric Davis -

r2536:c2dfffd7f267

parent child

Context file:

r2536:c2dfffd7f267

Collapse all files

app/models/issue.rb +10 0

             # redMine - project management software
             # Copyright (C) 2006-2007  Jean-Philippe Lang
             #
             # This program is free software; you can redistribute it and/or
             # modify it under the terms of the GNU General Public License
             # as published by the Free Software Foundation; either version 2
             # of the License, or (at your option) any later version.
             #
             # This program is distributed in the hope that it will be useful,
             # but WITHOUT ANY WARRANTY; without even the implied warranty of
             # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
             # GNU General Public License for more details.
             #
             # You should have received a copy of the GNU General Public License
             # along with this program; if not, write to the Free Software
             # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
             class Issue < ActiveRecord::Base
               belongs_to :project
               belongs_to :tracker
               belongs_to :status, :class_name => 'IssueStatus', :foreign_key => 'status_id'
               belongs_to :author, :class_name => 'User', :foreign_key => 'author_id'
               belongs_to :assigned_to, :class_name => 'User', :foreign_key => 'assigned_to_id'
               belongs_to :fixed_version, :class_name => 'Version', :foreign_key => 'fixed_version_id'
               belongs_to :priority, :class_name => 'Enumeration', :foreign_key => 'priority_id'
               belongs_to :category, :class_name => 'IssueCategory', :foreign_key => 'category_id'
               has_many :journals, :as => :journalized, :dependent => :destroy
               has_many :time_entries, :dependent => :delete_all
               has_and_belongs_to_many :changesets, :order => "#{Changeset.table_name}.committed_on ASC, #{Changeset.table_name}.id ASC"
               has_many :relations_from, :class_name => 'IssueRelation', :foreign_key => 'issue_from_id', :dependent => :delete_all
               has_many :relations_to, :class_name => 'IssueRelation', :foreign_key => 'issue_to_id', :dependent => :delete_all
               acts_as_attachable :after_remove => :attachment_removed
               acts_as_customizable
               acts_as_watchable
               acts_as_searchable :columns => ['subject', "#{table_name}.description", "#{Journal.table_name}.notes"],
                                  :include => [:project, :journals],
                                  # sort by id so that limited eager loading doesn't break with postgresql
                                  :order_column => "#{table_name}.id"
               acts_as_event :title => Proc.new {|o| "#{o.tracker.name} ##{o.id}: #{o.subject}"},
                             :url => Proc.new {|o| {:controller => 'issues', :action => 'show', :id => o.id}},
                             :type => Proc.new {|o| 'issue' + (o.closed? ? ' closed' : '') }
               acts_as_activity_provider :find_options => {:include => [:project, :author, :tracker]},
                                         :author_key => :author_id
               validates_presence_of :subject, :priority, :project, :tracker, :author, :status
               validates_length_of :subject, :maximum => 255
               validates_inclusion_of :done_ratio, :in => 0..100
               validates_numericality_of :estimated_hours, :allow_nil => true
               named_scope :visible, lambda {|*args| { :include => :project,
                                                       :conditions => Project.allowed_to_condition(args.first || User.current, :view_issues) } }
               named_scope :open, :conditions => ["#{IssueStatus.table_name}.is_closed = ?", false], :include => :status
               # Returns true if usr or current user is allowed to view the issue
               def visible?(usr=nil)
                 (usr || User.current).allowed_to?(:view_issues, self.project)
               end
               def after_initialize
                 if new_record?
                   # set default values for new records only
                   self.status ||= IssueStatus.default
                   self.priority ||= Enumeration.priorities.default
                 end
               end
               # Overrides Redmine::Acts::Customizable::InstanceMethods#available_custom_fields
               def available_custom_fields
                 (project && tracker) ? project.all_issue_custom_fields.select {|c| tracker.custom_fields.include? c } : []
               end
               def copy_from(arg)
                 issue = arg.is_a?(Issue) ? arg : Issue.find(arg)
                 self.attributes = issue.attributes.dup
                 self.custom_values = issue.custom_values.collect {|v| v.clone}
                 self
               end
               # Moves/copies an issue to a new project and tracker
               # Returns the moved/copied issue on success, false on failure
               def move_to(new_project, new_tracker = nil, options = {})
                 options ||= {}
                 issue = options[:copy] ? self.clone : self
                 transaction do
                   if new_project && issue.project_id != new_project.id
                     # delete issue relations
                     unless Setting.cross_project_issue_relations?
                       issue.relations_from.clear
                       issue.relations_to.clear
                     end
                     # issue is moved to another project
                     # reassign to the category with same name if any
                     new_category = issue.category.nil? ? nil : new_project.issue_categories.find_by_name(issue.category.name)
                     issue.category = new_category
                     issue.fixed_version = nil
                     issue.project = new_project
                   end
                   if new_tracker
                     issue.tracker = new_tracker
                   end
                   if options[:copy]
                     issue.custom_field_values = self.custom_field_values.inject({}) {|h,v| h[v.custom_field_id] = v.value; h}
                     issue.status = self.status
                   end
                   if issue.save
                     unless options[:copy]
                       # Manually update project_id on related time entries
                       TimeEntry.update_all("project_id = #{new_project.id}", {:issue_id => id})
                     end
                   else
                     Issue.connection.rollback_db_transaction
                     return false
                   end
                 end
                 return issue
               end
               def priority_id=(pid)
                 self.priority = nil
                 write_attribute(:priority_id, pid)
               end
               def estimated_hours=(h)
                 write_attribute :estimated_hours, (h.is_a?(String) ? h.to_hours : h)
               end
               def validate
                 if self.due_date.nil? && @attributes['due_date'] && !@attributes['due_date'].empty?
                   errors.add :due_date, :not_a_date
                 end
                 if self.due_date and self.start_date and self.due_date < self.start_date
                   errors.add :due_date, :greater_than_start_date
                 end
                 if start_date && soonest_start && start_date < soonest_start
                   errors.add :start_date, :invalid
                 end
               end
               def validate_on_create
                 errors.add :tracker_id, :invalid unless project.trackers.include?(tracker)
               end
               def before_create
                 # default assignment based on category
                 if assigned_to.nil? && category && category.assigned_to
                   self.assigned_to = category.assigned_to
                 end
               end
               def before_save
                 if @current_journal
                   # attributes changes
                   (Issue.column_names - %w(id description)).each {|c|
                     @current_journal.details << JournalDetail.new(:property => 'attr',
                                                                   :prop_key => c,
                                                                   :old_value => @issue_before_change.send(c),
                                                                   :value => send(c)) unless send(c)==@issue_before_change.send(c)
                   }
                   # custom fields changes
                   custom_values.each {|c|
                     next if (@custom_values_before_change[c.custom_field_id]==c.value ||
                               (@custom_values_before_change[c.custom_field_id].blank? && c.value.blank?))
                     @current_journal.details << JournalDetail.new(:property => 'cf',
                                                                   :prop_key => c.custom_field_id,
                                                                   :old_value => @custom_values_before_change[c.custom_field_id],
                                                                   :value => c.value)
                   }
                   @current_journal.save
                 end
                 # Save the issue even if the journal is not saved (because empty)
                 true
               end
               def after_save
                 # Reload is needed in order to get the right status
                 reload
                 # Update start/due dates of following issues
                 relations_from.each(&:set_issue_to_dates)
                 # Close duplicates if the issue was closed
                 if @issue_before_change && !@issue_before_change.closed? && self.closed?
                   duplicates.each do |duplicate|
                     # Reload is need in case the duplicate was updated by a previous duplicate
                     duplicate.reload
                     # Don't re-close it if it's already closed
                     next if duplicate.closed?
                     # Same user and notes
                     duplicate.init_journal(@current_journal.user, @current_journal.notes)
                     duplicate.update_attribute :status, self.status
                   end
                 end
               end
               def init_journal(user, notes = "")
                 @current_journal ||= Journal.new(:journalized => self, :user => user, :notes => notes)
                 @issue_before_change = self.clone
                 @issue_before_change.status = self.status
                 @custom_values_before_change = {}
                 self.custom_values.each {|c| @custom_values_before_change.store c.custom_field_id, c.value }
                 # Make sure updated_on is updated when adding a note.
                 updated_on_will_change!
                 @current_journal
               end
               # Return true if the issue is closed, otherwise false
               def closed?
                 self.status.is_closed?
               end
               # Returns true if the issue is overdue
               def overdue?
                 !due_date.nil? && (due_date < Date.today) && !status.is_closed?
               end
               # Users the issue can be assigned to
               def assignable_users
                 project.assignable_users
               end
               # Returns an array of status that user is able to apply
               def new_statuses_allowed_to(user)
                 statuses = status.find_new_statuses_allowed_to(user.role_for_project(project), tracker)
                 statuses << status unless statuses.empty?
                 statuses.uniq.sort
               end
               # Returns the mail adresses of users that should be notified for the issue
               def recipients
                 recipients = project.recipients
                 # Author and assignee are always notified unless they have been locked
                 recipients << author.mail if author && author.active?
                 recipients << assigned_to.mail if assigned_to && assigned_to.active?
                 recipients.compact.uniq
               end
+              # Returns the total number of hours spent on this issue.
+              #
+              # Example:
+              #   spent_hours => 0
+              #   spent_hours => 50
               def spent_hours
                 @spent_hours ||= time_entries.sum(:hours) || 0
               end
               def relations
                 (relations_from + relations_to).sort
               end
               def all_dependent_issues
                 dependencies = []
                 relations_from.each do |relation|
                   dependencies << relation.issue_to
                   dependencies += relation.issue_to.all_dependent_issues
                 end
                 dependencies
               end
               # Returns an array of issues that duplicate this one
               def duplicates
                 relations_to.select {|r| r.relation_type == IssueRelation::TYPE_DUPLICATES}.collect {|r| r.issue_from}
               end
               # Returns the due date or the target due date if any
               # Used on gantt chart
               def due_before
                 due_date || (fixed_version ? fixed_version.effective_date : nil)
               end
+              # Returns the time scheduled for this issue.
+              #
+              # Example:
+              #   Start Date: 2/26/09, End Date: 3/04/09
+              #   duration => 6
               def duration
                 (start_date && due_date) ? due_date - start_date : 0
               end
               def soonest_start
                 @soonest_start ||= relations_to.collect{|relation| relation.successor_soonest_start}.compact.min
               end
               def to_s
                 "#{tracker} ##{id}: #{subject}"
               end
               private
               # Callback on attachment deletion
               def attachment_removed(obj)
                 journal = init_journal(User.current)
                 journal.details << JournalDetail.new(:property => 'attachment',
                                                      :prop_key => obj.id,
                                                      :old_value => obj.filename)
                 journal.save
               end
             end

app/models/mailer.rb +46 -2

             # redMine - project management software
             # Copyright (C) 2006-2007  Jean-Philippe Lang
             #
             # This program is free software; you can redistribute it and/or
             # modify it under the terms of the GNU General Public License
             # as published by the Free Software Foundation; either version 2
             # of the License, or (at your option) any later version.
             #
             # This program is distributed in the hope that it will be useful,
             # but WITHOUT ANY WARRANTY; without even the implied warranty of
             # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
             # GNU General Public License for more details.
             #
             # You should have received a copy of the GNU General Public License
             # along with this program; if not, write to the Free Software
             # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
             class Mailer < ActionMailer::Base
               helper :application
               helper :issues
               helper :custom_fields
               include ActionController::UrlWriter
               include Redmine::I18n
               def self.default_url_options
                 h = Setting.host_name
                 h = h.to_s.gsub(%r{\/.*$}, '') unless Redmine::Utils.relative_url_root.blank?
                 { :host => h, :protocol => Setting.protocol }
               end
+              # Builds a tmail object used to email recipients of the added issue.
+              #
+              # Example:
+              #   issue_add(issue) => tmail object
+              #   Mailer.deliver_issue_add(issue) => sends an email to issue recipients
               def issue_add(issue)
                 redmine_headers 'Project' => issue.project.identifier,
                                 'Issue-Id' => issue.id,
                                 'Issue-Author' => issue.author.login
                 redmine_headers 'Issue-Assignee' => issue.assigned_to.login if issue.assigned_to
                 message_id issue
                 recipients issue.recipients
                 cc(issue.watcher_recipients - @recipients)
                 subject "[#{issue.project.name} - #{issue.tracker.name} ##{issue.id}] (#{issue.status.name}) #{issue.subject}"
                 body :issue => issue,
                      :issue_url => url_for(:controller => 'issues', :action => 'show', :id => issue)
               end
+              # Builds a tmail object used to email recipients of the edited issue.
+              #
+              # Example:
+              #   issue_edit(journal) => tmail object
+              #   Mailer.deliver_issue_edit(journal) => sends an email to issue recipients
               def issue_edit(journal)
                 issue = journal.journalized
                 redmine_headers 'Project' => issue.project.identifier,
                                 'Issue-Id' => issue.id,
                                 'Issue-Author' => issue.author.login
                 redmine_headers 'Issue-Assignee' => issue.assigned_to.login if issue.assigned_to
                 message_id journal
                 references issue
                 @author = journal.user
                 recipients issue.recipients
                 # Watchers in cc
                 cc(issue.watcher_recipients - @recipients)
                 s = "[#{issue.project.name} - #{issue.tracker.name} ##{issue.id}] "
                 s << "(#{issue.status.name}) " if journal.new_value_for('status_id')
                 s << issue.subject
                 subject s
                 body :issue => issue,
                      :journal => journal,
                      :issue_url => url_for(:controller => 'issues', :action => 'show', :id => issue)
               end
               def reminder(user, issues, days)
                 set_language_if_valid user.language
                 recipients user.mail
                 subject l(:mail_subject_reminder, issues.size)
                 body :issues => issues,
                      :days => days,
                      :issues_url => url_for(:controller => 'issues', :action => 'index', :set_filter => 1, :assigned_to_id => user.id, :sort_key => 'due_date', :sort_order => 'asc')
               end
+              # Builds a tmail object used to email users belonging to the added document's project.
+              #
+              # Example:
+              #   document_added(document) => tmail object
+              #   Mailer.deliver_document_added(document) => sends an email to the document's project recipients
               def document_added(document)
                 redmine_headers 'Project' => document.project.identifier
                 recipients document.project.recipients
                 subject "[#{document.project.name}] #{l(:label_document_new)}: #{document.title}"
                 body :document => document,
                      :document_url => url_for(:controller => 'documents', :action => 'show', :id => document)
               end
+              # Builds a tmail object used to email recipients of a project when an attachements are added.
+              #
+              # Example:
+              #   attachments_added(attachments) => tmail object
+              #   Mailer.deliver_attachments_added(attachments) => sends an email to the project's recipients
               def attachments_added(attachments)
                 container = attachments.first.container
                 added_to = ''
                 added_to_url = ''
                 case container.class.name
                 when 'Project'
                   added_to_url = url_for(:controller => 'projects', :action => 'list_files', :id => container)
                   added_to = "#{l(:label_project)}: #{container}"
                 when 'Version'
                   added_to_url = url_for(:controller => 'projects', :action => 'list_files', :id => container.project_id)
                   added_to = "#{l(:label_version)}: #{container.name}"
                 when 'Document'
                   added_to_url = url_for(:controller => 'documents', :action => 'show', :id => container.id)
                   added_to = "#{l(:label_document)}: #{container.title}"
                 end
                 redmine_headers 'Project' => container.project.identifier
                 recipients container.project.recipients
                 subject "[#{container.project.name}] #{l(:label_attachment_new)}"
                 body :attachments => attachments,
                      :added_to => added_to,
                      :added_to_url => added_to_url
               end
+              # Builds a tmail object used to email recipients of a news' project when a news item is added.
+              #
+              # Example:
+              #   news_added(news) => tmail object
+              #   Mailer.deliver_news_added(news) => sends an email to the news' project recipients
               def news_added(news)
                 redmine_headers 'Project' => news.project.identifier
                 message_id news
                 recipients news.project.recipients
                 subject "[#{news.project.name}] #{l(:label_news)}: #{news.title}"
                 body :news => news,
                      :news_url => url_for(:controller => 'news', :action => 'show', :id => news)
               end
+              # Builds a tmail object used to email the specified recipients of the specified message that was posted.
+              #
+              # Example:
+              #   message_posted(message, recipients) => tmail object
+              #   Mailer.deliver_message_posted(message, recipients) => sends an email to the recipients
               def message_posted(message, recipients)
                 redmine_headers 'Project' => message.project.identifier,
                                 'Topic-Id' => (message.parent_id || message.id)
                 message_id message
                 references message.parent unless message.parent.nil?
                 recipients(recipients)
                 subject "[#{message.board.project.name} - #{message.board.name} - msg#{message.root.id}] #{message.subject}"
                 body :message => message,
                      :message_url => url_for(:controller => 'messages', :action => 'show', :board_id => message.board_id, :id => message.root)
               end
+              # Builds a tmail object used to email the specified user their account information.
+              #
+              # Example:
+              #   account_information(user, password) => tmail object
+              #   Mailer.deliver_account_information(user, password) => sends account information to the user
               def account_information(user, password)
                 set_language_if_valid user.language
                 recipients user.mail
                 subject l(:mail_subject_register, Setting.app_title)
                 body :user => user,
                      :password => password,
                      :login_url => url_for(:controller => 'account', :action => 'login')
               end
+              # Builds a tmail object used to email all active administrators of an account activation request.
+              #
+              # Example:
+              #   account_activation_request(user) => tmail object
+              #   Mailer.deliver_account_activation_request(user)=> sends an email to all active administrators
               def account_activation_request(user)
                 # Send the email to all active administrators
                 recipients User.active.find(:all, :conditions => {:admin => true}).collect { |u| u.mail }.compact
                 subject l(:mail_subject_account_activation_request, Setting.app_title)
                 body :user => user,
                      :url => url_for(:controller => 'users', :action => 'index', :status => User::STATUS_REGISTERED, :sort_key => 'created_on', :sort_order => 'desc')
               end
-              # A registered user's account was activated by an administrator
+              # Builds a tmail object used to email the specified user that their account was activated by an administrator.
+              #
+              # Example:
+              #   account_activated(user) => tmail object
+              #   Mailer.deliver_account_activated(user) => sends an email to the registered user
               def account_activated(user)
                 set_language_if_valid user.language
                 recipients user.mail
                 subject l(:mail_subject_register, Setting.app_title)
                 body :user => user,
                      :login_url => url_for(:controller => 'account', :action => 'login')
               end
               def lost_password(token)
                 set_language_if_valid(token.user.language)
                 recipients token.user.mail
                 subject l(:mail_subject_lost_password, Setting.app_title)
                 body :token => token,
                      :url => url_for(:controller => 'account', :action => 'lost_password', :token => token.value)
               end
               def register(token)
                 set_language_if_valid(token.user.language)
                 recipients token.user.mail
                 subject l(:mail_subject_register, Setting.app_title)
                 body :token => token,
                      :url => url_for(:controller => 'account', :action => 'activate', :token => token.value)
               end
               def test(user)
                 set_language_if_valid(user.language)
                 recipients user.mail
                 subject 'Redmine test'
                 body :url => url_for(:controller => 'welcome')
               end
               # Overrides default deliver! method to prevent from sending an email
               # with no recipient, cc or bcc
               def deliver!(mail = @mail)
                 return false if (recipients.nil? || recipients.empty?) &&
                                 (cc.nil? || cc.empty?) &&
                                 (bcc.nil? || bcc.empty?)
                 # Set Message-Id and References
                 if @message_id_object
                   mail.message_id = self.class.message_id_for(@message_id_object)
                 end
                 if @references_objects
                   mail.references = @references_objects.collect {|o| self.class.message_id_for(o)}
                 end
                 super(mail)
               end
               # Sends reminders to issue assignees
               # Available options:
               # * :days     => how many days in the future to remind about (defaults to 7)
               # * :tracker  => id of tracker for filtering issues (defaults to all trackers)
               # * :project  => id or identifier of project to process (defaults to all projects)
               def self.reminders(options={})
                 days = options[:days] || 7
                 project = options[:project] ? Project.find(options[:project]) : nil
                 tracker = options[:tracker] ? Tracker.find(options[:tracker]) : nil
                 s = ARCondition.new ["#{IssueStatus.table_name}.is_closed = ? AND #{Issue.table_name}.due_date <= ?", false, days.day.from_now.to_date]
                 s << "#{Issue.table_name}.assigned_to_id IS NOT NULL"
                 s << "#{Project.table_name}.status = #{Project::STATUS_ACTIVE}"
                 s << "#{Issue.table_name}.project_id = #{project.id}" if project
                 s << "#{Issue.table_name}.tracker_id = #{tracker.id}" if tracker
                 issues_by_assignee = Issue.find(:all, :include => [:status, :assigned_to, :project, :tracker],
                                                       :conditions => s.conditions
                                                 ).group_by(&:assigned_to)
                 issues_by_assignee.each do |assignee, issues|
                   deliver_reminder(assignee, issues, days) unless assignee.nil?
                 end
               end
               private
               def initialize_defaults(method_name)
                 super
                 set_language_if_valid Setting.default_language
                 from Setting.mail_from
                 # Common headers
                 headers 'X-Mailer' => 'Redmine',
                         'X-Redmine-Host' => Setting.host_name,
                         'X-Redmine-Site' => Setting.app_title,
                         'List-Id' => "<#{Setting.mail_from.to_s.gsub('@', '.')}>"
               end
               # Appends a Redmine header field (name is prepended with 'X-Redmine-')
               def redmine_headers(h)
                 h.each { |k,v| headers["X-Redmine-#{k}"] = v }
               end
               # Overrides the create_mail method
               def create_mail
                 # Removes the current user from the recipients and cc
                 # if he doesn't want to receive notifications about what he does
                 @author ||= User.current
                 if @author.pref[:no_self_notified]
                   recipients.delete(@author.mail) if recipients
                   cc.delete(@author.mail) if cc
                 end
                 # Blind carbon copy recipients
                 if Setting.bcc_recipients?
                   bcc([recipients, cc].flatten.compact.uniq)
                   recipients []
                   cc []
                 end
                 super
               end
               # Renders a message with the corresponding layout
               def render_message(method_name, body)
                 layout = method_name.to_s.match(%r{text\.html\.(rhtml|rxml)}) ? 'layout.text.html.rhtml' : 'layout.text.plain.rhtml'
                 body[:content_for_layout] = render(:file => method_name, :body => body)
                 ActionView::Base.new(template_root, body, self).render(:file => "mailer/#{layout}", :use_full_path => true)
               end
               # for the case of plain text only
               def body(*params)
                 value = super(*params)
                 if Setting.plain_text_mail?
                   templates = Dir.glob("#{template_path}/#{@template}.text.plain.{rhtml,erb}")
                   unless String === @body or templates.empty?
                     template = File.basename(templates.first)
                     @body[:content_for_layout] = render(:file => template, :body => @body)
                     @body = ActionView::Base.new(template_root, @body, self).render(:file => "mailer/layout.text.plain.rhtml", :use_full_path => true)
                     return @body
                   end
                 end
                 return value
               end
               # Makes partial rendering work with Rails 1.2 (retro-compatibility)
               def self.controller_path
                 ''
               end unless respond_to?('controller_path')
               # Returns a predictable Message-Id for the given object
               def self.message_id_for(object)
                 # id + timestamp should reduce the odds of a collision
                 # as far as we don't send multiple emails for the same object
                 hash = "redmine.#{object.class.name.demodulize.underscore}-#{object.id}.#{object.created_on.strftime("%Y%m%d%H%M%S")}"
                 host = Setting.mail_from.to_s.gsub(%r{^.*@}, '')
                 host = "#{::Socket.gethostname}.redmine" if host.empty?
                 "<#{hash}@#{host}>"
               end
               private
               def message_id(object)
                 @message_id_object = object
               end
               def references(object)
                 @references_objects ||= []
                 @references_objects << object
               end
             end
             # Patch TMail so that message_id is not overwritten
             module TMail
               class Mail
                 def add_message_id( fqdn = nil )
                   self.message_id ||= ::TMail::new_message_id(fqdn)
                 end
               end
             end

app/models/project.rb +15 -1

             # redMine - project management software
             # Copyright (C) 2006  Jean-Philippe Lang
             #
             # This program is free software; you can redistribute it and/or
             # modify it under the terms of the GNU General Public License
             # as published by the Free Software Foundation; either version 2
             # of the License, or (at your option) any later version.
             #
             # This program is distributed in the hope that it will be useful,
             # but WITHOUT ANY WARRANTY; without even the implied warranty of
             # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
             # GNU General Public License for more details.
             #
             # You should have received a copy of the GNU General Public License
             # along with this program; if not, write to the Free Software
             # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
             class Project < ActiveRecord::Base
               # Project statuses
               STATUS_ACTIVE     = 1
               STATUS_ARCHIVED   = 9
               has_many :members, :include => :user, :conditions => "#{User.table_name}.status=#{User::STATUS_ACTIVE}"
               has_many :users, :through => :members
               has_many :enabled_modules, :dependent => :delete_all
               has_and_belongs_to_many :trackers, :order => "#{Tracker.table_name}.position"
               has_many :issues, :dependent => :destroy, :order => "#{Issue.table_name}.created_on DESC", :include => [:status, :tracker]
               has_many :issue_changes, :through => :issues, :source => :journals
               has_many :versions, :dependent => :destroy, :order => "#{Version.table_name}.effective_date DESC, #{Version.table_name}.name DESC"
               has_many :time_entries, :dependent => :delete_all
               has_many :queries, :dependent => :delete_all
               has_many :documents, :dependent => :destroy
               has_many :news, :dependent => :delete_all, :include => :author
               has_many :issue_categories, :dependent => :delete_all, :order => "#{IssueCategory.table_name}.name"
               has_many :boards, :dependent => :destroy, :order => "position ASC"
               has_one :repository, :dependent => :destroy
               has_many :changesets, :through => :repository
               has_one :wiki, :dependent => :destroy
               # Custom field for the project issues
               has_and_belongs_to_many :issue_custom_fields,
                                       :class_name => 'IssueCustomField',
                                       :order => "#{CustomField.table_name}.position",
                                       :join_table => "#{table_name_prefix}custom_fields_projects#{table_name_suffix}",
                                       :association_foreign_key => 'custom_field_id'
               acts_as_nested_set :order => 'name', :dependent => :destroy
               acts_as_attachable :view_permission => :view_files,
                                  :delete_permission => :manage_files
               acts_as_customizable
               acts_as_searchable :columns => ['name', 'description'], :project_key => 'id', :permission => nil
               acts_as_event :title => Proc.new {|o| "#{l(:label_project)}: #{o.name}"},
                             :url => Proc.new {|o| {:controller => 'projects', :action => 'show', :id => o.id}},
                             :author => nil
               attr_protected :status, :enabled_module_names
               validates_presence_of :name, :identifier
               validates_uniqueness_of :name, :identifier
               validates_associated :repository, :wiki
               validates_length_of :name, :maximum => 30
               validates_length_of :homepage, :maximum => 255
               validates_length_of :identifier, :in => 2..20
               validates_format_of :identifier, :with => /^[a-z0-9\-]*$/
               before_destroy :delete_all_members
               named_scope :has_module, lambda { |mod| { :conditions => ["#{Project.table_name}.id IN (SELECT em.project_id FROM #{EnabledModule.table_name} em WHERE em.name=?)", mod.to_s] } }
               named_scope :active, { :conditions => "#{Project.table_name}.status = #{STATUS_ACTIVE}"}
               named_scope :public, { :conditions => { :is_public => true } }
               named_scope :visible, lambda { { :conditions => Project.visible_by(User.current) } }
               def identifier=(identifier)
                 super unless identifier_frozen?
               end
               def identifier_frozen?
                 errors[:identifier].nil? && !(new_record? || identifier.blank?)
               end
               def issues_with_subprojects(include_subprojects=false)
                 conditions = nil
                 if include_subprojects
                   ids = [id] + descendants.collect(&:id)
                   conditions = ["#{Project.table_name}.id IN (#{ids.join(',')}) AND #{Project.visible_by}"]
                 end
                 conditions ||= ["#{Project.table_name}.id = ?", id]
                 # Quick and dirty fix for Rails 2 compatibility
                 Issue.send(:with_scope, :find => { :conditions => conditions }) do
                   Version.send(:with_scope, :find => { :conditions => conditions }) do
                     yield
                   end
                 end
               end
               # returns latest created projects
               # non public projects will be returned only if user is a member of those
               def self.latest(user=nil, count=5)
                 find(:all, :limit => count, :conditions => visible_by(user), :order => "created_on DESC")
               end
+              # Returns a SQL :conditions string used to find all active projects for the specified user.
+              #
+              # Examples:
+              #     Projects.visible_by(admin)        => "projects.status = 1"
+              #     Projects.visible_by(normal_user)  => "projects.status = 1 AND projects.is_public = 1"
               def self.visible_by(user=nil)
                 user ||= User.current
                 if user && user.admin?
                   return "#{Project.table_name}.status=#{Project::STATUS_ACTIVE}"
                 elsif user && user.memberships.any?
                   return "#{Project.table_name}.status=#{Project::STATUS_ACTIVE} AND (#{Project.table_name}.is_public = #{connection.quoted_true} or #{Project.table_name}.id IN (#{user.memberships.collect{|m| m.project_id}.join(',')}))"
                 else
                   return "#{Project.table_name}.status=#{Project::STATUS_ACTIVE} AND #{Project.table_name}.is_public = #{connection.quoted_true}"
                 end
               end
               def self.allowed_to_condition(user, permission, options={})
                 statements = []
                 base_statement = "#{Project.table_name}.status=#{Project::STATUS_ACTIVE}"
                 if perm = Redmine::AccessControl.permission(permission)
                   unless perm.project_module.nil?
                     # If the permission belongs to a project module, make sure the module is enabled
                     base_statement << " AND EXISTS (SELECT em.id FROM #{EnabledModule.table_name} em WHERE em.name='#{perm.project_module}' AND em.project_id=#{Project.table_name}.id)"
                   end
                 end
                 if options[:project]
                   project_statement = "#{Project.table_name}.id = #{options[:project].id}"
                   project_statement << " OR (#{Project.table_name}.lft > #{options[:project].lft} AND #{Project.table_name}.rgt < #{options[:project].rgt})" if options[:with_subprojects]
                   base_statement = "(#{project_statement}) AND (#{base_statement})"
                 end
                 if user.admin?
                   # no restriction
                 else
                   statements << "1=0"
                   if user.logged?
                     statements << "#{Project.table_name}.is_public = #{connection.quoted_true}" if Role.non_member.allowed_to?(permission)
                     allowed_project_ids = user.memberships.select {|m| m.role.allowed_to?(permission)}.collect {|m| m.project_id}
                     statements << "#{Project.table_name}.id IN (#{allowed_project_ids.join(',')})" if allowed_project_ids.any?
                   elsif Role.anonymous.allowed_to?(permission)
                     # anonymous user allowed on public project
                     statements << "#{Project.table_name}.is_public = #{connection.quoted_true}"
                   else
                     # anonymous user is not authorized
                   end
                 end
                 statements.empty? ? base_statement : "((#{base_statement}) AND (#{statements.join(' OR ')}))"
               end
+              # Returns a :conditions SQL string that can be used to find the issues associated with this project.
+              #
+              # Examples:
+              #   project.project_condition(true)  => "(projects.id = 1 OR (projects.lft > 1 AND projects.rgt < 10))"
+              #   project.project_condition(false) => "projects.id = 1"
               def project_condition(with_subprojects)
                 cond = "#{Project.table_name}.id = #{id}"
                 cond = "(#{cond} OR (#{Project.table_name}.lft > #{lft} AND #{Project.table_name}.rgt < #{rgt}))" if with_subprojects
                 cond
               end
               def self.find(*args)
                 if args.first && args.first.is_a?(String) && !args.first.match(/^\d*$/)
                   project = find_by_identifier(*args)
                   raise ActiveRecord::RecordNotFound, "Couldn't find Project with identifier=#{args.first}" if project.nil?
                   project
                 else
                   super
                 end
               end
               def to_param
                 # id is used for projects with a numeric identifier (compatibility)
                 @to_param ||= (identifier.to_s =~ %r{^\d*$} ? id : identifier)
               end
               def active?
                 self.status == STATUS_ACTIVE
               end
               # Archives the project and its descendants recursively
               def archive
                 # Archive subprojects if any
                 children.each do |subproject|
                   subproject.archive
                 end
                 update_attribute :status, STATUS_ARCHIVED
               end
               # Unarchives the project
               # All its ancestors must be active
               def unarchive
                 return false if ancestors.detect {|a| !a.active?}
                 update_attribute :status, STATUS_ACTIVE
               end
               # Returns an array of projects the project can be moved to
               def possible_parents
                 @possible_parents ||= (Project.active.find(:all) - self_and_descendants)
               end
               # Sets the parent of the project
               # Argument can be either a Project, a String, a Fixnum or nil
               def set_parent!(p)
                 unless p.nil? || p.is_a?(Project)
                   if p.to_s.blank?
                     p = nil
                   else
                     p = Project.find_by_id(p)
                     return false unless p
                   end
                 end
                 if p == parent && !p.nil?
                   # Nothing to do
                   true
                 elsif p.nil? || (p.active? && move_possible?(p))
                   # Insert the project so that target's children or root projects stay alphabetically sorted
                   sibs = (p.nil? ? self.class.roots : p.children)
                   to_be_inserted_before = sibs.detect {|c| c.name.to_s.downcase > name.to_s.downcase }
                   if to_be_inserted_before
                     move_to_left_of(to_be_inserted_before)
                   elsif p.nil?
                     if sibs.empty?
                       # move_to_root adds the project in first (ie. left) position
                       move_to_root
                     else
                       move_to_right_of(sibs.last) unless self == sibs.last
                     end
                   else
                     # move_to_child_of adds the project in last (ie.right) position
                     move_to_child_of(p)
                   end
                   true
                 else
                   # Can not move to the given target
                   false
                 end
               end
               # Returns an array of the trackers used by the project and its active sub projects
               def rolled_up_trackers
                 @rolled_up_trackers ||=
                   Tracker.find(:all, :include => :projects,
                                      :select => "DISTINCT #{Tracker.table_name}.*",
                                      :conditions => ["#{Project.table_name}.lft >= ? AND #{Project.table_name}.rgt <= ? AND #{Project.table_name}.status = #{STATUS_ACTIVE}", lft, rgt],
                                      :order => "#{Tracker.table_name}.position")
               end
               # Deletes all project's members
               def delete_all_members
                 Member.delete_all(['project_id = ?', id])
               end
               # Users issues can be assigned to
               def assignable_users
                 members.select {|m| m.role.assignable?}.collect {|m| m.user}.sort
               end
               # Returns the mail adresses of users that should be always notified on project events
               def recipients
                 members.select {|m| m.mail_notification? || m.user.mail_notification?}.collect {|m| m.user.mail}
               end
               # Returns an array of all custom fields enabled for project issues
               # (explictly associated custom fields and custom fields enabled for all projects)
               def all_issue_custom_fields
                 @all_issue_custom_fields ||= (IssueCustomField.for_all + issue_custom_fields).uniq.sort
               end
               def project
                 self
               end
               def <=>(project)
                 name.downcase <=> project.name.downcase
               end
               def to_s
                 name
               end
               # Returns a short description of the projects (first lines)
               def short_description(length = 255)
                 description.gsub(/^(.{#{length}}[^\n\r]*).*$/m, '\1...').strip if description
               end
+              # Return true if this project is allowed to do the specified action.
+              # action can be:
+              # * a parameter-like Hash (eg. :controller => 'projects', :action => 'edit')
+              # * a permission Symbol (eg. :edit_project)
               def allows_to?(action)
                 if action.is_a? Hash
                   allowed_actions.include? "#{action[:controller]}/#{action[:action]}"
                 else
                   allowed_permissions.include? action
                 end
               end
               def module_enabled?(module_name)
                 module_name = module_name.to_s
                 enabled_modules.detect {|m| m.name == module_name}
               end
               def enabled_module_names=(module_names)
                 if module_names && module_names.is_a?(Array)
                   module_names = module_names.collect(&:to_s)
                   # remove disabled modules
                   enabled_modules.each {|mod| mod.destroy unless module_names.include?(mod.name)}
                   # add new modules
                   module_names.each {|name| enabled_modules << EnabledModule.new(:name => name)}
                 else
                   enabled_modules.clear
                 end
               end
               # Returns an auto-generated project identifier based on the last identifier used
               def self.next_identifier
                 p = Project.find(:first, :order => 'created_on DESC')
                 p.nil? ? nil : p.identifier.to_s.succ
               end
             protected
               def validate
                 errors.add(:identifier, :invalid) if !identifier.blank? && identifier.match(/^\d*$/)
               end
             private
               def allowed_permissions
                 @allowed_permissions ||= begin
                   module_names = enabled_modules.collect {|m| m.name}
                   Redmine::AccessControl.modules_permissions(module_names).collect {|p| p.name}
                 end
               end
               def allowed_actions
                 @actions_allowed ||= allowed_permissions.inject([]) { |actions, permission| actions += Redmine::AccessControl.allowed_actions(permission) }.flatten
               end
             end

app/models/user.rb +2 0

             # redMine - project management software
             # Copyright (C) 2006-2007  Jean-Philippe Lang
             #
             # This program is free software; you can redistribute it and/or
             # modify it under the terms of the GNU General Public License
             # as published by the Free Software Foundation; either version 2
             # of the License, or (at your option) any later version.
             #
             # This program is distributed in the hope that it will be useful,
             # but WITHOUT ANY WARRANTY; without even the implied warranty of
             # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
             # GNU General Public License for more details.
             #
             # You should have received a copy of the GNU General Public License
             # along with this program; if not, write to the Free Software
             # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
             require "digest/sha1"
             class User < ActiveRecord::Base
               # Account statuses
               STATUS_ANONYMOUS  = 0
               STATUS_ACTIVE     = 1
               STATUS_REGISTERED = 2
               STATUS_LOCKED     = 3
               USER_FORMATS = {
                 :firstname_lastname => '#{firstname} #{lastname}',
                 :firstname => '#{firstname}',
                 :lastname_firstname => '#{lastname} #{firstname}',
                 :lastname_coma_firstname => '#{lastname}, #{firstname}',
                 :username => '#{login}'
               }
               has_many :memberships, :class_name => 'Member', :include => [ :project, :role ], :conditions => "#{Project.table_name}.status=#{Project::STATUS_ACTIVE}", :order => "#{Project.table_name}.name"
               has_many :members, :dependent => :delete_all
               has_many :projects, :through => :memberships
               has_many :issue_categories, :foreign_key => 'assigned_to_id', :dependent => :nullify
               has_many :changesets, :dependent => :nullify
               has_one :preference, :dependent => :destroy, :class_name => 'UserPreference'
               has_one :rss_token, :dependent => :destroy, :class_name => 'Token', :conditions => "action='feeds'"
               belongs_to :auth_source
               # Active non-anonymous users scope
               named_scope :active, :conditions => "#{User.table_name}.status = #{STATUS_ACTIVE}"
               acts_as_customizable
               attr_accessor :password, :password_confirmation
               attr_accessor :last_before_login_on
               # Prevents unauthorized assignments
               attr_protected :login, :admin, :password, :password_confirmation, :hashed_password
               validates_presence_of :login, :firstname, :lastname, :mail, :if => Proc.new { |user| !user.is_a?(AnonymousUser) }
               validates_uniqueness_of :login, :if => Proc.new { |user| !user.login.blank? }
               validates_uniqueness_of :mail, :if => Proc.new { |user| !user.mail.blank? }, :case_sensitive => false
               # Login must contain lettres, numbers, underscores only
               validates_format_of :login, :with => /^[a-z0-9_\-@\.]*$/i
               validates_length_of :login, :maximum => 30
               validates_format_of :firstname, :lastname, :with => /^[\w\s\'\-\.]*$/i
               validates_length_of :firstname, :lastname, :maximum => 30
               validates_format_of :mail, :with => /^([^@\s]+)@((?:[-a-z0-9]+\.)+[a-z]{2,})$/i, :allow_nil => true
               validates_length_of :mail, :maximum => 60, :allow_nil => true
               validates_length_of :password, :minimum => 4, :allow_nil => true
               validates_confirmation_of :password, :allow_nil => true
               def before_create
                 self.mail_notification = false
                 true
               end
               def before_save
                 # update hashed_password if password was set
                 self.hashed_password = User.hash_password(self.password) if self.password
               end
               def reload(*args)
                 @name = nil
                 super
               end
               def identity_url=(url)
                 if url.blank?
                   write_attribute(:identity_url, '')
                 else
                   begin
                     write_attribute(:identity_url, OpenIdAuthentication.normalize_identifier(url))
                   rescue OpenIdAuthentication::InvalidOpenId
                     # Invlaid url, don't save
                   end
                 end
                 self.read_attribute(:identity_url)
               end
               # Returns the user that matches provided login and password, or nil
               def self.try_to_login(login, password)
                 # Make sure no one can sign in with an empty password
                 return nil if password.to_s.empty?
                 user = find(:first, :conditions => ["login=?", login])
                 if user
                   # user is already in local database
                   return nil if !user.active?
                   if user.auth_source
                     # user has an external authentication method
                     return nil unless user.auth_source.authenticate(login, password)
                   else
                     # authentication with local password
                     return nil unless User.hash_password(password) == user.hashed_password
                   end
                 else
                   # user is not yet registered, try to authenticate with available sources
                   attrs = AuthSource.authenticate(login, password)
                   if attrs
                     user = new(*attrs)
                     user.login = login
                     user.language = Setting.default_language
                     if user.save
                       user.reload
                       logger.info("User '#{user.login}' created from the LDAP") if logger
                     end
                   end
                 end
                 user.update_attribute(:last_login_on, Time.now) if user && !user.new_record?
                 user
               rescue => text
                 raise text
               end
               # Returns the user who matches the given autologin +key+ or nil
               def self.try_to_autologin(key)
                 token = Token.find_by_action_and_value('autologin', key)
                 if token && (token.created_on > Setting.autologin.to_i.day.ago) && token.user && token.user.active?
                   token.user.update_attribute(:last_login_on, Time.now)
                   token.user
                 end
               end
               # Return user's full name for display
               def name(formatter = nil)
                 if formatter
                   eval('"' + (USER_FORMATS[formatter] || USER_FORMATS[:firstname_lastname]) + '"')
                 else
                   @name ||= eval('"' + (USER_FORMATS[Setting.user_format] || USER_FORMATS[:firstname_lastname]) + '"')
                 end
               end
               def active?
                 self.status == STATUS_ACTIVE
               end
               def registered?
                 self.status == STATUS_REGISTERED
               end
               def locked?
                 self.status == STATUS_LOCKED
               end
               def check_password?(clear_password)
                 User.hash_password(clear_password) == self.hashed_password
               end
               # Generate and set a random password.  Useful for automated user creation
               # Based on Token#generate_token_value
               #
               def random_password
                 chars = ("a".."z").to_a + ("A".."Z").to_a + ("0".."9").to_a
                 password = ''
 .times { |i| password << chars[rand(chars.size-1)] }
                 self.password = password
                 self.password_confirmation = password
                 self
               end
               def pref
                 self.preference ||= UserPreference.new(:user => self)
               end
               def time_zone
                 @time_zone ||= (self.pref.time_zone.blank? ? nil : ActiveSupport::TimeZone[self.pref.time_zone])
               end
               def wants_comments_in_reverse_order?
                 self.pref[:comments_sorting] == 'desc'
               end
               # Return user's RSS key (a 40 chars long string), used to access feeds
               def rss_key
                 token = self.rss_token || Token.create(:user => self, :action => 'feeds')
                 token.value
               end
               # Return an array of project ids for which the user has explicitly turned mail notifications on
               def notified_projects_ids
                 @notified_projects_ids ||= memberships.select {|m| m.mail_notification?}.collect(&:project_id)
               end
               def notified_project_ids=(ids)
                 Member.update_all("mail_notification = #{connection.quoted_false}", ['user_id = ?', id])
                 Member.update_all("mail_notification = #{connection.quoted_true}", ['user_id = ? AND project_id IN (?)', id, ids]) if ids && !ids.empty?
                 @notified_projects_ids = nil
                 notified_projects_ids
               end
               def self.find_by_rss_key(key)
                 token = Token.find_by_value(key)
                 token && token.user.active? ? token.user : nil
               end
               # Makes find_by_mail case-insensitive
               def self.find_by_mail(mail)
                 find(:first, :conditions => ["LOWER(mail) = ?", mail.to_s.downcase])
               end
               # Sort users by their display names
               def <=>(user)
                 self.to_s.downcase <=> user.to_s.downcase
               end
               def to_s
                 name
               end
               def logged?
                 true
               end
               def anonymous?
                 !logged?
               end
               # Return user's role for project
               def role_for_project(project)
                 # No role on archived projects
                 return nil unless project && project.active?
                 if logged?
                   # Find project membership
                   membership = memberships.detect {|m| m.project_id == project.id}
                   if membership
                     membership.role
                   else
                     @role_non_member ||= Role.non_member
                   end
                 else
                   @role_anonymous ||= Role.anonymous
                 end
               end
               # Return true if the user is a member of project
               def member_of?(project)
                 role_for_project(project).member?
               end
               # Return true if the user is allowed to do the specified action on project
               # action can be:
               # * a parameter-like Hash (eg. :controller => 'projects', :action => 'edit')
               # * a permission Symbol (eg. :edit_project)
               def allowed_to?(action, project, options={})
                 if project
                   # No action allowed on archived projects
                   return false unless project.active?
                   # No action allowed on disabled modules
                   return false unless project.allows_to?(action)
                   # Admin users are authorized for anything else
                   return true if admin?
                   role = role_for_project(project)
                   return false unless role
                   role.allowed_to?(action) && (project.is_public? || role.member?)
                 elsif options[:global]
                   # authorize if user has at least one role that has this permission
                   roles = memberships.collect {|m| m.role}.uniq
                   roles.detect {|r| r.allowed_to?(action)} || (self.logged? ? Role.non_member.allowed_to?(action) : Role.anonymous.allowed_to?(action))
                 else
                   false
                 end
               end
               def self.current=(user)
                 @current_user = user
               end
               def self.current
                 @current_user ||= User.anonymous
               end
+              # Returns the anonymous user.  If the anonymous user does not exist, it is created.  There can be only
+              # one anonymous user per database.
               def self.anonymous
                 anonymous_user = AnonymousUser.find(:first)
                 if anonymous_user.nil?
                   anonymous_user = AnonymousUser.create(:lastname => 'Anonymous', :firstname => '', :mail => '', :login => '', :status => 0)
                   raise 'Unable to create the anonymous user.' if anonymous_user.new_record?
                 end
                 anonymous_user
               end
             private
               # Return password digest
               def self.hash_password(clear_password)
                 Digest::SHA1.hexdigest(clear_password || "")
               end
             end
             class AnonymousUser < User
               def validate_on_create
                 # There should be only one AnonymousUser in the database
                 errors.add_to_base 'An anonymous user already exists.' if AnonymousUser.find(:first)
               end
               def available_custom_fields
                 []
               end
               # Overrides a few properties
               def logged?; false end
               def admin; false end
               def name; 'Anonymous' end
               def mail; nil end
               def time_zone; nil end
               def rss_key; nil end
             end

app/models/version.rb +12 -2

             # redMine - project management software
             # Copyright (C) 2006  Jean-Philippe Lang
             #
             # This program is free software; you can redistribute it and/or
             # modify it under the terms of the GNU General Public License
             # as published by the Free Software Foundation; either version 2
             # of the License, or (at your option) any later version.
             #
             # This program is distributed in the hope that it will be useful,
             # but WITHOUT ANY WARRANTY; without even the implied warranty of
             # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
             # GNU General Public License for more details.
             #
             # You should have received a copy of the GNU General Public License
             # along with this program; if not, write to the Free Software
             # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
             class Version < ActiveRecord::Base
               before_destroy :check_integrity
               belongs_to :project
               has_many :fixed_issues, :class_name => 'Issue', :foreign_key => 'fixed_version_id'
               acts_as_attachable :view_permission => :view_files,
                                  :delete_permission => :manage_files
               validates_presence_of :name
               validates_uniqueness_of :name, :scope => [:project_id]
               validates_length_of :name, :maximum => 60
               validates_format_of :effective_date, :with => /^\d{4}-\d{2}-\d{2}$/, :message => :not_a_date, :allow_nil => true
               def start_date
                 effective_date
               end
               def due_date
                 effective_date
               end
               # Returns the total estimated time for this version
               def estimated_hours
                 @estimated_hours ||= fixed_issues.sum(:estimated_hours).to_f
               end
               # Returns the total reported time for this version
               def spent_hours
                 @spent_hours ||= TimeEntry.sum(:hours, :include => :issue, :conditions => ["#{Issue.table_name}.fixed_version_id = ?", id]).to_f
               end
               # Returns true if the version is completed: due date reached and no open issues
               def completed?
                 effective_date && (effective_date <= Date.today) && (open_issues_count == 0)
               end
+              # Returns the completion percentage of this version based on the amount of open/closed issues
+              # and the time spent on the open issues.
               def completed_pourcent
                 if issues_count == 0
                 elsif open_issues_count == 0
                 else
                   issues_progress(false) + issues_progress(true)
                 end
               end
+              # Returns the percentage of issues that have been marked as 'closed'.
               def closed_pourcent
                 if issues_count == 0
                 else
                   issues_progress(false)
                 end
               end
               # Returns true if the version is overdue: due date reached and some open issues
               def overdue?
                 effective_date && (effective_date < Date.today) && (open_issues_count > 0)
               end
               # Returns assigned issues count
               def issues_count
                 @issue_count ||= fixed_issues.count
               end
+              # Returns the total amount of open issues for this version.
               def open_issues_count
                 @open_issues_count ||= Issue.count(:all, :conditions => ["fixed_version_id = ? AND is_closed = ?", self.id, false], :include => :status)
               end
+              # Returns the total amount of closed issues for this version.
               def closed_issues_count
                 @closed_issues_count ||= Issue.count(:all, :conditions => ["fixed_version_id = ? AND is_closed = ?", self.id, true], :include => :status)
               end
               def wiki_page
                 if project.wiki && !wiki_page_title.blank?
                   @wiki_page ||= project.wiki.find_page(wiki_page_title)
                 end
                 @wiki_page
               end
               def to_s; name end
               # Versions are sorted by effective_date and name
               # Those with no effective_date are at the end, sorted by name
               def <=>(version)
                 if self.effective_date
                   version.effective_date ? (self.effective_date == version.effective_date ? self.name <=> version.name : self.effective_date <=> version.effective_date) : -1
                 else
                   version.effective_date ? 1 : (self.name <=> version.name)
                 end
               end
             private
               def check_integrity
                 raise "Can't delete version" if self.fixed_issues.find(:first)
               end
               # Returns the average estimated time of assigned issues
               # or 1 if no issue has an estimated time
               # Used to weigth unestimated issues in progress calculation
               def estimated_average
                 if @estimated_average.nil?
                   average = fixed_issues.average(:estimated_hours).to_f
                   if average == 0
                     average = 1
                   end
                   @estimated_average = average
                 end
                 @estimated_average
               end
-              # Returns the total progress of open or closed issues
+              # Returns the total progress of open or closed issues.  The returned percentage takes into account
+              # the amount of estimated time set for this version.
+              #
+              # Examples:
+              # issues_progress(true)   => returns the progress percentage for open issues.
+              # issues_progress(false)  => returns the progress percentage for closed issues.
               def issues_progress(open)
                 @issues_progress ||= {}
                 @issues_progress[open] ||= begin
                   progress = 0
                   if issues_count > 0
                     ratio = open ? 'done_ratio' : 100
                     done = fixed_issues.sum("COALESCE(estimated_hours, #{estimated_average}) * #{ratio}",
                                               :include => :status,
                                               :conditions => ["is_closed = ?", !open]).to_f
                     progress = done / (estimated_average * issues_count)
                   end
                   progress
                 end
               end
             end

General Comments 0

Write
Preview

You need to be logged in to leave comments. Login now

No TODOs yet

	Site-wide shortcuts
/	Use quick search box
g h	Goto home page
g g	Goto my private gists page
g G	Goto my public gists page
g 0-9	Goto bookmarked items from 0-9
n r	New repository page
n g	New gist page

	Repositories
g s	Goto summary page
g c	Goto changelog page
g f	Goto files page
g F	Goto files page with file search activated
g p	Goto pull requests page
g o	Goto repository settings
g O	Goto repository access permissions settings
t s	Toggle sidebar on some pages