taskjuggler 0.0.2

data/lib/taskjuggler3.rb

@@ -0,0 +1,106 @@
+#!/usr/bin/env ruby -w
+# encoding: UTF-8
+#
+# = taskjuggler3.rb -- The TaskJuggler III Project Management Software
+#
+# Copyright (c) 2006, 2007, 2008, 2009 by Chris Schlaeger <cs@kde.org>
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of version 2 of the GNU General Public License as
+# published by the Free Software Foundation.
+#
+
+require 'optparse'
+require 'Tj3Config'
+require 'TaskJuggler'
+
+# Name of the application suite
+AppConfig.appName = 'taskjuggler3'
+
+def processArguments(argv)
+  opts = OptionParser.new
+
+  opts.banner = "#{AppConfig.packageName} v#{AppConfig.version} - " +
+                "#{AppConfig.packageInfo}\n\n" +
+                "Copyright (c) #{AppConfig.copyright.join(', ')}" +
+                " by #{AppConfig.authors.join(', ')}\n\n" +
+                "#{AppConfig.license}\n" +
+                "For more info about #{AppConfig.packageName} see " +
+                "#{AppConfig.contact}\n\n" +
+                "Usage: #{AppConfig.appName} [options] file.tjp " +
+                "[ file1.tji ... ]"
+  opts.separator ""
+  opts.on('--debuglevel N', Integer, "Verbosity of debug output") do |arg|
+    TaskJuggler::Log.level = arg
+  end
+  opts.on('--debugmodules x,y,z', Array,
+          'Restrict debug output to a list of modules') do |arg|
+    TaskJuggler::Log.segments = arg.split(',')
+  end
+  opts.on('--silent', "Don't show program and progress information") do
+    TaskJuggler::Log.silent = true
+  end
+  opts.on('-f', '--force-reports',
+          'Generate reports despite scheduling errors') do
+    @forceReports = true
+  end
+  opts.on('-c N', Integer, 'Maximum number of CPU cores to use') do |arg|
+    @maxCpuCores = arg
+  end
+  opts.on_tail('-h', '--help', 'Show this message') do
+    puts opts.to_s
+    exit 0
+  end
+
+  opts.on_tail('--version', 'Show version info') do
+    puts "#{AppConfig.packageName} v#{AppConfig.version} - " +
+      "#{AppConfig.packageInfo}"
+    exit 0
+  end
+
+  # Show some progress information by default
+  TaskJuggler::Log.silent = false
+  begin
+    files = opts.parse(argv)
+  rescue OptionParser::ParseError => msg
+    puts opts.to_s + "\n"
+    $stderr.puts msg
+    exit 0
+  end
+
+  if files.empty?
+    puts opts.to_s
+    $stderr.puts "\nNo file name specified!"
+    exit 1
+  end
+
+  unless TaskJuggler::Log.silent
+    puts "#{AppConfig.packageName} v#{AppConfig.version} - " +
+      "#{AppConfig.packageInfo}\n\n" +
+      "Copyright (c) #{AppConfig.copyright.join(', ')}" +
+      " by #{AppConfig.authors.join(', ')}\n\n" +
+      "#{AppConfig.license}\n"
+  end
+
+  files
+end
+
+def main
+  @maxCpuCores = 1
+  @forceReports = false
+
+  errors = false
+  tj = TaskJuggler.new(files = processArguments(ARGV))
+  tj.maxCpuCores = @maxCpuCores
+  exit 1 unless tj.parse(files)
+  if !tj.schedule
+    errors = true
+    exit 1 unless @forceReports
+  end
+  exit 1 if !tj.generateReports || errors
+
+end
+
+main()
+exit 0
+

data/lib/tj3man.rb

