Andreas/tracks
1
0
Fork 0
mirror of https://github.com/TracksApp/tracks.git synced 2026-01-21 16:36:08 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

Removed superfluous 'tracks' directory at the root of the repository.

Browse source 
Testing commits to github.
This commit is contained in:
bsag 2008-05-20 21:28:26 +01:00
parent 6a42901514
commit 4cbf5a34d3
2269 changed files with 0 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

150
doc/CHANGELOG Normal file
View file

@ -0,0 +1,150 @@
= Tracks: a GTD web application, built with Ruby on Rails
* Homepage: http://www.rousette.org.uk/projects/
* Author: bsag (http://www.rousette.org.uk/)
* Contributors: Nicholas Lee, Lolindrath, Jim Ray, Arnaud Limbourg, Timothy Martens, Luke Melia, John Leonard, Jim Strupp, Eric Lesh, Damien Cirotteau, Janet Riley, Reinier Balt, Jacqui Maher, James Kebinger
* Version: 1.5rc1
* Copyright: (cc) 2004-2008 rousette.org.uk
* License: GNU GPL
Main project site: http://www.rousette.org.uk/projects/
Trac (for bug reports and feature requests): http://dev.rousette.org.uk/report/6
Wiki (deprecated - please use Trac): http://www.rousette.org.uk/projects/wiki/
== Version 1.5rc1
1. Show from date allows you to postpone the appearance of actions in the list until you can do something about them (like a 'tickler')
2. Tagging of actions
3. Simple management of users (deleting users through the web interface)
4. Import and export of data in various formats
5. Fantastic RESTful API to provide access to actions via scripts
6. Mobile interface designed for use on mobile phone browsers
7. Improved ease-of-use for installation and upgrading
8. Optional support for authentication via OpenID or LDAP
9. Update to Rails 1.2.3
10. Per-user time zone preference
11. Use autocomplete fields for Project and Context specification to support on-the-fly adding of each
12. Add a "Hidden" status to projects
13. Add optional Default Context for a Project
14. Add ability to sort projects alphabetically
15. Add "starring" of actions
16. Statistics page with graphs
17. Rake task to set password. Usage: rake tracks:password USER=useranme
== Version 1.041
=== New features
1. Tracks now has an API, written by Luke Melia, which allows you to create new actions in a particular context remotely, using scripts. See http://www.rousette.org.uk/projects/downloads/comments/adding-next-actions-via-scripts-the-tracks-api/ for some example scripts and instructions. If anyone creates scripts for other platforms (Windows or Linux), or more fancy ones for Mac OS X, do share them!
2. The feeds page now lists iCal links alongside each RSS and TXT feed link. Copying your chosen link and pasting it in to the text box that appears in iCal when you choose Calendar > Subscribe.. Name your calendar as you wish, but make sure that you get it to refresh periodically and that the 'Remove Todo items' checkbox is UNCHECKED (obviously ;-) ). Then your Tracks next actions should appear as todo items in iCal, with proper due dates assigned, and notes in the notes field. The todos should update periodically in iCal as you add, delete or complete items in Tracks, but the subscription is read-only from iCal's end. However, it does allow you read access on the move if you sync iCal with your Palm or mobile phone.
3. Setting no_completed in the user preferences to zero now removes the completed items box completely from the home page and from the individual context and project pages, if you don't like completed items cluttering those pages up.
4. You can set a local time zone in environment.rb if your local time zone is different from the time zone setting on the server running Tracks.
5. 'Add users' link added to the navigation bar for the admin user, which is a convenient way to get to the signup page.
6. Luke fixed the edit actions method so that changing an action's context immediately moves it in an Ajaxy way to the new context.
7. Updated vendor directory to Rails 1.1
=== Minor additions and bug fixes
1. Deleting a context now correctly deletes any actions in it as it should. Again.
2. The user's context ordering is now honoured in the feeds (Luke Melia).
3. A 'spinner' next to the date at the top of the page informs you that an Ajax action is in progress (Luke Melia).
4. Text feeds now don't have superfluous blank lines.
5. Fixed errors on 'done' page.
6. Expansion and collapsing of the context boxes now works without a refresh after an Ajax action. (Luke Melia).
7. User id only is now stored in the session object, reducing the size of the object and improving security (Luke Melia).
8. Notes page now doesn't raise an error if you don't have any notes created yet.
9. notes.yml fixture fixed so that it contains all the correct fields, so using the test contents should work properly again.
10. The Completed Items box on the home, context and project pages now shows the same format for the actions as the Done page.
11. The navigation bar now shows which page you are on by underlining the appropriate link and colouring the text black.
12. There are new accesskeys for the notes page (alt/ctrl o) and user preferences (alt/ctrl u).
== Version 1.04
1. Tidied up the interface a bit, fixing mistakes in the wording.
2. The number of actions reported is now correctly pluralized depending on the number of actions (e.g. 1 action, 2 actions).
3. Added a Note model and notes database table. Notes have their own interface (/notes lists them all, and /note/1 shows note id 1), but they are displayed on the /project/show/[name] page. For now, notes belong to a particular project, and are added from the /project/show/[name] pages. You can delete and edit notes either from the /notes page or from the /note/[id] page. Notes use Textile/Markdown formatting.
4. Can now host multiple users on a single tracks install. User creation only possible by admin user.
5. Major improves to the render-flow, code reuse and MVC rationalisation.
6. Rails based db creation and migration via rake.
7. Added loginhash to settings.yml.
8. Modify signup to prevent is_admin being set by malicious user. Begin work on standardising layout for login controller.
9. BIGGEST NEW FEATURE: Tracks is now properly multi-user, thanks to the work of Nicholas Lee. Any new users that you sign up can't view any of your next actions, contexts, projects or notes, and they get a clean slate to add their own. Great Things are planned in this direction...
10. Projects now have a description field which you can edit in the form on [tracks_url]/projects. It's optional, but you can use it to remind you of the aims or purpose of the project. If you have a description, it's displayed in italics just under the project name.
11. Included a new rake task. Call it with <tt>rake setup_tracks</tt> at the command line. This automates a lot of the work of setting up tracks, like renaming the template files (*.tmpl). However, you need to make sure that you've copied database.yml.tmpl to database.yml before you run it (and added the correct settings to the file), because rake can't run without that file in place. The task is safe to run if you're upgrading, because it ignores already converted files.
12. Changed the shebang lines to <tt>#!/usr/bin/env ruby</tt>. This should work for all *nix based setups (Linux or Mac OS X), but Windows users will probably have to change it. Try this command at the command line, run inside the Tracks directory:
ruby -i.bak -pe 'gsub!("#!/usr/bin/env ruby", "#!c:/ruby/bin/ruby")' public/dispatch.* script/*
13. The TXT view is now sorted by position, just as the home page is.
14. <b>Contributed by lolindrath</b>: Items that are overdue are coloured red, and have the text 'Overdue by X days' in the badge. Other due dates are given as days from now (up to a week away in orange, more than a week away in green), and the tool tip shows the actual date.
15. Projects and Contexts in [tracks_url]/projects and [tracks_url]/contexts can now be rearranged in order by dragging and dropping. Just pick the item up by the 'DRAG' label and drop it where you want.
16. Got rid of the 'fresh actions' box on the home page. When you create a new action, it is now automatically inserted (via the magic of Ajax and RJS templates) at the bottom of the correct context box.
17. The next action count badge is now dynamically updated whenever you add or delete a next action, so that you don't have to refresh to see the count updated.
18. Validation errors are now reported in a status box (just above the new next action form).
19. There's a rake task (upgrade_sqlite_db) which allows you to safely upgrade databases created with version 1.03, afterwhich you can run rake migrate to complete the process. From there, rake migrate should work OK.
20. Moved settings for Tracks from the file settings.yml to the database. Running 'rake migrate' will update your database appropriately, and add the default settings into it. Then you should be able to visit <tt>http://0.0.0.0:3000/user/preferences</tt> to view and edit your settings. The advantage is that you don't need to mess about with the settings.yml file, and each of the users can have their own settings.
21. Session data is now stored in the database rather than a file in tracks/tmp. This should prevent the tmp directory cluttering up the file system, and give better performance. You need to run rake migrate to add the session table to your database.
22. You can now change the password for the logged in user (user/preferences)
23. Lots of new text and RSS feeds added by Luke Melia. These are accessed via the feed icon on in the main navigation.
== Version 1.03
13. All the adding, updating, deleting and marking actions done is performed using Ajax, so happens without needing to refresh the page.
14. There's a new setting in settings.yml ('staleness_starts') which defines the number of days before which actions get marked as stale. Let's say you set it to 7 days. Actions created between 7 and 14 days ago get marked pale yellow, those created between 14 and 28 days ago (staleness_starts x 2) get marked darker yellow, and those created more than 28 days ago (staleness_starts x 3) are fluorescent yellow! This is only applied to items without a due date, so you can add items to be done some time in the future without getting yellow splashed all over the place (thanks to Nicholas for the patch to restrict to items with no due date).
15. Contexts and projects can now be sorted in any order you like. Arrow buttons on the <tt>/contexts</tt> and <tt>/projects</tt> pages let you move an item to the top, up, down or to the bottom. For contexts, this affects the order in which they sort on the home page. Position is also used to sort the listings of active/completed/hidden contexts and projects in the 'sidebar', and in the dropdown lists on forms.
16. You can mark projects as completed (by editing the project on <tt>/projects</tt>). In the 'sidebar' active and completed projects are shown separately, but you can still view the completed project.
17. New images (from eclipse.org) for the edit, delete, notes and up, down, top and bottom buttons. I've made a greyscale version for the default, then the coloured version gets loaded when the mouse is hovering over the button.
1. Added back border="0" to images which I had mistakenly taken out. This should fix the ugly red border around images that appears in Firefox (thanks, Adam Hughes).
2. Removed the section in <tt>config/environment.rb</tt> which requires Redcloth. This was causing errors because Rails now requires Redcloth itself. This means that you now need to have Redcloth installed as a gem (gem install redcloth) (thanks, Jim).
3. SQL dumps are now available for each of the available database formats (MySQL, PostgreSQL and SQLite), as well as a separate file containing some example contents, which should work for all of the formats. These are in the <tt>tracks/db</tt> directory (thanks, Jim)
4. The new item forms on all pages now use a mini calendar which pops up when you click in the due date field. The calendar is the GPL one from dynarch.com http://www.dynarch.com/projects/calendar/
5. <b>Contributed by Lolindrath</b>: Toggling of contexts in on the home page to collapse or expand their display via a small '+' or '-' graphic. This is independent of the shown/hidden setting for contexts, and is ideal for just hiding things on the fly to focus your view.
6. <b>Contributed by Jim Ray</b>: Jim added a host of fixes and bits of cleaning up, including a position column for contexts and projects to allow custom sorting, and changes to the links for pages to make them more human-readable.
7. <b>Contributed by Nicholas Lee</b>: URLs are now generated using the <tt>url_for</tt> or <tt>link_to</tt> methods, which should mean that people using Tracks in a subdirectory won't have to manually tinker with the URLs to get them to work.
8. <b>Contributed by Arnaud Limbourg, ticket 18</b>: A new entry in settings.yml allows you to choose the number of completed actions you want to see on the home page. Also sorts by due date (ascending) first, then creation date (descending) on the home page, <tt>/context/show/[name]</tt>, and <tt>/project/show/[name]</tt>.
9. Counts of next actions are now shown on the <tt>/context/show/[name]</tt> and <tt>/project/show/[name]</tt> pages. These just show how many uncompleted actions you have in the selected context or project.
10. <b>Patch by lolindrath</b>: Sorting by date is now much smarter on the home page. Actions are sorted by ascending due date then ascending creation date, but non-due dated items sort to the bottom. This means that the most urgent items float to the top of each context list.
11. You can now uncheck actions from the completed actions list, so that they dynamically appear back in the uncompleted actions area.
12. A tiny improvement: the toggling of the individual notes now uses Element.toggle from prototype.js, so it doesn't have to be an onLoad property of the body tag. This means that you don't get the notes flashing before they are hidden when you load or reload a page.
== Version 1.02
1. Uses Rails 0.10.0
2. Added validation for the entry fields. If you enter a bit of text that's too long or you omit the description (not much point in a blank next action!) you'll get an error message and the action won't be saved.
3. Added action caching.
4. Did a bit of refactoring to try to make page loading a bit more efficient.
5. Added a new row to the context table: 'hide'. This determines whether a particular context gets hidden on the main page. If the checkbox on the add new context form is checked, the context is hidden, and isn't listed on the front (todo/list) page. This is useful for contexts like 'wish list' or 'someday/maybe' that you don't want taking up your attention all the time.
6. Added a list of links to the hidden contexts at the bottom of the page.
7. Changed the method of adding due dates to drop-down option lists. It's more obvious and less error prone than typing in the date. Your preferences for date formatting are still honoured when displaying due dates.
8. Added a favicon, kindly produced by Jim Ray.
9. Added border="0" to the button images to stop Firefox putting a red border around them.
10. Added a new path:, base: setting in settings.yml. This is used in constructing URLs in standard.rhtml and other places for the javascripts and stylesheets. You need to specify it in the format <tt>http://my.domain.tld/subdir/tracks</tt>, or whatever the full URL is. This should help people who put Tracks in a subdirectory.
11. Added some rudimentary sorting of completed items. They are now sorted in to done today, done in the last 7 days and done in the last 31 days. At the bottom of completed.rhtml, there's a link to completed_archive.rhtml, which shows archived items older than 31 days.
12. Changed the method of generating links to stylesheet and javascripts. Together with the new Routes, this should sort out any problems with putting Tracks in a sub-directory.
13. config/environment.rb now checks to see if a gem version of Redcloth is installed that is greater than version 3.0.3. If that fails, it falls back on the packaged lib version. Note that there's an odd bug I can't seem to pin down that means that if you are using the packaged lib version, you'll get some errors like: <tt>./script/../config/..//lib/redcloth.rb:169: warning: already initialized constant VERSION</tt> or <tt>./script/../config/..//lib/redcloth.rb:170: warning: already initialized constant DEFAULT_RULES</tt> but ONLY if you're using the development environment; with production it's fine, and with the gem version of Redcloth it's fine in both environments.
13. Modified the 'count' badge on todo/list: now shows the number of uncompleted items in contexts that <b>aren't</b> hidden (i.e. the actions actually listed on todo/list). Number of items in hidden contexts are shown in parentheses after the link to that context. So you don't forget about that stuff ;-)
14. Protected RSS and text feeds at last! The appropriate URLs can be copied from the RSS and TXT links in the navigation bar. The URL includes the login name of the current user, and an MD5 encoded string of the 'word' field of the users table. This is checked against users to make sure it's valid; if it is, the feed is displayed, if not, you get an error message.
15. Better signup system implemented. The users table has another new column, 'is_admin'. If no users have been created, the first user to sign in is made the admin user. If the admin user (while logged in), visits the signup page, the form indicates that this user can create a new user (who won't have admin rights). If anyone who is not not logged in and not an admin user visits signup, they are greeted with a message that they don't have permission to create an account, and should contact the admin. I've made a new field in settings.yml to hold your admin email address for this purpose. This should mean that you can safely leave signup.rhtml intact on a public server.
16. Added a list of other contexts and projects to the context/show/[id] and project/show/[id] pages, so that you can easily navigate between the filtered views of contexts and projects, without having to go back to context/list or project/list.
== Version 1.01
A small increment to fix a few bugs and typographical errors in the README:
1. README.txt now lists the correct location for the dump file
2. Fixed the redirection from the login page. Once you have signed up or logged in, you should be taken automatically to the main todo/list page. This also works once you have logged out and clicked the "<< login" page to get back to <tt>login/login</tt>. (Thanks, Max Prophet!)
3. Properly updated for Rails 0.9.3: this probably means that it won't work for a lower version of Rails. If you have the gems version of Rails installed, you can update it with: <tt>sudo gem update rails</tt>
4. Made some minor changes to the appearance of the listed items, so that the description wraps properly, and the tool buttons (edit, delete and notes) are always in the same place relative to the checkbox.
== Version 1.0
1. Updated to run on Rails 0.9.1. This should work with any 0.9.x branch.
2. Added a proper edit page for todos. This also allows you to add a todo to a project, or re-assign it to a new project.
3. Improved the efficiency of the Projects page: it now only finds the Project you've selected, rather than all of them (thanks, Johan http://theexciter.com/!)
4. You now get a warning if you try to delete a project or context with undone items. If you choose to continue, the dependent items will be deleted, so that the list page should no longer break.
5. Using Redcloth for markup now that it allows you to use either Textile or Markdown format transparently. This is now included in the distribution, so that you don't need to install it.
6. Added links to context/list page so that you can go directly to <tt>todo/show/blah</tt> if you click the link for context 'blah'.
7. You can now set the date format you want to use in the file config/settings.yml. Use the strftime formats, with whatever separator you like. e.g. If you want 2004-12-31, the correct format is <tt>%Y-%m-%d</tt>. 31/12/2004 would be <tt>%d/%m/%Y</tt>. The same format is used for entry of the date in the due date box, and for display of the date in the list.
8. You can now add a new item to a particular project when you are viewing it at <tt>/project/show/[id]</tt>. This makes it easy to add a block of next actions to a project. Edit and delete buttons work on this page, but redirect you to <tt>/todo/list</tt>. I need to fix this.
9. Added a login system by using the login_generator: http://wiki.rubyonrails.com/rails/show/LoginGenerator. The first time you access the system, you need to visit <tt>[tracks_url]/login/signup</tt> to enter a username and password. Then when you visit, you will be greeted with a login page. This stores a temporary cookie for your session. The whole app is protected by the login.
10. You can now add a new item to a particular context when you are viewing it at <tt>/context/show/[id]</tt>. This makes it easy to add a block of next actions to a project. Edit and delete buttons work on this page, but redirect you to <tt>/todo/list</tt>. I need to fix this.
11. Feeds! There's an RSS feed available at <tt>[tracks_url]/feed/na_feed</tt> which shows the last 15 next actions, and a text feed at <tt>[tracks_url]/feed/na_text</tt> which gives you a plain text list of all your next actions, sorted by context. You can use the latter to display your next actions on the desktop with GeekTool. Simply set up a shell command containing the following: <tt>curl http://[tracks_url]/feed/na_text</tt>. Obviously, you need to replace [tracks_url] with the actual URL to the Tracks application.

23
doc/README_DEVELOPERS Normal file
View file

@ -0,0 +1,23 @@
1. SQLITE3 FOR TESTING
By default, tests are configured to run using sqlite3 in memory mode to increase speed. You will need the sqlite3-ruby gem for this.
To avoid showing the migrations as tests are run, add the following to your database.yml below 'database: ":memory:"':
verbosity: quiet
If you want to run tests using another database, that's fine, too. Just change your database.yml accordingly.
2. SELENIUM TESTS
To run selenium tests, start Tracks in test mode using
script/server -e test
Then open a browser to
http://localhost:3000/selenium/
and interact with the test runner.
For more information about Selenium on Rails, see vendor/plugins/selenium-on-rails/README

29
doc/manual.css Normal file
View file

@ -0,0 +1,29 @@
body {
width: 60%;
font-family: Helvetica, Arial, sans-serif;
font-size: 1em;
margin: 20px auto;
line-height: 1.5em;
}
a {
color: #9E2029;
text-decoration: none;
}
a:hover {
color: #DE8E30;
text-decoration: underline;
}
a:visited {
color: #DE8E30;
}
code {
color: #000;
background-color: #E3E3E3;
padding: 2px;
}
.footnote {font-size: 0.9em; vertical-align: super;}

251
doc/manual.html Normal file
View file

@ -0,0 +1,251 @@
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1 plus MathML 2.0//EN"
"http://www.w3.org/TR/MathML2/dtd/xhtml-math11-f.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<!-- Processed by MultiMarkdown -->
<meta name="Author" content="Tracks Development Team" />
<meta name="BaseHeaderLevel" content="2" />
<link type="text/css" rel="stylesheet" href="manual.css" />
<meta name="Copyright" content="2008 rousette.org.uk
This work is licensed under a Creative Commons License.
http://creativecommons.org/licenses/by-nc-sa/3.0/" />
<meta name="Date" content="2008-04-07" />
<meta name="Format" content="complete" />
<meta name="LaTeXXSLT" content="memoir-twosided-manual.xslt" />
<meta name="Revision" content="$Id: manual.markdown 811 2008-04-07 20:21:00Z bsag $" />
<title>Tracks 1.5 Manual</title>
<meta name="Version" content="1.5" />
<meta name="XMP" content="CCAttributionShareAlike" />
</head>
<body>
<!-- The HTML file manual.html is generated from manual.markdown, so make edits to the *.markdown file -->
<h2 id="installingtracks1.5">Installing Tracks 1.5</h2>
<h3 id="introduction">Introduction</h3>
<p>Tracks 1.5 has been thoroughly beta tested by a large number of people, and should be fully stable for everyday use. However, once set up, Tracks will contain the majority of your plans for your work and personal life, so it&#8217;s only sensible to make sure that you have frequent, reliable backups of your data. Full changenotes on the release can be found in <code>doc/CHANGELOG</code>. Full API documentation can be found at <code>doc/app/index.html</code>, once you have run <code>rake appdoc</code></p>
<p>There are two methods of downloading Tracks 1.5 <strong>(N.B. These links will not work until Tracks 1.5 final is released)</strong>):</p>
<ol>
<li>(Recommended for most people) Download the <a href="http://www.rousette.org.uk/projects/files/tracks-current.zip">zipped package</a>, and unzip in your preferred location (e.g. <code>~/Sites</code> for Mac OS X users).</li>
<li>Download using Subversion:</li>
</ol>
<pre>
<code>
svn co --username=guest
http://www.rousette.org.uk/svn/tracks-repos/tags/current tracks
</code>
</pre>
<h3 id="requirements">Requirements</h3>
<p>The Tracks interface is accessed through a web browser, so you need to run a webserver to serve the Tracks pages up to you. This isn&#8217;t as daunting as it sounds, however: Tracks ships with a built-in web server called Mongrel which you can run on your own computer to serve the Tracks application locally. If you want to be able to access Tracks from any computer connected to the Internet, then you need to install Tracks on a publicly accessible server, and you will probably be better off using a more robust server such as <a href="http://www.apache.org/">Apache</a> or <a href="http://www.lighttpd.net/">Lighttpd</a> to serve the pages, particularly if it will be used by many people.</p>
<p>Tracks stores its data in a database, and you can either use SQLite3, MySQL or PostgreSQL. SQLite3 is the best choice for a single user (or a small number of users) on a local installation, while MySQL or PostgreSQL is better for multiple users on a remote installation.</p>
<h4 id="easyinstallationoptions">Easy installation options</h4>
<p>If you&#8217;d like to install Tracks on a local machine, try <a href="http://bitnami.org/stack/tracks">BitNami</a> &#8211; it runs on Windows, Mac OS X and Linux.</p>
<p>If you&#8217;d like an easy way to access Tracks from any internet-connected computer, sign up for a free account at <a href="http://www.morphexchange.com/">Morph eXchange</a>. Sign up for a free account, then choose &#8216;Subscriptions&#8217; to subscribe to the Tracks service.</p>
<h4 id="whatisincludedwiththetrackspackage">What is included with the Tracks package</h4>
<ol>
<li>Tracks itself</li>
<li>Rails 1.2.5 (installed in the <code>/vendor/rails</code> directory, so you do not need to install Rails yourself)</li>
<li>An empty SQLite3 database, set up with the correct database schema</li>
</ol>
<h4 id="whatyouneed">What you need to install</h4>
<p>If you don&#8217;t want to (or can&#8217;t) use one of the all in one installations, you&#8217;ll need to install a few things, depending on your platform and your needs.</p>
<ol>
<li><strong>Ruby</strong>. Version 1.8.6 is recommended, but it is also possible to use 1.8.5, 1.8.4 and 1.8.2. Note that 1.8.3 is not compatible. If you are running Mac OS X Leopard, you already have Ruby 1.8.6 installed by default, so you have nothing to do here. You can get the source to compile yourself <a href="http://ftp.ruby-lang.org/pub/ruby/1.8/ruby-1.8.6.tar.gz">here</a> for all platforms, or Windows users can use an easy <a href="http://rubyforge.org/frs/?group_id=167">installer</a>. If you&#8217;re using a version of Mac OS X earlier than 10.5.0, it is recommended that you use the <a href="http://hivelogic.com/narrative/articles/ruby-rails-mongrel-mysql-osx">instructions here</a> to install all the Rails dependencies, though you can skip the step to install Rails if you like.</li>
<li><strong>RubyGems</strong>. The gems needed by Rails to interact with the database have to be compiled on the platform on which they will be run, so we cannot include them with the Tracks package, unlike some other gems. So you will need to <a href="http://rubyforge.org/frs/?group_id=126">download</a> and install RubyGems (run <code>ruby setup.rb</code> after extracting the package). Note that once again, Mac OS X Leopard users get an easy life, because RubyGems and the SQLite3 gem is already installed. Once installed you can use RubyGems to install the gems you need for your database. If you are using SQLite3, run <code>sudo gem install sqlite3-ruby</code>, then select the appropriate package for your platform (version 1.2.1 recommended). You can use MySQL without installing a gem, but installing the gem can speed things up a bit: <code>sudo install gem mysql</code>. If you&#8217;re using Leopard, there are a few work-arounds necessary, which are explained on <a href="http://trac.macosforge.org/projects/ruby/wiki/Troubleshooting#IcannotbuildrubymysqlonLeopardwithmysql.combinaries">Mac OS Forge</a>. The ruby-mysql bindings can sometimes be a bit troublesome to install, so to be honest, it&#8217;s probably not worth the bother unless you are trying to wring maximum speed out of your system. If you are using PostgreSQL, then you can install a postgres gem: <code>gem install postgres</code>.</li>
<li><strong>Database</strong>. The easiest option is to use SQLite3, as the database is included in the package. All you need then is the <code>sqlite3-ruby</code> gem, as described in step 2, and the SQLite3 libraries and binary (see <a href="http://sqlite.org/download.html">sqlite.org</a> for downloads and installation instructions). If you want to use MySQL, download and install a package for your platform from <a href="http://dev.mysql.com/downloads/mysql/5.0.html">MySQL.com</a>. The basic steps for Postgresql should be similar to those for MySQL, but they will not be discussed further here.</li>
</ol>
<p>If you are using Unix, you might find <a href="http://www.cooldown.com.ar/2006/12/16/install-tracks-on-ubuntu-or-debian/">this guide</a> by c00i90wn helpful. It was written for Tracks 1.043, but it should work for Tracks 1.5.</p>
<h3 id="installation">Installation</h3>
<p>This description is intended for people installing Tracks from scratch. If you would like to upgrade an existing installation, please see <a href="#upgrading" title="Upgrading to Tracks 1.5">Upgrading to Tracks 1.5</a>.</p>
<ol>
<li><a href="#unzip_install" title="Unzip Tracks and install">Unzip tracks</a> and install in a directory</li>
<li>Decide on a <a href="#database_install" title="Decide on a database">database</a> to use
<ol><li>SQLite3 - change database.yml to point to SQLite3 database</li>
<li>MySQL - create new MySQL db and grant all privileges </li></ol></li>
<li><a href="#config_install" title="Configure variables">Configure some variables</a></li>
<li>Populate the database with the <a href="#rake_install" title="Populate your database with the Tracks 1.5 schema">Tracks 1.5 schema</a></li>
<li><a href="#startserver_install" title="Start the server">Start the server</a></li>
<li><a href="#signup_install" title="Visit Tracks in a browser">Visit Tracks in a browser</a></li>
<li><a href="#customise_install" title="Customise Tracks">Customise Tracks</a></li>
</ol>
<h4 id="unzip_install">Unzip Tracks and install</h4>
<p>Unzip the package and move Tracks into the directory you want to run it from. For example, for Mac OS X users, <code>~/Sites</code> is a good choice.</p>
<h4 id="database_install">Decide on a database</h4>
<p>Before you go any further, you need to decide which database you will use. See the <a href="#whatyouneed" title="What you need to install">What you need to install</a> section for details on installing the required components for you choice of database.</p>
<ol>
<li><strong>SQLite3</strong>. All you need to do is make sure that you point Tracks to the included SQLite3 database in <code>/db</code> in the next step, <a href="#config_install" title="Configure variables">Configure variables</a>.</li>
<li><strong>MySQL</strong>. Once you have MySQL installed, you need to create a database to use with Tracks 1.5. Go into a terminal and issue the following commands:</li>
</ol>
<pre>
<code>
mysql -uroot -p
mysql> CREATE DATABASE tracks15;
mysql> GRANT ALL PRIVILEGES ON tracks15.* TO yourmysqluser@localhost \
IDENTIFIED BY 'password-goes-here' WITH GRANT OPTION;
</code>
</pre>
<h4 id="config_install">Configure variables</h4>
<ol>
<li>If you downloaded Tracks 1.5 via Subversion, you need to duplicate the files <code>database.yml.tmpl</code> and <code>environment.yml.tmpl</code> and remove the <code>*.tmpl</code> extension from the duplicates. Similarly, duplicate <code>/log.tmpl</code> and remove the <code>*.tmpl</code> extension, then edit the files as described in steps 2 and 3.</li>
<li>Open the file <code>/config/database.yml</code> and edit the <code>production:</code> section with the details of your database. If you are using MySQL the <code>adapter:</code> line should read <code>adapter: mysql</code>, <code>host: localhost</code> (in the majority of cases), and your username and password should match those you assigned when you created the database. If you are using SQLite3, you should have only two lines under the production section: <code>adapter: sqlite3</code> and <code>database: db/tracks-15-blank.db</code>. If you downloaded the zipped file, the database.yml file is already configured to use the provided SQLite3 file.</li>
<li>Open the file <code>/config/environment.rb</code>, and read through the settings to make sure that they suit your setup. In most cases, all you need to change is the <code>SALT = "change-me"</code> line (change the string &#8220;change-me&#8221; to some other string of your choice), and the time zone setting.</li>
<li>If you are using Windows, you may need to check the &#8216;shebang&#8217; lines (<code>#!/usr/bin/env ruby</code>) of the <code>/public/dispatch.*</code> files and all the files in the <code>/script</code> directory. They are set to <code>#!/usr/bin/env ruby</code> by default. This should work for all *nix based setups (Linux or Mac OS X), but Windows users will probably have to change it to something like <code>#c:/ruby/bin/ruby</code> to point to the Ruby binary on your system.</li>
</ol>
<h4 id="rake_install">Populate your database with the Tracks 1.5 schema</h4>
<p>Open a terminal and change into the root of your Tracks 1.5 directory. Enter the following command:</p>
<p><code>rake db:migrate RAILS_ENV=production</code></p>
<p>This will update your database with the required schema for Tracks 1.5. If you are using SQLite3, it is not strictly necessary, because the SQLite3 database included with Tracks already has the schema included in it, but it should not do any harm to run the command (nothing will happen if it is up to date).</p>
<h4 id="startserver_install">Start the server</h4>
<p>While still in the Terminal inside the Tracks 1.5 root directory, issue the following command:</p>
<p><code>script/server -e production</code></p>
<p>If all goes well, you should see some text informing you that the Mongrel server is running: <code>** Mongrel available at 0.0.0.0:3000</code>. If you are already running other services on port 3000, you need to select a different port when running the server, using the <code>-p</code> option. You can stop the server again by the key combination Ctrl-C.</p>
<h4 id="signup_install">Visit Tracks in a browser</h4>
<p>Visit <code>http://0.0.0.0:3000/signup</code> in a browser (or whatever URL and port was reported when you started the server in the step above) and chose a user name and password for admin user. Once logged in as admin, you can add other (ordinary level) users. If you need to access Tracks from a mobile/cellular phone browser, visit <code>http://yourdomain.com/mobile/</code>. This mobile version is a special, lightweight version of Tracks, designed to use on a mobile browser.</p>
<h4 id="customise_install">Customise Tracks</h4>
<p>Once logged in, add some Contexts and Projects, and then go ahead and add your actions. You might also want to visit the Preferences page to edit various settings to your liking. Have fun!</p>
<h2 id="upgrading">Upgrading to Tracks 1.5</h2>
<h3 id="upgrading_1043">Upgrading from Tracks 1.043</h3>
<p>This should be a relatively straightforward, and involves the following main steps:</p>
<ol>
<li><a href="#backup_upgrade" title="Backing up">Back up</a> your existing database and installation of Tracks</li>
<li><a href="#install_upgrade" title="Install Tracks 1.5">Install Tracks 1.5</a> in a new directory</li>
<li><a href="#config_upgrade" title="Copy over old configuration files">Copy over</a> a few configuration files from your Tracks 1.043 directory. If using SQLite3, copy the old database into the new Tracks 1.5 directory</li>
<li>Run <code>rake db:migrate RAILS_ENV=production</code> to <a href="#rake_upgrade" title="Update your old database to the new format">update your old database</a> to the new schema &#8211; you did back up your database didn&#8217;t you?</li>
<li>Run <code>script/server</code> inside your Tracks 1.5 directory to <a href="#startserver_upgrade" title="Start the server">start up Tracks 1.5</a>.</li>
<li>Once you are happy that everything is working well, <a href="#cleanup_upgrade" title="Clean up your old installation">delete your old Tracks directory</a>.</li>
</ol>
<h4 id="backup_upgrade">Backing up</h4>
<p>It&#8217;s very important that you <strong>back up your database</strong> before you start the upgrade process. It&#8217;s always possible for things to go wrong with the database update, and you don&#8217;t want to lose any data. If you are using SQLite3 and you are leaving your old Tracks directory in place, then you don&#8217;t need to do anything. However, there is no harm in taking extra precautions and copying your database from <code>/db</code> to a safe location as an extra backup, or making a dump of the schema and contents. You will never regret making too many backups! If you are using MySQL, make a SQL dump of your database, replacing the terms in square brackets with the correct information for your setup:</p>
<p><code>mysqldump –-user [user name] –-password=[password] [database name] &gt; [dump file]</code></p>
<p>Rename your old Tracks installation (e.g. to &#8216;tracks-old&#8217;) so that you can install Tracks 1.5 along side it.</p>
<h4 id="install_upgrade">Install Tracks 1.5</h4>
<p>There are two methods of downloading Tracks 1.5:</p>
<ol>
<li>(Recommended for most people) Download the <a href="http://www.rousette.org.uk/projects/files/tracks-current.zip">zipped package</a>, and unzip in your preferred location (e.g. <code>~/Sites</code> for Mac OS X users).</li>
<li>Download using Subversion:</li>
</ol>
<pre>
<code>
svn co --username=guest \
http://www.rousette.org.uk/svn/tracks-repos/tags/current tracks
</code>
</pre>
<h4 id="config_upgrade">Copy over old configuration files</h4>
<p>There are a few files you need to copy over from your old installation. If you copy them over rather than moving them, you can still run your old version of Tracks if anything goes awry with the installation process.</p>
<ol>
<li>Copy <code>/config/database.yml</code> from your old Tracks directory to the same location in the new one. Double check that the information there is still correct.</li>
<li>Duplicate <code>/config/environment.rb.tmpl</code> in the Tracks 1.5 directory, and rename the file to <code>environment.rb</code>. Open the file and alter the line <code>SALT = "change-me"</code> so that it matches what you had in this file in your old installation. You may also want to change the time zone setting as appropriate for your location (<code>ENV['TZ'] = 'US/Eastern'</code>). If you have made any other customisations to <code>environment.rb</code> in the past, copy those over, but the contents of the file have changed quite a lot since 1.043, so check it carefully.</li>
<li>Copy your <code>/log</code> directory over from your old installation to the root of the new one, or just rename <code>/log.tmpl</code> to <code>log</code> to start afresh.</li>
<li>If you are using SQLite3, copy your database from <code>/db</code> in your old Tracks directory to the same location in the new one.</li>
<li>If you are using Windows, you may need to check the &#8216;shebang&#8217; lines (<code>#!/usr/bin/env ruby</code>)<a href="#fn:env" id="fnref:env" class="footnote">1</a> of the <code>/public/dispatch.*</code> files and all the files in the <code>/script</code> directory. They are set to <code>#!/usr/bin/env ruby</code> by default. Check the format of those lines in your old installation, and change the new ones as necessary.</li>
</ol>
<h4 id="rake_upgrade">Update your old database to the new format</h4>
<p>In a terminal, change directories so that you are inside the Tracks 1.5 directory. Then issue the command to update your Tracks 1.043 database to the format required for Tracks 1.5:</p>
<p><code>rake db:migrate RAILS_ENV=production</code></p>
<p>Watch the output carefully for errors, but it should report at the end of the process that everything worked OK. If you do get errors, you&#8217;ll have to fix them before you proceed any further. Running rake with the <code>--trace</code> option can help to track down the problem.</p>
<h4 id="startserver_upgrade">Start the server</h4>
<p>If you&#8217;re still in the Tracks 1.5 root directory in a terminal, enter the following command to start up Tracks in production mode:</p>
<p><code>script/server -e production</code></p>
<p>Visit the URL indicated by the output (e.g. <code>** Mongrel available at 0.0.0.0:3000</code>
) in a browser, and with any luck, you should be able to log in and find all your actions as you left them! If you need to access Tracks from a mobile/cellular phone browser, visit <code>http://yourdomain.com/mobile/</code>. This mobile version is a special, lightweight version of Tracks, designed to use on a mobile browser.</p>
<h4 id="cleanup_upgrade">Clean up your old installation</h4>
<p>Once you&#8217;re certain that your new Tracks 1.5 installation is working perfectly, you can delete your old Tracks directory.</p>
<h3 id="upgradingfromversionspriorto1.043">Upgrading from versions prior to 1.043</h3>
<p>The best option for versions prior to 1.043 is to follow the instructions below to upgrade to version 1.043, then use the instructions above to <a href="#upgrading_1043" title="Upgrading from Tracks 1.043">upgrade from version 1.043</a>.</p>
<ol>
<li>For safety, rename your current Tracks directory to &#8216;tracks-old&#8217; or something similar.</li>
<li>Before you do anything else, <strong>BACK UP YOUR DATABASE</strong> (tables and content) and keep the SQL dumps somewhere safe so that you can recreate the old database if necesary.</li>
<li>Download a copy of Tracks 1.043 and unzip alongside your &#8216;tracks-old&#8217; directory.</li>
<li>Open the file <code>config/environment.rb</code> and look at the last line which should read: <code>SALT = "change-me"</code>. Change the word change-me to something else of your choosing. This string will be used as a &#8216;salt&#8217; to encrypt your password and make it a bit more secure. Also look at the timezone setting at the bottom. You can leave it commented out if your server is in the same time zone as you, but you may need to adjust it if your server is in a different time zone.</li>
<li>In <code>database.yml</code> insert your old database name, user and password under the &#8216;development&#8217; section. If you are using SQLite3 rather than MySQL or PostgreSQL, you need only the database name, and to change the &#8216;adapter&#8217; line to &#8216;sqlite3&#8217;. You also need to copy (NOT MOVE!), your SQLite3 database from your tracks-old <code>db</code> directory to your new tracks <code>db</code> directory</li>
<li>Run the command <code>rake extract_fixtures</code> inside the Tracks directory. This will populate the <code>db/exported_fixtures</code> directory with <code>*.yml</code> files corresponding to the contexts, projects and todos table from the contents of your old database.</li>
<li>Open <code>db/exported_fixtures/todos.yml</code> and search for the lines starting <code>created:</code> and replace with <code>created_at:</code>. If you are using SQLite3, you also need to change the following: <code>done: "0"</code> with <code>done: "f"</code> and <code>done: "1"</code> with <code>done: "t"</code>. You need to replace the similar &#8216;done&#8217; lines in <code>projects.yml</code>, and in <code>contexts.yml</code> replace <code>hide: "0"</code> with <code>hide: "f"</code> and <code>hide: "1"</code> with <code>hide: "t"</code>.</li>
<li>Create a new MySQL database (named tracks1043, for example). In <code>database.yml</code> insert this new database name, user and password under the &#8216;development&#8217; and &#8216;production&#8217; sections. If you are using SQLite3, insert a new name for a database to hold your Tracks 1.043 data.</li>
<li>Run the command <code>rake db_schema_import</code> inside the Tracks directory. This should import the upgraded schema for 1.043 into your new database.</li>
<li>Run the command <code>rake load_exported_fixtures</code> which will import the contents of your old database from the fixtures files in <code>db/exported_fixtures</code>.</li>
<li>If you are using Windows, you may need to check the &#8216;shebang&#8217; lines (<code>#!/usr/bin/env ruby</code>)<a href="#fn:env" id="fnref:env" class="footnote">2</a> of the <code>/public/dispatch.*</code> files and all the files in the <code>/script</code> directory. They are set to <code>#!/usr/bin/env ruby</code> by default. Check the format of those lines in your old installation, and change the new ones as necessary.</li>
<li>Try starting up the server with <code>script/server</code> to make sure that all your data has migrated successfully. If all is well, follow the instructions above to <a href="#upgrading_1043" title="Upgrading from Tracks 1.043">upgrade from version 1.043</a> to Tracks 1.5. If you need to access Tracks from a mobile/cellular phone browser, visit <code>http://yourdomain.com/mobile/</code>. This mobile version is a special, lightweight version of Tracks, designed to use on a mobile browser.</li>
</ol>
<div class="footnotes">
<hr />
<ol>
<li id="fn:env"><p>The <code>env</code> binary helps to locate other binaries, regardless of their location. If you don&#8217;t have <code>env</code> installed, you&#8217;ll need to change this line to point to the location of your Ruby binary.<a href="#fnref:env" class="reversefootnote">&#160;&#8617;</a></p></li>
<li id="fn:env"><p>The <code>env</code> binary helps to locate other binaries, regardless of their location. If you don&#8217;t have <code>env</code> installed, you&#8217;ll need to change this line to point to the location of your Ruby binary.<a href="#fnref:env" class="reversefootnote">&#160;&#8617;</a></p></li>
</ol>
</div>
</body>
</html>

208
doc/manual.markdown Normal file
View file

@ -0,0 +1,208 @@
Title: Tracks 1.5 Manual
Author: Tracks Development Team
Date: 2008-04-07
Revision: $Id: manual.markdown 811 2008-04-07 20:21:00Z bsag $
Version: 1.5
Copyright: 2008 rousette.org.uk
This work is licensed under a Creative Commons License.
http://creativecommons.org/licenses/by-nc-sa/3.0/
XMP: CCAttributionShareAlike
Format: complete
Base Header Level: 2
LaTeX XSLT: memoir-twosided-manual.xslt
CSS: manual.css
<!-- The HTML file manual.html is generated from manual.markdown, so make edits to the *.markdown file -->
# Installing Tracks 1.5 #
## Introduction ##
Tracks 1.5 has been thoroughly beta tested by a large number of people, and should be fully stable for everyday use. However, once set up, Tracks will contain the majority of your plans for your work and personal life, so it's only sensible to make sure that you have frequent, reliable backups of your data. Full changenotes on the release can be found in `doc/CHANGELOG`. Full API documentation can be found at `doc/app/index.html`, once you have run `rake appdoc`
There are two methods of downloading Tracks 1.5 **(N.B. These links will not work until Tracks 1.5 final is released)**):
1. (Recommended for most people) Download the [zipped package](http://www.rousette.org.uk/projects/files/tracks-current.zip), and unzip in your preferred location (e.g. `~/Sites` for Mac OS X users).
2. Download using Subversion:
<pre>
<code>
svn co --username=guest
http://www.rousette.org.uk/svn/tracks-repos/tags/current tracks
</code>
</pre>
## Requirements ##
The Tracks interface is accessed through a web browser, so you need to run a webserver to serve the Tracks pages up to you. This isn't as daunting as it sounds, however: Tracks ships with a built-in web server called Mongrel which you can run on your own computer to serve the Tracks application locally. If you want to be able to access Tracks from any computer connected to the Internet, then you need to install Tracks on a publicly accessible server, and you will probably be better off using a more robust server such as [Apache](http://www.apache.org/) or [Lighttpd](http://www.lighttpd.net/) to serve the pages, particularly if it will be used by many people.
Tracks stores its data in a database, and you can either use SQLite3, MySQL or PostgreSQL. SQLite3 is the best choice for a single user (or a small number of users) on a local installation, while MySQL or PostgreSQL is better for multiple users on a remote installation.
### Easy installation options ###
If you'd like to install Tracks on a local machine, try [BitNami](http://bitnami.org/stack/tracks) -- it runs on Windows, Mac OS X and Linux.
If you'd like an easy way to access Tracks from any internet-connected computer, sign up for a free account at [Morph eXchange](http://www.morphexchange.com/). Sign up for a free account, then choose 'Subscriptions' to subscribe to the Tracks service.
### What is included with the Tracks package ###
1. Tracks itself
2. Rails 1.2.5 (installed in the `/vendor/rails` directory, so you do not need to install Rails yourself)
3. An empty SQLite3 database, set up with the correct database schema
### What you need to install [whatyouneed] ###
If you don't want to (or can't) use one of the all in one installations, you'll need to install a few things, depending on your platform and your needs.
1. **Ruby**. Version 1.8.6 is recommended, but it is also possible to use 1.8.5, 1.8.4 and 1.8.2. Note that 1.8.3 is not compatible. If you are running Mac OS X Leopard, you already have Ruby 1.8.6 installed by default, so you have nothing to do here. You can get the source to compile yourself [here](http://ftp.ruby-lang.org/pub/ruby/1.8/ruby-1.8.6.tar.gz) for all platforms, or Windows users can use an easy [installer](http://rubyforge.org/frs/?group_id=167). If you're using a version of Mac OS X earlier than 10.5.0, it is recommended that you use the [instructions here](http://hivelogic.com/narrative/articles/ruby-rails-mongrel-mysql-osx) to install all the Rails dependencies, though you can skip the step to install Rails if you like.
2. **RubyGems**. The gems needed by Rails to interact with the database have to be compiled on the platform on which they will be run, so we cannot include them with the Tracks package, unlike some other gems. So you will need to [download](http://rubyforge.org/frs/?group_id=126) and install RubyGems (run `ruby setup.rb` after extracting the package). Note that once again, Mac OS X Leopard users get an easy life, because RubyGems and the SQLite3 gem is already installed. Once installed you can use RubyGems to install the gems you need for your database. If you are using SQLite3, run `sudo gem install sqlite3-ruby`, then select the appropriate package for your platform (version 1.2.1 recommended). You can use MySQL without installing a gem, but installing the gem can speed things up a bit: `sudo install gem mysql`. If you're using Leopard, there are a few work-arounds necessary, which are explained on [Mac OS Forge](http://trac.macosforge.org/projects/ruby/wiki/Troubleshooting#IcannotbuildrubymysqlonLeopardwithmysql.combinaries). The ruby-mysql bindings can sometimes be a bit troublesome to install, so to be honest, it's probably not worth the bother unless you are trying to wring maximum speed out of your system. If you are using PostgreSQL, then you can install a postgres gem: `gem install postgres`.
3. **Database**. The easiest option is to use SQLite3, as the database is included in the package. All you need then is the `sqlite3-ruby` gem, as described in step 2, and the SQLite3 libraries and binary (see [sqlite.org](http://sqlite.org/download.html) for downloads and installation instructions). If you want to use MySQL, download and install a package for your platform from [MySQL.com](http://dev.mysql.com/downloads/mysql/5.0.html). The basic steps for Postgresql should be similar to those for MySQL, but they will not be discussed further here.
If you are using Unix, you might find [this guide](http://www.cooldown.com.ar/2006/12/16/install-tracks-on-ubuntu-or-debian/) by c00i90wn helpful. It was written for Tracks 1.043, but it should work for Tracks 1.5.
## Installation ##
This description is intended for people installing Tracks from scratch. If you would like to upgrade an existing installation, please see [Upgrading to Tracks 1.5][upgrading].
1. [Unzip tracks][unzip_install] and install in a directory
2. Decide on a [database][database_install] to use
1. SQLite3 - change database.yml to point to SQLite3 database
2. MySQL - create new MySQL db and grant all privileges
3. [Configure some variables][config_install]
4. Populate the database with the [Tracks 1.5 schema][rake_install]
5. [Start the server][startserver_install]
6. [Visit Tracks in a browser][signup_install]
7. [Customise Tracks][customise_install]
### Unzip Tracks and install [unzip_install] ###
Unzip the package and move Tracks into the directory you want to run it from. For example, for Mac OS X users, `~/Sites` is a good choice.
### Decide on a database [database_install] ###
Before you go any further, you need to decide which database you will use. See the [What you need to install][whatyouneed] section for details on installing the required components for you choice of database.
1. **SQLite3**. All you need to do is make sure that you point Tracks to the included SQLite3 database in `/db` in the next step, [Configure variables][config_install].
2. **MySQL**. Once you have MySQL installed, you need to create a database to use with Tracks 1.5. Go into a terminal and issue the following commands:
<pre>
<code>
mysql -uroot -p
mysql> CREATE DATABASE tracks15;
mysql> GRANT ALL PRIVILEGES ON tracks15.* TO yourmysqluser@localhost \
IDENTIFIED BY 'password-goes-here' WITH GRANT OPTION;
</code>
</pre>
### Configure variables [config_install] ###
1. If you downloaded Tracks 1.5 via Subversion, you need to duplicate the files `database.yml.tmpl` and `environment.yml.tmpl` and remove the `*.tmpl` extension from the duplicates. Similarly, duplicate `/log.tmpl` and remove the `*.tmpl` extension, then edit the files as described in steps 2 and 3.
2. Open the file `/config/database.yml` and edit the `production:` section with the details of your database. If you are using MySQL the `adapter:` line should read `adapter: mysql`, `host: localhost` (in the majority of cases), and your username and password should match those you assigned when you created the database. If you are using SQLite3, you should have only two lines under the production section: `adapter: sqlite3` and `database: db/tracks-15-blank.db`. If you downloaded the zipped file, the database.yml file is already configured to use the provided SQLite3 file.
3. Open the file `/config/environment.rb`, and read through the settings to make sure that they suit your setup. In most cases, all you need to change is the `SALT = "change-me"` line (change the string "change-me" to some other string of your choice), and the time zone setting.
4. If you are using Windows, you may need to check the 'shebang' lines (`#!/usr/bin/env ruby`) of the `/public/dispatch.*` files and all the files in the `/script` directory. They are set to `#!/usr/bin/env ruby` by default. This should work for all *nix based setups (Linux or Mac OS X), but Windows users will probably have to change it to something like `#c:/ruby/bin/ruby` to point to the Ruby binary on your system.
### Populate your database with the Tracks 1.5 schema [rake_install] ###
Open a terminal and change into the root of your Tracks 1.5 directory. Enter the following command:
`rake db:migrate RAILS_ENV=production`
This will update your database with the required schema for Tracks 1.5. If you are using SQLite3, it is not strictly necessary, because the SQLite3 database included with Tracks already has the schema included in it, but it should not do any harm to run the command (nothing will happen if it is up to date).
### Start the server [startserver_install] ###
While still in the Terminal inside the Tracks 1.5 root directory, issue the following command:
`script/server -e production`
If all goes well, you should see some text informing you that the Mongrel server is running: `** Mongrel available at 0.0.0.0:3000`. If you are already running other services on port 3000, you need to select a different port when running the server, using the `-p` option. You can stop the server again by the key combination Ctrl-C.
### Visit Tracks in a browser [signup_install] ###
Visit `http://0.0.0.0:3000/signup` in a browser (or whatever URL and port was reported when you started the server in the step above) and chose a user name and password for admin user. Once logged in as admin, you can add other (ordinary level) users. If you need to access Tracks from a mobile/cellular phone browser, visit `http://yourdomain.com/mobile/`. This mobile version is a special, lightweight version of Tracks, designed to use on a mobile browser.
### Customise Tracks [customise_install] ###
Once logged in, add some Contexts and Projects, and then go ahead and add your actions. You might also want to visit the Preferences page to edit various settings to your liking. Have fun!
# Upgrading to Tracks 1.5 [upgrading] #
## Upgrading from Tracks 1.043 [upgrading_1043] ##
This should be a relatively straightforward, and involves the following main steps:
1. [Back up][backup_upgrade] your existing database and installation of Tracks
2. [Install Tracks 1.5][install_upgrade] in a new directory
3. [Copy over][config_upgrade] a few configuration files from your Tracks 1.043 directory. If using SQLite3, copy the old database into the new Tracks 1.5 directory
5. Run `rake db:migrate RAILS_ENV=production` to [update your old database][rake_upgrade] to the new schema -- you did back up your database didn't you?
6. Run `script/server` inside your Tracks 1.5 directory to [start up Tracks 1.5][startserver_upgrade].
7. Once you are happy that everything is working well, [delete your old Tracks directory][cleanup_upgrade].
### Backing up [backup_upgrade] ###
It's very important that you **back up your database** before you start the upgrade process. It's always possible for things to go wrong with the database update, and you don't want to lose any data. If you are using SQLite3 and you are leaving your old Tracks directory in place, then you don't need to do anything. However, there is no harm in taking extra precautions and copying your database from `/db` to a safe location as an extra backup, or making a dump of the schema and contents. You will never regret making too many backups! If you are using MySQL, make a SQL dump of your database, replacing the terms in square brackets with the correct information for your setup:
`mysqldump –-user [user name] –-password=[password] [database name] > [dump file]`
Rename your old Tracks installation (e.g. to 'tracks-old') so that you can install Tracks 1.5 along side it.
### Install Tracks 1.5 [install_upgrade] ###
There are two methods of downloading Tracks 1.5:
1. (Recommended for most people) Download the [zipped package](http://www.rousette.org.uk/projects/files/tracks-current.zip), and unzip in your preferred location (e.g. `~/Sites` for Mac OS X users).
2. Download using Subversion:
<pre>
<code>
svn co --username=guest \
http://www.rousette.org.uk/svn/tracks-repos/tags/current tracks
</code>
</pre>
### Copy over old configuration files [config_upgrade] ###
There are a few files you need to copy over from your old installation. If you copy them over rather than moving them, you can still run your old version of Tracks if anything goes awry with the installation process.
1. Copy `/config/database.yml` from your old Tracks directory to the same location in the new one. Double check that the information there is still correct.
2. Duplicate `/config/environment.rb.tmpl` in the Tracks 1.5 directory, and rename the file to `environment.rb`. Open the file and alter the line `SALT = "change-me"` so that it matches what you had in this file in your old installation. You may also want to change the time zone setting as appropriate for your location (`ENV['TZ'] = 'US/Eastern'`). If you have made any other customisations to `environment.rb` in the past, copy those over, but the contents of the file have changed quite a lot since 1.043, so check it carefully.
3. Copy your `/log` directory over from your old installation to the root of the new one, or just rename `/log.tmpl` to `log` to start afresh.
4. If you are using SQLite3, copy your database from `/db` in your old Tracks directory to the same location in the new one.
5. If you are using Windows, you may need to check the 'shebang' lines (`#!/usr/bin/env ruby`)[^env] of the `/public/dispatch.*` files and all the files in the `/script` directory. They are set to `#!/usr/bin/env ruby` by default. Check the format of those lines in your old installation, and change the new ones as necessary.
### Update your old database to the new format [rake_upgrade] ###
In a terminal, change directories so that you are inside the Tracks 1.5 directory. Then issue the command to update your Tracks 1.043 database to the format required for Tracks 1.5:
`rake db:migrate RAILS_ENV=production`
Watch the output carefully for errors, but it should report at the end of the process that everything worked OK. If you do get errors, you'll have to fix them before you proceed any further. Running rake with the `--trace` option can help to track down the problem.
### Start the server [startserver_upgrade] ###
If you're still in the Tracks 1.5 root directory in a terminal, enter the following command to start up Tracks in production mode:
`script/server -e production`
Visit the URL indicated by the output (e.g. `** Mongrel available at 0.0.0.0:3000`
) in a browser, and with any luck, you should be able to log in and find all your actions as you left them! If you need to access Tracks from a mobile/cellular phone browser, visit `http://yourdomain.com/mobile/`. This mobile version is a special, lightweight version of Tracks, designed to use on a mobile browser.
### Clean up your old installation [cleanup_upgrade] ###
Once you're certain that your new Tracks 1.5 installation is working perfectly, you can delete your old Tracks directory.
[^env]: The `env` binary helps to locate other binaries, regardless of their location. If you don't have `env` installed, you'll need to change this line to point to the location of your Ruby binary.
## Upgrading from versions prior to 1.043 ##
The best option for versions prior to 1.043 is to follow the instructions below to upgrade to version 1.043, then use the instructions above to [upgrade from version 1.043][upgrading_1043].
1. For safety, rename your current Tracks directory to 'tracks-old' or something similar.
2. Before you do anything else, **BACK UP YOUR DATABASE** (tables and content) and keep the SQL dumps somewhere safe so that you can recreate the old database if necesary.
3. Download a copy of Tracks 1.043 and unzip alongside your 'tracks-old' directory.
4. Open the file `config/environment.rb` and look at the last line which should read: `SALT = "change-me"`. Change the word change-me to something else of your choosing. This string will be used as a 'salt' to encrypt your password and make it a bit more secure. Also look at the timezone setting at the bottom. You can leave it commented out if your server is in the same time zone as you, but you may need to adjust it if your server is in a different time zone.
5. In `database.yml` insert your old database name, user and password under the 'development' section. If you are using SQLite3 rather than MySQL or PostgreSQL, you need only the database name, and to change the 'adapter' line to 'sqlite3'. You also need to copy (NOT MOVE!), your SQLite3 database from your tracks-old `db` directory to your new tracks `db` directory
6. Run the command `rake extract_fixtures` inside the Tracks directory. This will populate the `db/exported_fixtures` directory with `*.yml` files corresponding to the contexts, projects and todos table from the contents of your old database.
7. Open `db/exported_fixtures/todos.yml` and search for the lines starting `created:` and replace with `created_at:`. If you are using SQLite3, you also need to change the following: `done: "0"` with `done: "f"` and `done: "1"` with `done: "t"`. You need to replace the similar 'done' lines in `projects.yml`, and in `contexts.yml` replace `hide: "0"` with `hide: "f"` and `hide: "1"` with `hide: "t"`.
8. Create a new MySQL database (named tracks1043, for example). In `database.yml` insert this new database name, user and password under the 'development' and 'production' sections. If you are using SQLite3, insert a new name for a database to hold your Tracks 1.043 data.
9. Run the command `rake db_schema_import` inside the Tracks directory. This should import the upgraded schema for 1.043 into your new database.
10. Run the command `rake load_exported_fixtures` which will import the contents of your old database from the fixtures files in `db/exported_fixtures`.
11. If you are using Windows, you may need to check the 'shebang' lines (`#!/usr/bin/env ruby`)[^env] of the `/public/dispatch.*` files and all the files in the `/script` directory. They are set to `#!/usr/bin/env ruby` by default. Check the format of those lines in your old installation, and change the new ones as necessary.
12. Try starting up the server with `script/server` to make sure that all your data has migrated successfully. If all is well, follow the instructions above to [upgrade from version 1.043][upgrading_1043] to Tracks 1.5. If you need to access Tracks from a mobile/cellular phone browser, visit `http://yourdomain.com/mobile/`. This mobile version is a special, lightweight version of Tracks, designed to use on a mobile browser.

BIN
doc/manual.pdf Normal file
View file

Binary file not shown.

620
doc/manual.tex Normal file
View file

@ -0,0 +1,620 @@
\documentclass[10pt,twoside]{memoir}
\usepackage{layouts}[2001/04/29]
\usepackage{palatino}
\usepackage{color,calc}
\newsavebox{\ChpNumBox}
\definecolor{ChapBlue}{rgb}{0.00,0.65,0.65}
\makeatletter
\newcommand*{\thickhrulefill}{%
\leavevmode\leaders\hrule height 1\p@ \hfill \kern \z@}
\newcommand*\BuildChpNum[2]{%
\begin{tabular}[t]{@{}c@{}}
\makebox[0pt][c]{#1\strut} \\[.5ex]
\colorbox{ChapBlue}{%
\rule[-10em]{0pt}{0pt}%
\rule{1ex}{0pt}\color{black}#2\strut
\rule{1ex}{0pt}}%
\end{tabular}}
\makechapterstyle{BlueBox}{%
\renewcommand{\chapnamefont}{\large\scshape}
\renewcommand{\chapnumfont}{\Huge\bfseries}
\renewcommand{\chaptitlefont}{\raggedright\Huge\bfseries}
\setlength{\beforechapskip}{20pt}
\setlength{\midchapskip}{26pt}
\setlength{\afterchapskip}{40pt}
\renewcommand{\printchaptername}{}
\renewcommand{\chapternamenum}{}
\renewcommand{\printchapternum}{%
\sbox{\ChpNumBox}{%
\BuildChpNum{\chapnamefont\@chapapp}%
{\chapnumfont\thechapter}}}
\renewcommand{\printchapternonum}{%
\sbox{\ChpNumBox}{%
\BuildChpNum{\chapnamefont\vphantom{\@chapapp}}%
{\chapnumfont\hphantom{\thechapter}}}}
\renewcommand{\afterchapternum}{}
\renewcommand{\printchaptertitle}[1]{%
\usebox{\ChpNumBox}\hfill
\parbox[t]{\hsize-\wd\ChpNumBox-1em}{%
\vspace{\midchapskip}%
\thickhrulefill\par
\chaptitlefont ##1\par}}%
}
\chapterstyle{BlueBox}
\setsecheadstyle{\sffamily\bfseries\Large}
\setsubsecheadstyle{\sffamily\bfseries\normal}
\makepagestyle{myruledpagestyle}
\makeevenhead{myruledpagestyle}{\thepage}{}{\leftmark}
\makeoddhead{myruledpagestyle}{\rightmark}{}{\thepage}
\makeatletter
\makepsmarks{myruledpagestyle}{
\def\chaptermark##1{\markboth{%
\ifnum \value{secnumdepth} > -1
\if@mainmatter
\chaptername\ \thechapter\ --- %
\fi
\fi
##1}{}}
\def\sectionmark##1{\markright{%
\ifnum \value{secnumdepth} > 0
\thesection. \ %
\fi
##1}}
}
\makeatother
\makerunningwidth{myruledpagestyle}{1.1\textwidth}
\makeheadposition{myruledpagestyle}{flushright}{flushleft}{flushright}{flushleft}
\makeheadrule{myruledpagestyle}{1.1\textwidth}{\normalrulethickness}
\makeglossary
\makeindex
\def\mychapterstyle{BlueBox}
\def\mypagestyle{myruledpagestyle}
\def\revision{}
%%% need more space for ToC page numbers
\setpnumwidth{2.55em}
\setrmarg{3.55em}
%%% need more space for ToC section numbers
\cftsetindents{part}{0em}{3em}
\cftsetindents{chapter}{0em}{3em}
\cftsetindents{section}{3em}{3em}
\cftsetindents{subsection}{4.5em}{3.9em}
\cftsetindents{subsubsection}{8.4em}{4.8em}
\cftsetindents{paragraph}{10.7em}{5.7em}
\cftsetindents{subparagraph}{12.7em}{6.7em}
%%% need more space for LoF numbers
\cftsetindents{figure}{0em}{3.0em}
%%% and do the same for the LoT
\cftsetindents{table}{0em}{3.0em}
%%% set up the page layout
\settrimmedsize{\stockheight}{\stockwidth}{*} % Use entire page
\settrims{0pt}{0pt}
\setlrmarginsandblock{1.5in}{1.5in}{*}
\setulmarginsandblock{1.5in}{1.5in}{*}
\setmarginnotes{17pt}{51pt}{\onelineskip}
\setheadfoot{\onelineskip}{2\onelineskip}
\setheaderspaces{*}{2\onelineskip}{*}
\checkandfixthelayout
\usepackage{fancyvrb} % Allow \verbatim et al. in footnotes
\usepackage{graphicx} % To include graphics in pdf's (jpg, gif, png, etc)
\usepackage{booktabs} % Better tables
\usepackage{tabulary} % Support longer table cells
\usepackage[utf8]{inputenc} % For UTF-8 support
% \usepackage{xcolor} % Allow for color (annotations)
%\geometry{landscape} % Activate for rotated page geometry
% \usepackage[parfill]{parskip} % Activate to begin paragraphs with an empty
% line rather than an indent
\def\myauthor{Author} % In case these were not included in metadata
\def\mytitle{Title}
\def\mykeywords{}
\def\mybibliostyle{plain}
\def\bibliocommand{}
\VerbatimFootnotes
\def\myauthor{Tracks Development Team}
\def\baseheaderlevel{2}
\def\mycopyright{2008 rousette.org.uk \\ This work is licensed under a Creative Commons License. \\ http://creativecommons.org/licenses/by-nc-sa/3.0/}
\date{2008-04-07}
\def\format{complete}
\def\latexxslt{memoir-twosided-manual.xslt}
\def\revision{Revision: \$Id: manual.markdown 811 2008-04-07 20:21:00Z bsag \$}
\def\mytitle{Tracks 1.5 Manual}
\def\version{1.5}
\usepackage{xmpincl}
\includexmp{CCAttributionShareAlike}
%
% PDF Stuff
%
%\ifpdf % Removed for XeLaTeX compatibility
% \pdfoutput=1 % Removed for XeLaTeX compatibility
\usepackage[
plainpages=false,
pdfpagelabels,
pdftitle={\mytitle},
pagebackref,
pdfauthor={\myauthor},
pdfkeywords={\mykeywords},
colorlinks=true,
urlcolor=blue,
linkcolor=red
]{hyperref}
\usepackage{memhfixc}
%\fi % Removed for XeLaTeX compatibility
%
% Title Information
%
\ifx\subtitle\undefined
\else
\addtodef{\mytitle}{}{ \\ \subtitle}
\fi
\ifx\affiliation\undefined
\else
\addtodef{\myauthor}{}{ \\ \affiliation}
\fi
\ifx\address\undefined
\else
\addtodef{\myauthor}{}{ \\ \address}
\fi
\ifx\phone\undefined
\else
\addtodef{\myauthor}{}{ \\ \phone}
\fi
\ifx\email\undefined
\else
\addtodef{\myauthor}{}{ \\ \email}
\fi
\ifx\web\undefined
\else
\addtodef{\myauthor}{}{ \\ \web}
\fi
\title{\mytitle}
\author{\myauthor}
\maxsecnumdepth{subsection}
\setsecnumdepth{subsection}
\begin{document}
\chapterstyle{\mychapterstyle}
\pagestyle{\mypagestyle}
%
% Front Matter
%
\frontmatter
% Title Page
\maketitle
\clearpage
% Copyright Page
\vspace*{\fill}
\setlength{\parindent}{0pt}
\ifx\mycopyright\undefined
\else
\textcopyright{} \mycopyright
\fi
\revision
\begin{center}
\framebox{ \parbox[t]{1.5in}{\centering Formatted for \LaTeX \\
by MultiMarkdown}}
\end{center}
\setlength{\parindent}{1em}
\clearpage
% Table of Contents
\tableofcontents
%\listoffigures % activate to include a List of Figures
%\listoftables % activate to include a List of Tables
%
% Main Content
%
% Layout settings
\setlength{\parindent}{0pt}
\setlength{\parskip}{\baselineskip/2}
\mainmatter
\chapter{Installing Tracks 1.5}
\label{installingtracks1.5}
\section{Introduction}
\label{introduction}
Tracks 1.5 has been thoroughly beta tested by a large number of people, and should be fully stable for everyday use. However, once set up, Tracks will contain the majority of your plans for your work and personal life, so it's only sensible to make sure that you have frequent, reliable backups of your data. Full changenotes on the release can be found in \texttt{doc/CHANGELOG}. Full API documentation can be found at \texttt{doc/app/index.html}, once you have run \texttt{rake appdoc}
There are two methods of downloading Tracks 1.5 \textbf{(N.B. These links will not work until Tracks 1.5 final is released)}):
\begin{enumerate}
\item (Recommended for most people) Download the \href{http://www.rousette.org.uk/projects/files/tracks-current.zip}{zipped package}, and unzip in your preferred location (e.g.\ \texttt{\ensuremath{\sim}/Sites} for Mac OS X users).
\item Download using Subversion:
\end{enumerate}
\begin{adjustwidth}{2.5em}{2.5em}
\begin{verbatim}
svn co --username=guest
http://www.rousette.org.uk/svn/tracks-repos/tags/current tracks
\end{verbatim}
\end{adjustwidth}
\section{Requirements}
\label{requirements}
The Tracks interface is accessed through a web browser, so you need to run a webserver to serve the Tracks pages up to you. This isn't as daunting as it sounds, however: Tracks ships with a built-in web server called Mongrel which you can run on your own computer to serve the Tracks application locally. If you want to be able to access Tracks from any computer connected to the Internet, then you need to install Tracks on a publicly accessible server, and you will probably be better off using a more robust server such as \href{http://www.apache.org/}{Apache} or \href{http://www.lighttpd.net/}{Lighttpd} to serve the pages, particularly if it will be used by many people.
Tracks stores its data in a database, and you can either use SQLite3, MySQL or PostgreSQL. SQLite3 is the best choice for a single user (or a small number of users) on a local installation, while MySQL or PostgreSQL is better for multiple users on a remote installation.
\subsection{Easy installation options}
\label{easyinstallationoptions}
If you'd like to install Tracks on a local machine, try \href{http://bitnami.org/stack/tracks}{BitNami} -- it runs on Windows, Mac OS X and Linux.
If you'd like an easy way to access Tracks from any internet-connected computer, sign up for a free account at \href{http://www.morphexchange.com/}{Morph eXchange}. Sign up for a free account, then choose `Subscriptions' to subscribe to the Tracks service.
\subsection{What is included with the Tracks package}
\label{whatisincludedwiththetrackspackage}
\begin{enumerate}
\item Tracks itself
\item Rails 1.2.5 (installed in the \texttt{/vendor/rails} directory, so you do not need to install Rails yourself)
\item An empty SQLite3 database, set up with the correct database schema
\end{enumerate}
\subsection{What you need to install}
\label{whatyouneed}
If you don't want to (or can't) use one of the all in one installations, you'll need to install a few things, depending on your platform and your needs.
\begin{enumerate}
\item \textbf{Ruby}. Version 1.8.6 is recommended, but it is also possible to use 1.8.5, 1.8.4 and 1.8.2. Note that 1.8.3 is not compatible. If you are running Mac OS X Leopard, you already have Ruby 1.8.6 installed by default, so you have nothing to do here. You can get the source to compile yourself \href{http://ftp.ruby-lang.org/pub/ruby/1.8/ruby-1.8.6.tar.gz}{here} for all platforms, or Windows users can use an easy \href{http://rubyforge.org/frs/?group_id=167}{installer}. If you're using a version of Mac OS X earlier than 10.5.0, it is recommended that you use the \href{http://hivelogic.com/narrative/articles/ruby-rails-mongrel-mysql-osx}{instructions here} to install all the Rails dependencies, though you can skip the step to install Rails if you like.
\item \textbf{RubyGems}. The gems needed by Rails to interact with the database have to be compiled on the platform on which they will be run, so we cannot include them with the Tracks package, unlike some other gems. So you will need to \href{http://rubyforge.org/frs/?group_id=126}{download} and install RubyGems (run \texttt{ruby setup.rb} after extracting the package). Note that once again, Mac OS X Leopard users get an easy life, because RubyGems and the SQLite3 gem is already installed. Once installed you can use RubyGems to install the gems you need for your database. If you are using SQLite3, run \texttt{sudo gem install sqlite3-ruby}, then select the appropriate package for your platform (version 1.2.1 recommended). You can use MySQL without installing a gem, but installing the gem can speed things up a bit: \texttt{sudo install gem mysql}. If you're using Leopard, there are a few work-arounds necessary, which are explained on \href{http://trac.macosforge.org/projects/ruby/wiki/Troubleshooting#IcannotbuildrubymysqlonLeopardwithmysql.combinaries}{Mac OS Forge}. The ruby-mysql bindings can sometimes be a bit troublesome to install, so to be honest, it's probably not worth the bother unless you are trying to wring maximum speed out of your system. If you are using PostgreSQL, then you can install a postgres gem: \texttt{gem install postgres}.
\item \textbf{Database}. The easiest option is to use SQLite3, as the database is included in the package. All you need then is the \texttt{sqlite3-ruby} gem, as described in step 2, and the SQLite3 libraries and binary (see \href{http://sqlite.org/download.html}{sqlite.org} for downloads and installation instructions). If you want to use MySQL, download and install a package for your platform from \href{http://dev.mysql.com/downloads/mysql/5.0.html}{MySQL.com}. The basic steps for Postgresql should be similar to those for MySQL, but they will not be discussed further here.
\end{enumerate}
If you are using Unix, you might find \href{http://www.cooldown.com.ar/2006/12/16/install-tracks-on-ubuntu-or-debian/}{this guide} by c00i90wn helpful. It was written for Tracks 1.043, but it should work for Tracks 1.5.
\section{Installation}
\label{installation}
This description is intended for people installing Tracks from scratch. If you would like to upgrade an existing installation, please see Upgrading to Tracks 1.5 (\autoref{upgrading}).
\begin{enumerate}
\item Unzip tracks (\autoref{unzip_install}) and install in a directory
\item Decide on a database (\autoref{database_install}) to use
\begin{enumerate}
\item SQLite3 - change database.yml to point to SQLite3 database
\item MySQL - create new MySQL db and grant all privileges
\end{enumerate}
\item Configure some variables (\autoref{config_install})
\item Populate the database with the Tracks 1.5 schema (\autoref{rake_install})
\item Start the server (\autoref{startserver_install})
\item Visit Tracks in a browser (\autoref{signup_install})
\item Customise Tracks (\autoref{customise_install})
\end{enumerate}
\subsection{Unzip Tracks and install}
\label{unzip_install}
Unzip the package and move Tracks into the directory you want to run it from. For example, for Mac OS X users, \texttt{\ensuremath{\sim}/Sites} is a good choice.
\subsection{Decide on a database}
\label{database_install}
Before you go any further, you need to decide which database you will use. See the What you need to install (\autoref{whatyouneed}) section for details on installing the required components for you choice of database.
\begin{enumerate}
\item \textbf{SQLite3}. All you need to do is make sure that you point Tracks to the included SQLite3 database in \texttt{/db} in the next step, Configure variables (\autoref{config_install}).
\item \textbf{MySQL}. Once you have MySQL installed, you need to create a database to use with Tracks 1.5. Go into a terminal and issue the following commands:
\end{enumerate}
\begin{adjustwidth}{2.5em}{2.5em}
\begin{verbatim}
mysql -uroot -p
mysql> CREATE DATABASE tracks15;
mysql> GRANT ALL PRIVILEGES ON tracks15.* TO yourmysqluser@localhost \
IDENTIFIED BY 'password-goes-here' WITH GRANT OPTION;
\end{verbatim}
\end{adjustwidth}
\subsection{Configure variables}
\label{config_install}
\begin{enumerate}
\item If you downloaded Tracks 1.5 via Subversion, you need to duplicate the files \texttt{database.yml.tmpl} and \texttt{environment.yml.tmpl} and remove the \texttt{*.tmpl} extension from the duplicates. Similarly, duplicate \texttt{/log.tmpl} and remove the \texttt{*.tmpl} extension, then edit the files as described in steps 2 and 3.
\item Open the file \texttt{/config/database.yml} and edit the \texttt{production:} section with the details of your database. If you are using MySQL the \texttt{adapter:} line should read \texttt{adapter: mysql}, \texttt{host: localhost} (in the majority of cases), and your username and password should match those you assigned when you created the database. If you are using SQLite3, you should have only two lines under the production section: \texttt{adapter: sqlite3} and \texttt{database: db/tracks-15-blank.db}. If you downloaded the zipped file, the database.yml file is already configured to use the provided SQLite3 file.
\item Open the file \texttt{/config/environment.rb}, and read through the settings to make sure that they suit your setup. In most cases, all you need to change is the \texttt{SALT = "change-me"} line (change the string ``change-me" to some other string of your choice), and the time zone setting.
\item If you are using Windows, you may need to check the `shebang' lines (\texttt{\#!/usr/bin/env ruby}) of the \texttt{/public/dispatch.*} files and all the files in the \texttt{/script} directory. They are set to \texttt{\#!/usr/bin/env ruby} by default. This should work for all *nix based setups (Linux or Mac OS X), but Windows users will probably have to change it to something like \texttt{\#c:/ruby/bin/ruby} to point to the Ruby binary on your system.
\end{enumerate}
\subsection{Populate your database with the Tracks 1.5 schema}
\label{rake_install}
Open a terminal and change into the root of your Tracks 1.5 directory. Enter the following command:
\texttt{rake db:migrate RAILS\_ENV=production}
This will update your database with the required schema for Tracks 1.5. If you are using SQLite3, it is not strictly necessary, because the SQLite3 database included with Tracks already has the schema included in it, but it should not do any harm to run the command (nothing will happen if it is up to date).
\subsection{Start the server}
\label{startserver_install}
While still in the Terminal inside the Tracks 1.5 root directory, issue the following command:
\texttt{script/server -e production}
If all goes well, you should see some text informing you that the Mongrel server is running: \texttt{** Mongrel available at 0.0.0.0:3000}. If you are already running other services on port 3000, you need to select a different port when running the server, using the \texttt{-p} option. You can stop the server again by the key combination Ctrl-C.
\subsection{Visit Tracks in a browser}
\label{signup_install}
Visit \texttt{http://0.0.0.0:3000/signup} in a browser (or whatever URL and port was reported when you started the server in the step above) and chose a user name and password for admin user. Once logged in as admin, you can add other (ordinary level) users. If you need to access Tracks from a mobile/cellular phone browser, visit \texttt{http://yourdomain.com/mobile/}. This mobile version is a special, lightweight version of Tracks, designed to use on a mobile browser.
\subsection{Customise Tracks}
\label{customise_install}
Once logged in, add some Contexts and Projects, and then go ahead and add your actions. You might also want to visit the Preferences page to edit various settings to your liking. Have fun!
\chapter{Upgrading to Tracks 1.5}
\label{upgrading}
\section{Upgrading from Tracks 1.043}
\label{upgrading_1043}
This should be a relatively straightforward, and involves the following main steps:
\begin{enumerate}
\item Back up (\autoref{backup_upgrade}) your existing database and installation of Tracks
\item Install Tracks 1.5 (\autoref{install_upgrade}) in a new directory
\item Copy over (\autoref{config_upgrade}) a few configuration files from your Tracks 1.043 directory. If using SQLite3, copy the old database into the new Tracks 1.5 directory
\item Run \texttt{rake db:migrate RAILS\_ENV=production} to update your old database (\autoref{rake_upgrade}) to the new schema -- you did back up your database didn't you?
\item Run \texttt{script/server} inside your Tracks 1.5 directory to start up Tracks 1.5 (\autoref{startserver_upgrade}).
\item Once you are happy that everything is working well, delete your old Tracks directory (\autoref{cleanup_upgrade}).
\end{enumerate}
\subsection{Backing up}
\label{backup_upgrade}
It's very important that you \textbf{back up your database} before you start the upgrade process. It's always possible for things to go wrong with the database update, and you don't want to lose any data. If you are using SQLite3 and you are leaving your old Tracks directory in place, then you don't need to do anything. However, there is no harm in taking extra precautions and copying your database from \texttt{/db} to a safe location as an extra backup, or making a dump of the schema and contents. You will never regret making too many backups! If you are using MySQL, make a SQL dump of your database, replacing the terms in square brackets with the correct information for your setup:
\texttt{mysqldump ---user [user name] ---password=[password] [database name] $>$ [dump file]}
Rename your old Tracks installation (e.g.\ to `tracks-old') so that you can install Tracks 1.5 along side it.
\subsection{Install Tracks 1.5}
\label{install_upgrade}
There are two methods of downloading Tracks 1.5:
\begin{enumerate}
\item (Recommended for most people) Download the \href{http://www.rousette.org.uk/projects/files/tracks-current.zip}{zipped package}, and unzip in your preferred location (e.g.\ \texttt{\ensuremath{\sim}/Sites} for Mac OS X users).
\item Download using Subversion:
\end{enumerate}
\begin{adjustwidth}{2.5em}{2.5em}
\begin{verbatim}
svn co --username=guest \
http://www.rousette.org.uk/svn/tracks-repos/tags/current tracks
\end{verbatim}
\end{adjustwidth}
\subsection{Copy over old configuration files}
\label{config_upgrade}
There are a few files you need to copy over from your old installation. If you copy them over rather than moving them, you can still run your old version of Tracks if anything goes awry with the installation process.
\begin{enumerate}
\item Copy \texttt{/config/database.yml} from your old Tracks directory to the same location in the new one. Double check that the information there is still correct.
\item Duplicate \texttt{/config/environment.rb.tmpl} in the Tracks 1.5 directory, and rename the file to \texttt{environment.rb}. Open the file and alter the line \texttt{SALT = "change-me"} so that it matches what you had in this file in your old installation. You may also want to change the time zone setting as appropriate for your location (\texttt{ENV['TZ'] = 'US/Eastern'}). If you have made any other customisations to \texttt{environment.rb} in the past, copy those over, but the contents of the file have changed quite a lot since 1.043, so check it carefully.
\item Copy your \texttt{/log} directory over from your old installation to the root of the new one, or just rename \texttt{/log.tmpl} to \texttt{log} to start afresh.
\item If you are using SQLite3, copy your database from \texttt{/db} in your old Tracks directory to the same location in the new one.
\item If you are using Windows, you may need to check the `shebang' lines (\texttt{\#!/usr/bin/env ruby})\footnote{The \texttt{env} binary helps to locate other binaries, regardless of their location. If you don't have \texttt{env} installed, you'll need to change this line to point to the location of your Ruby binary.The \texttt{env} binary helps to locate other binaries, regardless of their location. If you don't have \texttt{env} installed, you'll need to change this line to point to the location of your Ruby binary.} of the \texttt{/public/dispatch.*} files and all the files in the \texttt{/script} directory. They are set to \texttt{\#!/usr/bin/env ruby} by default. Check the format of those lines in your old installation, and change the new ones as necessary.
\end{enumerate}
\subsection{Update your old database to the new format}
\label{rake_upgrade}
In a terminal, change directories so that you are inside the Tracks 1.5 directory. Then issue the command to update your Tracks 1.043 database to the format required for Tracks 1.5:
\texttt{rake db:migrate RAILS\_ENV=production}
Watch the output carefully for errors, but it should report at the end of the process that everything worked OK. If you do get errors, you'll have to fix them before you proceed any further. Running rake with the \texttt{--trace} option can help to track down the problem.
\subsection{Start the server}
\label{startserver_upgrade}
If you're still in the Tracks 1.5 root directory in a terminal, enter the following command to start up Tracks in production mode:
\texttt{script/server -e production}
Visit the URL indicated by the output (e.g.\ \texttt{** Mongrel available at 0.0.0.0:3000}
) in a browser, and with any luck, you should be able to log in and find all your actions as you left them! If you need to access Tracks from a mobile/cellular phone browser, visit \texttt{http://yourdomain.com/mobile/}. This mobile version is a special, lightweight version of Tracks, designed to use on a mobile browser.
\subsection{Clean up your old installation}
\label{cleanup_upgrade}
Once you're certain that your new Tracks 1.5 installation is working perfectly, you can delete your old Tracks directory.
\section{Upgrading from versions prior to 1.043}
\label{upgradingfromversionspriorto1.043}
The best option for versions prior to 1.043 is to follow the instructions below to upgrade to version 1.043, then use the instructions above to upgrade from version 1.043 (\autoref{upgrading_1043}).
\begin{enumerate}
\item For safety, rename your current Tracks directory to `tracks-old' or something similar.
\item Before you do anything else, \textbf{BACK UP YOUR DATABASE} (tables and content) and keep the SQL dumps somewhere safe so that you can recreate the old database if necesary.
\item Download a copy of Tracks 1.043 and unzip alongside your `tracks-old' directory.
\item Open the file \texttt{config/environment.rb} and look at the last line which should read: \texttt{SALT = "change-me"}. Change the word change-me to something else of your choosing. This string will be used as a `salt' to encrypt your password and make it a bit more secure. Also look at the timezone setting at the bottom. You can leave it commented out if your server is in the same time zone as you, but you may need to adjust it if your server is in a different time zone.
\item In \texttt{database.yml} insert your old database name, user and password under the `development' section. If you are using SQLite3 rather than MySQL or PostgreSQL, you need only the database name, and to change the `adapter' line to `sqlite3'. You also need to copy (NOT MOVE!), your SQLite3 database from your tracks-old \texttt{db} directory to your new tracks \texttt{db} directory
\item Run the command \texttt{rake extract\_fixtures} inside the Tracks directory. This will populate the \texttt{db/exported\_fixtures} directory with \texttt{*.yml} files corresponding to the contexts, projects and todos table from the contents of your old database.
\item Open \texttt{db/exported\_fixtures/todos.yml} and search for the lines starting \texttt{created:} and replace with \texttt{created\_at:}. If you are using SQLite3, you also need to change the following: \texttt{done: "0"} with \texttt{done: "f"} and \texttt{done: "1"} with \texttt{done: "t"}. You need to replace the similar `done' lines in \texttt{projects.yml}, and in \texttt{contexts.yml} replace \texttt{hide: "0"} with \texttt{hide: "f"} and \texttt{hide: "1"} with \texttt{hide: "t"}.
\item Create a new MySQL database (named tracks1043, for example). In \texttt{database.yml} insert this new database name, user and password under the `development' and `production' sections. If you are using SQLite3, insert a new name for a database to hold your Tracks 1.043 data.
\item Run the command \texttt{rake db\_schema\_import} inside the Tracks directory. This should import the upgraded schema for 1.043 into your new database.
\item Run the command \texttt{rake load\_exported\_fixtures} which will import the contents of your old database from the fixtures files in \texttt{db/exported\_fixtures}.
\item If you are using Windows, you may need to check the `shebang' lines (\texttt{\#!/usr/bin/env ruby})\footnote{The \texttt{env} binary helps to locate other binaries, regardless of their location. If you don't have \texttt{env} installed, you'll need to change this line to point to the location of your Ruby binary.The \texttt{env} binary helps to locate other binaries, regardless of their location. If you don't have \texttt{env} installed, you'll need to change this line to point to the location of your Ruby binary.} of the \texttt{/public/dispatch.*} files and all the files in the \texttt{/script} directory. They are set to \texttt{\#!/usr/bin/env ruby} by default. Check the format of those lines in your old installation, and change the new ones as necessary.
\item Try starting up the server with \texttt{script/server} to make sure that all your data has migrated successfully. If all is well, follow the instructions above to upgrade from version 1.043 (\autoref{upgrading_1043}) to Tracks 1.5. If you need to access Tracks from a mobile/cellular phone browser, visit \texttt{http://yourdomain.com/mobile/}. This mobile version is a special, lightweight version of Tracks, designed to use on a mobile browser.
\end{enumerate}
%
% Back Matter
%
\backmatter
%\appendixpage
% Bibliography
\bibliographystyle{\mybibliostyle}
\bibliocommand
% Glossary
\printglossary
% Index
\printindex
\end{document}

134
doc/memoir-twosided-manual.xslt Normal file
View file

@ -0,0 +1,134 @@
<?xml version='1.0' encoding='utf-8'?>
<!-- XHTML-to-Memoir converter by Fletcher Penney
specifically designed for use with MultiMarkdown created XHTML
Uses the LaTeX memoir class for output with the twoside option
MultiMarkdown Version 2.0.b3
$Id: memoir-twosided.xslt 400 2007-05-26 18:42:49Z fletcher $
-->
<!--
# Copyright (C) 2005-2007 Fletcher T. Penney <fletcher@fletcherpenney.net>
#
# 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.
# 59 Temple Place, Suite 330
# Boston, MA 02111-1307 USA
-->
<xsl:stylesheet
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:html="http://www.w3.org/1999/xhtml"
version="1.0">
<xsl:import href="memoir.xslt"/>
<xsl:output method='text' encoding='utf-8'/>
<xsl:strip-space elements="*" />
<xsl:template match="/">
<xsl:apply-templates select="html:html/html:head"/>
<xsl:apply-templates select="html:html/html:body"/>
<xsl:call-template name="latex-footer"/>
</xsl:template>
<xsl:template name="latex-document-class">
<xsl:text>\documentclass[10pt,twoside]{memoir}
\usepackage{layouts}[2001/04/29]
\usepackage{palatino}
\usepackage{color,calc}
\newsavebox{\ChpNumBox}
\definecolor{ChapBlue}{rgb}{0.00,0.65,0.65}
\makeatletter
\newcommand*{\thickhrulefill}{%
\leavevmode\leaders\hrule height 1\p@ \hfill \kern \z@}
\newcommand*\BuildChpNum[2]{%
\begin{tabular}[t]{@{}c@{}}
\makebox[0pt][c]{#1\strut} \\[.5ex]
\colorbox{ChapBlue}{%
\rule[-10em]{0pt}{0pt}%
\rule{1ex}{0pt}\color{black}#2\strut
\rule{1ex}{0pt}}%
\end{tabular}}
\makechapterstyle{BlueBox}{%
\renewcommand{\chapnamefont}{\large\scshape}
\renewcommand{\chapnumfont}{\Huge\bfseries}
\renewcommand{\chaptitlefont}{\raggedright\Huge\bfseries}
\setlength{\beforechapskip}{20pt}
\setlength{\midchapskip}{26pt}
\setlength{\afterchapskip}{40pt}
\renewcommand{\printchaptername}{}
\renewcommand{\chapternamenum}{}
\renewcommand{\printchapternum}{%
\sbox{\ChpNumBox}{%
\BuildChpNum{\chapnamefont\@chapapp}%
{\chapnumfont\thechapter}}}
\renewcommand{\printchapternonum}{%
\sbox{\ChpNumBox}{%
\BuildChpNum{\chapnamefont\vphantom{\@chapapp}}%
{\chapnumfont\hphantom{\thechapter}}}}
\renewcommand{\afterchapternum}{}
\renewcommand{\printchaptertitle}[1]{%
\usebox{\ChpNumBox}\hfill
\parbox[t]{\hsize-\wd\ChpNumBox-1em}{%
\vspace{\midchapskip}%
\thickhrulefill\par
\chaptitlefont ##1\par}}%
}
\chapterstyle{BlueBox}
\setsecheadstyle{\sffamily\bfseries\Large}
\setsubsecheadstyle{\sffamily\bfseries\normal}
\makepagestyle{myruledpagestyle}
\makeevenhead{myruledpagestyle}{\thepage}{}{\leftmark}
\makeoddhead{myruledpagestyle}{\rightmark}{}{\thepage}
\makeatletter
\makepsmarks{myruledpagestyle}{
\def\chaptermark##1{\markboth{%
\ifnum \value{secnumdepth} > -1
\if@mainmatter
\chaptername\ \thechapter\ --- %
\fi
\fi
##1}{}}
\def\sectionmark##1{\markright{%
\ifnum \value{secnumdepth} > 0
\thesection. \ %
\fi
##1}}
}
\makeatother
\makerunningwidth{myruledpagestyle}{1.1\textwidth}
\makeheadposition{myruledpagestyle}{flushright}{flushleft}{flushright}{flushleft}
\makeheadrule{myruledpagestyle}{1.1\textwidth}{\normalrulethickness}
\makeglossary
\makeindex
\def\mychapterstyle{BlueBox}
\def\mypagestyle{myruledpagestyle}
\def\revision{}
</xsl:text>
</xsl:template>
</xsl:stylesheet>

58
doc/tracks_api_wrapper.rb Normal file
View file

@ -0,0 +1,58 @@
require 'activeresource'
# Install the ActiveResource gem if you don't already have it:
#
# sudo gem install activeresource --source http://gems.rubyonrails.org --include-dependencies
# $ SITE="http://myusername:p4ssw0rd@mytracksinstallation.com" irb -r tracks_api_wrapper.rb
#
# >> my_pc = Tracks::Context.find(:first)
# => #<Tracks::Context:0x139c3c0 @prefix_options={}, @attributes={"name"=>"my pc", "updated_at"=>Mon Aug 13 02:56:18 UTC 2007, "hide"=>0, "id"=>8, "position"=>1, "created_at"=>Wed Feb 28 07:07:28 UTC 2007}
# >> my_pc.name
# => "my pc"
# >> my_pc.todos
# => [#<Tracks::Todo:0x1e16b84 @prefix_options={}, @attributes={"context_id"=>8, "completed_at"=>Tue Apr 10 12:57:24 UTC 2007, "project_id"=>nil, "show_from"=>nil, "id"=>1432, "notes"=>nil, "description"=>"check rhino mocks bug", "due"=>Mon, 09 Apr 2007, "created_at"=>Sun Apr 08 04:56:35 UTC 2007, "state"=>"completed"}, #<Tracks::Todo:0x1e16b70 @prefix_options={}, @attributes={"context_id"=>8, "completed_at"=>Mon Oct 10 13:10:21 UTC 2005, "project_id"=>10, "show_from"=>nil, "id"=>17, "notes"=>"fusion problem", "description"=>"Fix Client Installer", "due"=>nil, "created_at"=>Sat Oct 08 00:19:33 UTC 2005, "state"=>"completed"}]
#
# >> t = Tracks::Todo.new
# => #<Tracks::Todo:0x1ee9fc0 @prefix_options={}, @attributes={}>
# >> t.description = "do it now"
# => "do it now"
# >> t.context_id = 8
# => 8
# >> t.save
# => true
# >> t.reload
# => #<Tracks::Todo:0x1ee9fc0 @prefix_options={}, @attributes={"completed_at"=>nil, "context_id"=>8, "project_id"=>nil, "show_from"=>nil, "notes"=>nil, "id"=>1791, "description"=>"do it now", "due"=>nil, "created_at"=>Mon Dec 03 19:15:46 UTC 2007, "state"=>"active"}
# >> t.put(:toggle_check)
# => #<Net::HTTPOK 200 OK readbody=true>
# >> t.reload
# => #<Tracks::Todo:0x1ee9fc0 @prefix_options={}, @attributes={"completed_at"=>Mon Dec 03 19:17:46 UTC 2007, "context_id"=>8, "project_id"=>nil, "show_from"=>nil, "notes"=>nil, "id"=>1791, "description"=>"do it now", "due"=>nil, "created_at"=>Mon Dec 03 19:15:46 UTC 2007, "state"=>"completed"}
# If you want to see the HTTP requests and responses that are being passed back and
# forth, you can tweak your active_resource like as described in:
# http://blog.pepperdust.org/2007/2/13/enabling-wire-level-debug-output-for-activeresource
module Tracks
class Base < ActiveResource::Base
self.site = ENV["SITE"] || "http://username:password@0.0.0.0:3000/"
end
class Todo < Base
end
class Context < Base
def todos
return attributes["todos"] if attributes.keys.include?("todos")
return Todo.find(:all, :params => {:context_id => id})
end
end
class Project < Base
def todos
return attributes["todos"] if attributes.keys.include?("todos")
return Todo.find(:all, :params => {:project_id => id})
end
end
end