@@ -0,0 +1,88 @@
+#!/usr/bin/env ruby -w
+# encoding: UTF-8
+#
+# = tj3man.rb -- The TaskJuggler III Project Management Software
+#
+# Copyright (c) 2006, 2007, 2008, 2009 by Chris Schlaeger <cs@kde.org>
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of version 2 of the GNU General Public License as
+# published by the Free Software Foundation.
+#
+
+require 'optparse'
+require 'Tj3Config'
+require 'SyntaxReference'
+require 'UserManual'
+
+AppConfig.appName = 'tj3man'
+
+class Arguments
+
+  attr_reader :keywords, :directory, :manual
+
+  def initialize(argv)
+    @keywords = []
+    @directory = './'
+    @manual = false
+
+    opts = OptionParser.new
+    opts.banner = "#{AppConfig.packageName} v#{AppConfig.version} - " +
+                  "#{AppConfig.packageInfo}\n\n" +
+                  "Copyright (c) #{AppConfig.copyright.join(', ')}" +
+                  " by #{AppConfig.authors.join(', ')}\n\n" +
+                  "#{AppConfig.license}\n" +
+                  "For more info about #{AppConfig.packageName} see " +
+                  "#{AppConfig.contact}\n"
+    opts.separator ''
+    opts.separator "Usage: #{AppConfig.appName} [options] [<keyword> ...]"
+    opts.separator 'Options:'
+
+    opts.on('-d', '--dir <directory>', String,
+            'directory to put the manual') do |dir|
+      @directory = dir
+    end
+    opts.on('-m', '--manual',
+            'Generate the user manual into the current directory or ' +
+            'the directory specified with the -d option.') do
+      @manual = true
+    end
+    opts.on_tail('-h', '--help', 'Show this message.') do
+      puts opts
+      exit
+    end
+    opts.on_tail('--version', 'Show version number.') do
+      puts opts.banner
+      exit
+    end
+
+    @keywords = opts.parse(argv)
+  end
+
+end
+
+def main
+  args = Arguments.new(ARGV)
+
+  man = TaskJuggler::SyntaxReference.new
+  keywords = args.keywords
+
+  if args.manual
+    TaskJuggler::UserManual.new.generate(args.directory)
+  elsif keywords.empty?
+    puts man.all.join("\n")
+  else
+    keywords.each do |keyword|
+      puts man.to_s(keyword)
+    end
+  end
+
+  #$stderr.puts "#{AppConfig.packageName} v#{AppConfig.version} - " +
+  #             "#{AppConfig.packageInfo}\n\n"
+  #puts man.to_s(args.keyword)
+
+  exit 0
+end
+
+main()
+

data/manual/Day_To_Day_Juggling

@@ -0,0 +1,168 @@
+== Day To Day Juggling ==
+
+
+=== Tracking the Project ===
+
+Once the initial plan has been made and the project has started, TaskJuggler
+can be turned from a planning tool into a tracking tool. You don't have to
+change a lot to do this. After all, as the initial plan is almost always just a
+first guess, you need to continue planning your project as new details become
+evident. So what you really want is a way to gradually freeze the plan as work
+has been completed, while still having full flexibility with all future work.
+
+While it is generally accepted to invest some amount of time in project
+planning, it is very common that once the project has been started, project
+managers tend to avoid a proper tracking of the project. Our bet is that the
+vast majority of project plans are only made to get management or investor
+approval. After the approval phase, many project managers only work with their
+project plan again when the project is running really late. On the other hand
+there are projects that are done using strict project management techniques
+that require detailed status tracking. Both extremes probably have their fans
+and TaskJuggler offers good support for both extremes as well as various
+techniques in between.
+
+=== Recording Progress ===
+
+As mentioned previously, your initial project plan is only a first estimate of
+how the project will progress. During the course of the project you will have
+to make changes to the plan as new information needs to be taken into account
+and you probably want to track the progress of the project in a formalized
+form. TaskJuggler will support you during this phase of the project as well,
+but it needs your help. You have to provide the additional information in the
+project file. In return you get current status reports and an updated project
+plan based on the current status of the project.
+
+The most simple form of capturing the current status of the project is to use
+the complete attribute.
+
+ task impl "Implementation" {
+   depends !spec
+   effort 4w
+   allocate dev1, dev2
+   complete 50
+ }
+
+This tells TaskJuggler that 50% of the task's effort has been completed by the
+current date. Tasks that have no completion specification will be assumed to be
+on track. TaskJuggler calculates the completion degree based on the current
+date. Completion specifications only need to be supplied for tasks that are
+either ahead of schedule or behind schedule. Please keep in mind that the
+completion degree does not affect the scheduling and resource allocation. It is
+only for reporting purposes. It also does not tell TaskJuggler which resource
+actually worked on the tasks.
+
+If you want the past work to affect scheduling you must use the booking
+statements as outlined in the next section.
+
+When your project plan reflects the current status of your project, TaskJuggler
+can generate nice status reports for you. To generate an HTML report for the
+last week listing all tasks that are running late, all tasks that are ongoing,
+tasks that have been completed last week, and task that will be started next
+week, you just specify 
+
+ htmlstatusreport "Status-Report.html" {
+ }
+
+=== Recording Resource Usage ===
+
+The initial project plan should be made by entering the minimum amount of
+required information such as task dependencies and efforts. TaskJuggler will
+then compute all the missing data based on this initial setup. This is your
+project baseline. As the project progresses you can now track the work already
+completed by recording the work that your resources have done. Let's assume you
+had the following task in your original plan: 
+
+ task impl "Implementation" {
+   depends !spec
+   effort 4w
+   allocate dev1, dev2
+ }
+
+After the first week of work on this task the two resources have really been
+able to complete half the job. You can capture this in your project plan using
+the booking attribute. Bookings are resource specific, so you have to add the
+booking to the resource definition, not the task definition.
+
+ resource dev1 "Developer 1" {
+   booking impl 2005-04-11 - 2005-04-16 { sloppy 2 }
+ }
+ 
+ resource dev2 "Developer 2" {
+   booking impl 2005-04-11 - 2005-04-16 { sloppy 2 }
+ }
+
+The sloppy attribute defines the accuracy of your bookings. If it's missing or
+0, the booking must only describe a continuous working period during working
+hours. With higher values the interval may overlap with off-hour or vacation
+time slots. See details on sloppy.
+
+If you don't like to mix the resource definitions and their bookings, you can
+specify the bookings with supplement statements. These supplement statements
+can even reside in an other file. Some companies have created a web front-end
+for their developers to report the completed work against the project plan. The
+reports are stored in a database and include files for TaskJuggler are
+generated from this database. This way the project manager gets a very current
+status of the project and can compute the current project plan based on these
+data without much effort. If you are interested in this you should have a look
+at the download section of the TaskJuggler web site.
+
+It is ok to specify bookings beyond the effort value found in the task
+definition. In case you want to declare a task as done, even if the bookings do
+not reach the specified effort or length, you can use the scheduled property.
+
+ supplement task impl {
+   actual:scheduled
+ }
+
+As a side note we would like to mention that the recording of the work time of
+employees is regulated by labor law in certain countries. You might also
+require approval from a Worker's Council before you can deploy time recording
+tools.
+
+In case your actual progress does not deviate a lot from your project plan, you
+can generate the file with the booking statements automatically.
+
+ export "DoneWork-Week15.tji" {
+   hideresource 0
+   start 2005-04-11
+   end 2005-04-16
+   properties bookings
+ }
+
+This will generate a TaskJuggler include file that contains all bookings
+according to the project plan for the specified interval. You can then use this
+file as a baseline and modify it to reflect the real work that has happened
+during the interval. After that you can include it into your project again.
+
+ include "DoneWork-Week15.tji"
+
+As this include file references the tasks and resources of your project you
+should include it after all task and resource definitions.
+
+To make TaskJuggler aware that you want to compute the end date based on the
+bookings and the effort you need to enable the projection mode for the
+scenario. This has to be done in the scenario definition in the project header.
+If you don't have a scenario definition because you are only using the built-in
+default scenario, you have to add a scenario definition.
+
+ project prj "Project" "1.0" 2005-04-01 - 2005-05-01 {
+   scenario plan "Plan" {
+     # Compute when the task will be ready based on the already
+     # done work and the current date.
+     projection
+   }
+ }
+
+TaskJuggler now assumes that for all tasks that have bookings, all work has
+been specified with bookings up to the current date. It then calculates the end
+date of the task based on the effort that is still left over. It also computes
+the complete value based on the specified bookings. So if you specify bookings
+for a task you should not specify a completion value as well. It will be
+ignored and replaced by a value based on the specified bookings.
+
+When you now schedule the project again, it will take these bookings into
+account and generate a new project plan based on your current project status.
+Each time you review your project status you should generate such an include
+file for the period that you are reviewing. Then you sync the content with the
+feedback that you get from your resources and add the file to the project plan.
+

data/manual/Getting_Started

@@ -0,0 +1,61 @@
+== Getting Started ==
+
+=== Basics ===
+
+TaskJuggler uses one or more text files to describe a project. The
+main project should be placed in a file with the .tjp extension. This
+main project may include other files. Such included files must have
+file names with a ''''.tji'''' extension.
+
+The graphical user interface from the 2.x version has not been ported
+to TaskJuggler III yet. So all work with TaskJuggler needs to be done
+in your favorite text editor and in a command shell.
+
+The commandline version of TaskJuggler works like a compiler. You
+provide the source files, it computes the contents and creates the
+output files. Let's say you have a project file called
+''''AcSo.tjp''''. It contains the tasks of your project and their
+dependencies. To schedule the project and create report files you have
+to ask TaskJuggler to process it.
+
+ tj3 AcSo.tjp
+
+TaskJuggler will try to schedule all tasks with the specified
+conditions and generate the reports that were requested with the
+[[htmltaskreport]], [[htmlresourcereport]] or other report properties
+in the input file. The report files will be generated in the current
+directory or relative to it.
+
+If you specify file names in a project file, you need to use the
+''''/'''' as directory separator. This way, projects are portable
+across all operating systems. Do not use the ''''\'''' or '''':''''
+that are used on some operating systems.
+
+=== Structure of a TJP File ===
+
+Each TaskJuggler project consists of one or more text files. There is
+always a main project file that may [[include.properties]] other
+files. The main file name should have a ''''.tjp'''' suffix, the
+included files must have a ''''.tji'''' suffix.
+
+Every project must start with a [[project project header]]. The
+project header must be in the main project file. All other elements
+may be put into include files. The project header must then be
+followed by any number of project properties such as [[account
+accounts]], [[resource resources]] and [[task tasks]]. Each project
+must have at least one task defined and should have at least one
+[[reports report]].  Properties don't have to be listed in a
+particular order, but may have interdependencies that require such an
+order. If you want to assign a resource to work on a task, this
+resource needs to be defined first. It is therefor recommended to
+define them in the following sequence.
+
+* [[macro macros]]
+* [[flags]]
+* [[account accounts]]
+* [[shift shifts]]
+* [[vacation vacations]]
+* [[resource resources]]
+* [[task tasks]]
+* [[reports]]
+

data/manual/How_To_Contribute

@@ -0,0 +1,185 @@
+=== How to Contribute ===
+
+==== Why contribute? ====
+
+TaskJuggler is an Open Source Project. It was developed by volunteers
+mostly in their spare time. Made available under the GNU General
+Public license and similar licenses, TaskJuggler can be shared and
+used free of charge by anybody who respects the license conditions.
+Does that mean you can use it without worrying about anything? Clearly
+not! Though users have no legal obligation to contribute, you should
+feel a moral obligation to support Open Source in whatever way you
+can. This can range from helping out other users with their first
+Linux installation to actively contributing to the TaskJuggler
+Project, not just as a programmer. The following section describes,
+how you can contribute to any of the components that are part of the
+TaskJuggler software releases.  
+
+==== Preparing a contribution ====
+
+All TaskJuggler development is coordinated using the
+[http://git.or.cz/ Git revision control system]. All changes must be
+submitted using Git so that we can track the authorship of each
+submission. To contribute you need to have at least Git version 1.5.0
+installed. Git was developed as a tool for the Linux Kernel
+developers but is now very popular with many other Open Source
+projects as well. Git and the TaskJuggler development environment are
+primarily designed to be used on Linux or Unix-like systems. While it
+is possible to use it on other systems such as Microsoft Windows, we
+do not recommend this. If you can't switch to a Linux installation
+for your TaskJuggler contributions, you should consider using a Linux
+Live (or bootable) CD/DVD or use a VmWare Player image of a Linux
+distribution.
+
+As a first step, you need to checkout the latest version of
+the TaskJuggler. This will create a directory called taskjuggler in
+your current directory. It not only contains the latest sources, but
+also the full revision history of the code. It is your local copy of
+the TaskJuggler source repository.
+
+ git clone http://www.taskjuggler.org/git-repos/taskjuggler.git
+
+If you have never used Git before, you need to configure it first. You
+need to set your name and email address. This information will be
+present in all patches that you submit.
+
+ git config --global user.name "Your Name"
+ git config --global user.email "firstname.lastname@domain.org"
+
+See the [[Installation]] section for how to build and install
+TaskJuggler.
+
+Do not use the development snapshots and send your patches as plain
+diff files. After having switched to Git, we no longer accept such
+patches.
+
+Next you need to find the files where you want to make your
+modifications. Sometimes files will be generated from other files. Do
+not change those generated files. Your changes will be overwritten the
+next time you call the make utility. To identify those files, some
+familiarity with make and other Linux tools are helpful. Whenever
+there is a file with the same base name and the extension .in in the
+same directory, then the file is generated from the .in-file. You need
+to modify the .in-file, not the one with just the base name. Another
+indicator is the fact that the file is not part of the repository.
+With few exceptions the repository does not contain any generated
+files.
+
+==== Creating a Patch ====
+
+When you are done with your changes, it's a good idea to test them. In
+the taskjuggler directory run the following commands. 
+
+ cd taskjuggler3
+ rake test
+ rake manual
+ rake gem
+
+If there are no errors, you can check or test the result. If
+everything works fine, you can lock at your changes again.
+
+ git diff
+
+The git-diff utility performs a line-by-line comparison of the files
+against the latest version in you local repository. Try to only make
+changes that have an impact on the generated files. Do not change
+indentation or line wrapping of paragraphs unless absolutely
+necessary. These kinds of changes increase the size of diff files and
+make it much harder to evaluate the patches. When making changes to
+the program code, please use exactly the same coding style. If your
+contribution is large enough to justify a copyright claim, please
+indicate what copyright you claim in the patch. For modifications to
+existing files, we will assume that your contribution falls under the
+same license as the modified file. All new files will need to contain
+a license declaration, preferably GPL version 2. In any case, the
+license must be [http://www.opensource.org/licenses an OSI accepted
+license] and be compatible with the rest of the project.
+
+Review all changes carefully. In case you have created new source
+files, you need to register them with your repository.
+
+ git add FILENAME
+
+If you think you are done, you can commit your changes to your local
+repository.
+
+ git commit -a
+
+Whenever you have made a certain change or added a certain feature,
+you should commit your changes to your local repository. This keeps
+patches small and makes reviewing them easier. The easier your patches
+can be reviewed, the more likely they will get in.
+
+The final step to submit your changes is to package them up and sign
+them. It is always a good idea to check for upstream changes again.
+
+ git pull
+
+This makes sure you are really committing your patches against the
+latest version of the source code. In case there were upstream
+changes, you need to merge them first. Usually Git does this
+automatically. Refer to the
+[http://www.kernel.org/pub/software/scm/git/docs/user-manual.html Git
+manual] for details on resolving conflicts during merges. Now you can
+create the patch or patch-set.
+
+ git format-patch -s origin
+
+This will generate a number of files starting with 5-digit file names.
+You then need to attach these files to a posting in the
+[http://www.taskjuggler.org/FUDforum2/index.php?t=thread&frm_id=5
+TaskJuggler Developer Forum].
+
+==== Contributing to the User Manual ====
+
+The user manual is currently a rough port of the 2.x manual. It
+contains many inaccuracies and does not provide much more than a
+tutorial and a syntax reference. Any help to turn this into a real
+user manual is greatly appreciated.
+
+The manual is composed from 3 different sources.
+
+# The sources for normal pages are in MediaWiki format and can be
+found in the ''''manual'''' directory of the source distribution. 
+
+# The information in the syntax reference is extracted from the TJP
+parser source code. It can be found in the file
+''''lib/TjpSyntaxRules.rb''''. You can ignore all but the
+''''doc(...)'''', ''''arg(...)'''' and ''''example(...)'''' sections.
+
+# The TJP examples are in the ''''test/TestSuite/Syntax/Correct''''
+directory.
+
+The following commands build the HTML files for the manual in the
+''''data/manual'''' directory.
+
+ cd lib
+ ruby UserManual.rb 
+
+==== Contributing to the Test Suite ====
+
+The test suite can be found in the ''''test'''' directory. It
+contains unit and system tests but is very rudimentary at the moment.
+Adding more system tests to the CSV-Report directory is probably the
+best place to start.
+
+==== Contributing to the Ruby code ====
+
+For the first stable TaskJuggler III release we should have all 2.x
+features supported. The few things that break backwards compatibility
+should be documented in the [[TaskJuggler_2x_Migration]] section.
+
+In general, patches are very welcome. Please follow the coding style
+and naming conventions used in the existing code. Larger changes
+should be preceded by a discussion in the
+[http://www.taskjuggler.org/FUDforum2/index.php?t=thread&frm_id=5
+TaskJuggler Developer Forum].
+
+==== Some final words to Contributors ====
+
+We do welcome all contributions, but please understand that we reserve
+the right to reject any contribution that does not follow the above
+guidelines or otherwise conflicts with the goals of the TaskJuggler
+team. It is a good idea to contact the team prior to making any larger
+efforts.
+