Merge lp:~jkakar/todo/project-skeleton into lp:todo

[Jamu Kakar]

This branch introduces the following changes:

- A README.rst file has been added with ideas about the command line
  UI sketched out. There is still more to describe, but we have
  enough of a basic design to start writing some code.

- A Makefile and setup.py are in place with basic support for running
  tests, generating API documentation, etc.

- A mostly empty top-level 'todo' package has been added. It has an
  'entry_point' module with glue to wire up Commandant. A bin/td
  executable invokes entery point code. At present it just displays
  the stock 'basic' help topic and the stock builtin 'help' and
  'version' commands.

[Nicholas Tollervey (ntoll)]

OK... The only reason I put that it needs fixing is because of the following relatively trivial items:

1) Please list authors alphabetically - it's a nice precedent that everyone understands.
2) The setup.py file needs to reference commandant in some way. The simplest thing to do would be to upload commandant to PyPI and add the following line in setup.py:

     requires=['commandant',]

Instructions for how to do this can be found in the Python docs. I'm more than happy to help with this process (it's very easy).

Other than that [phone] from me. :-)

review: Needs Fixing

[lp:~jkakar/todo/project-skeleton]

9. By Jamu Kakar on 2011-01-22

- Reorder authors to be alphabetic.

10. By Jamu Kakar on 2011-01-22

- Added 'commandant' to the requires list in setup.py.

[Jamu Kakar (jkakar)]

I've pushed new revisions with the fixes you've requested. Thanks for
the review!

Unmerged revisions

10. By Jamu Kakar on 2011-01-22

- Added 'commandant' to the requires list in setup.py.

9. By Jamu Kakar on 2011-01-22

- Reorder authors to be alphabetic.

8. By Jamu Kakar on 2011-01-20

- Added information about dependencies to the README file.

7. By Jamu Kakar on 2011-01-20

- Added a Makefile with basic targets to run tests, generate API
  documentation, etc.
- Added a setup.py to generate releases.
- Added _trial_temp to Bazaar's ignore list.

6. By Jamu Kakar on 2011-01-20

- Added a bin/td executable to invoke Todo.

5. By Jamu Kakar on 2011-01-20

- Added a 'todo' package with a simple entry point to wire up
  Commandant.

4. By Jamu Kakar on 2011-01-20

- Added a 'License' section.

3. By Jamu Kakar on 2011-01-19

- Added more details to the README and TODO files.

2. By Jamu Kakar on 2011-01-19

- Start writing README and TODO files to design the user interface and
  capture questions.

=== added file '.bzrignore'
--- .bzrignore	1970-01-01 00:00:00 +0000
+++ .bzrignore	2011-01-22 10:00:09 +0000
@@ -0,0 +1,1 @@
+_trial_temp

=== added file 'Makefile'
--- Makefile	1970-01-01 00:00:00 +0000
+++ Makefile	2011-01-22 10:00:09 +0000
@@ -0,0 +1,29 @@
+clean:
+	find . -name \*pyc -exec rm {} \;
+	rm -rf _trial_temp
+
+check:
+	trial todo
+
+release:
+	python setup.py sdist
+
+doc:
+	pydoctor \
+		--project-name Todo \
+		--project-url "http://launchpad.net/todo" \
+		--project-base-dir `pwd` \
+		--add-package todo \
+		--make-html
+
+info:
+	@bzr info
+	@echo
+	@echo "Revision:"
+	@bzr revno
+	@echo
+	@echo "Lines of application code:"
+	@find todo -name \*py | grep -v test_ | xargs cat | wc -l
+	@echo
+	@echo "Lines of test code:"
+	@find todo -name \*py | grep test_ | xargs cat | wc -l

=== added file 'README.rst'
--- README.rst	1970-01-01 00:00:00 +0000
+++ README.rst	2011-01-22 10:00:09 +0000
@@ -0,0 +1,227 @@
+Todo is a task tracker for teams!
+
+
+License
+-------
+
+Todo is a task tracker for teams!
+Copyright (C) 2011 Jamshed Kakar <[e-mail]> and Nicholas Tollervey
+<[e-mail]>.
+
+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 3 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, see <http://www.gnu.org/licenses/>.  On Ubuntu systems,
+the complete text of the GNU General Public Version 2 License is in
+`/usr/share/common-licenses/GPL-3'.
+
+
+Dependencies
+------------
+
+Todo requires Python 2.6+ and has the following package dependencies:
+
+  python-commandant
+  python-testtools (to run the test suite)
+
+The python-commandant package is available from a PPA:
+
+  https://launchpad.net/~jkakar/+archive/commandant
+
+
+Use cases
+---------
+
+ - Manager assigns task to employee
+   - Employee receives notification of task (via Twitter or Jabber or IRC)
+ - I can {un,}assign a task to myself
+   - Into a category, (eg. personal task, Fluidinfo task, etc.)
+ - I can view someone elses task list
+ - I can add a person to a category I'm in
+
+
+Using Todo
+----------
+
+Logging in
+~~~~~~~~~~
+
+::
+  $ td login $fluiddb-username $fluiddb-password
+
+Todo will write a credentials file to ~/.config/todo/credentials.txt.  These
+will be used whenever you use Todo.  When you login for the first time a
+default category is created with the same name as your FluidDB username.
+
+Creating and deleting categories
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+  $ td create-category fluidinfo
+
+A category is a container for related tasks.  When a category is created, the
+creator is the only person who has access to tasks in that category.
+
+::
+  $ td delete-category fluidinfo
+
+When a category is deleted, so are all tasks in the category.
+
+
+Granting and revoking access to a category
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+  $ td grant ntoll fluidinfo
+
+The grant command gives a user access to tasks in a category.  The user is
+capable of reading and modify all tasks in the category, including adding or
+removing users from the category itself.
+
+::
+  $ td revoke ntoll fluidinfo
+
+The revoke command removes a user from a category.  The user is unassigned
+from any tasks they may be linked to in the category.
+
+
+Creating a new task
+~~~~~~~~~~~~~~~~~~~
+
+::
+  $ td add "Do laundry"
+  OK
+
+This item is automatically assigned to you and the creation time is stored.
+It starts life in a 'pending' state.  The task ID is printed out.  The -c
+option can be passed to specify a category::
+
+  $ td add -c fluidinfo "Deploy sandbox"
+
+Assigning a task to a category makes it visible to people that have been
+granted access to see and modify tasks in that category.  Tasks are assigned
+to you, by default.
+
+Showing tasks
+~~~~~~~~~~~~~
+
+::
+  $ td list
+  ID   Task                                          Created  Status
+  ---- --------------------------------------------  -------  -------
+  1    Buy dirty socks                               Jan 18   started
+  2    Buy laundry soap                              Jan 19   started
+  3    Do laundry                                    Jan 19   pending
+
+By default, 'list' shows tasks that are started and pending.  Items are sorted
+by state, then by time with the newest first::
+
+  $ td list --started
+  ID   Task                                          Created  Status
+  ---- --------------------------------------------  -------  -------
+  1    Buy dirty socks                               Jan 18   started
+
+The --started option can be passed to limit output to only those tasks that
+are in progress.  Other options include --pending, --done and --dropped::
+
+  $ td list --all
+  ID   Task                                 Creator  Created  Status
+  ---- -----------------------------------  -------  -------  -------
+  1    Buy dirty socks                      jkakar   Jan 18   started
+  2    Buy laundry soap                              Jan 19   started
+  3    Do laundry                                    Jan 19   pending
+  4    Buy washing machine                           Jan 17   done
+  5    Buy dirty underwear                           Jan 17   dropped
+
+The --all option displays all tasks, including completed and dropped ones.
+The options can be used in conjunction with the -c option to show tasks from a
+specific category::
+
+  $ td list -u ntoll
+  ID   Task                                 Creator  Created  Status
+  ---- -----------------------------------  -------  -------  -------
+  1    Phone kids                           ntoll    Jan 19   pending
+
+Starting a task
+~~~~~~~~~~~~~~~
+
+::
+  $ td start 1
+
+A task can be started using the short ID.  It can also be started using the
+object ID of the task object in FluidDB::
+
+  $ td start 8ec67dc7-3477-4ea1-9e01-d0c06f1ba444
+
+Completing a task
+~~~~~~~~~~~~~~~~~
+
+::
+  $ td done 1
+
+A task can be completed using the short ID.  It can also be completed using
+the object ID of the task object in FluidDB::
+
+  $ td done 8ec67dc7-3477-4ea1-9e01-d0c06f1ba444
+
+Dropping a task
+~~~~~~~~~~~~~~~
+
+::
+  $ td drop 1
+
+A task can be dropped using the short ID.  It can also be dropped using the
+object ID of the task object in FluidDB::
+
+  $ td drop 8ec67dc7-3477-4ea1-9e01-d0c06f1ba444
+
+Assigning and unassigning a task
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+  $ td assign 1 ntoll
+
+A task can be assigned to another user.
+
+::
+  $ td unassign 1
+
+A task can be unassigned.
+
+
+FluidDB data model
+------------------
+
+Representing categories and tasks
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Categories are represented as namespaces in FluidDB, like::
+
+  todo/<category>
+
+Tags within a category are used to track details related to a task, one object
+per task::
+
+  todo/<category>
+    description -> "foo"
+    owner -> "jkakar"
+    ...
+
+The tags in a category have a closed policy with a list of exceptions, that
+are the users who have access to read or modify data about the tasks.
+
+
+Deleting a category
+~~~~~~~~~~~~~~~~~~~
+
+When a category is deleted, the tags on tasks (represented as objects) are
+first deleted.  The tags on the namespace object that represents the category
+are then removed.

=== added file 'TODO'
--- TODO	1970-01-01 00:00:00 +0000
+++ TODO	2011-01-22 10:00:09 +0000
@@ -0,0 +1,7 @@
+- Figure out what to do for the about tag.
+
+- If categories are namespaces and data is stored as tags in those
+  namespaces, how do we:
+  - Querying across categories.  One solution would be to add
+    wildcards to FluidDB so we could do: todo/*/owner = "ntoll"
+

=== added directory 'bin'
=== added file 'bin/td'
--- bin/td	1970-01-01 00:00:00 +0000
+++ bin/td	2011-01-22 10:00:09 +0000
@@ -0,0 +1,14 @@
+#!/usr/bin/python
+
+"""Use Todo interactively from a text prompt."""
+
+import os
+import sys
+
+if os.path.isdir("todo"):
+    sys.path.insert(0, "./")
+
+from todo.entry_point import main
+
+
+main(sys.argv)

=== added file 'setup.py'
--- setup.py	1970-01-01 00:00:00 +0000
+++ setup.py	2011-01-22 10:00:09 +0000
@@ -0,0 +1,42 @@
+#!/usr/bin/env python
+
+# Todo is a task tracker for teams!
+# Copyright (C) 2011 Jamshed Kakar <[e-mail]> and Nicholas Tollervey
+# <[e-mail]>.
+#
+# 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 3 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.
+
+from distutils.core import setup
+import os
+
+from todo import __version__ as version
+
+
+def find_packages():
+    """Find installable packages in the L{todo} source tree."""
+    packages = []
+    for directory, subdirectories, files in os.walk("todo"):
+        if "__init__.py" in files:
+            packages.append(directory.replace(os.sep, "."))
+    return [package for package in packages if "tests" not in package]
+
+
+setup(name="todo",
+      version=version,
+      description="Todo is a task tracker for teams!",
+      author="Nicholas Tollervey, Jamshed Kakar",
+      author_email="[e-mail], [e-mail]",
+      url="http://launchpad.net/todo",
+      license="GPLv3",
+      url="https://launchpad.net/todo",
+      packages=find_packages(),
+      requires=["commandant"],
+      scripts=["bin/td"])

=== added directory 'todo'
=== added file 'todo/__init__.py'
--- todo/__init__.py	1970-01-01 00:00:00 +0000
+++ todo/__init__.py	2011-01-22 10:00:09 +0000
@@ -0,0 +1,18 @@
+# Todo is a task tracker for teams!
+# Copyright (C) 2011 Jamshed Kakar <[e-mail]> and Nicholas Tollervey
+# <[e-mail]>.
+#
+# 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 3 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.
+
+"""Todo is a task tracker for teams!"""
+
+__version_info__ = (0, 1, 0)
+__version__ = ".".join(str(part) for part in __version_info__)

=== added file 'todo/entry_point.py'
--- todo/entry_point.py	1970-01-01 00:00:00 +0000
+++ todo/entry_point.py	2011-01-22 10:00:09 +0000
@@ -0,0 +1,43 @@
+# Todo is a task tracker for teams!
+# Copyright (C) 2011 Jamshed Kakar <[e-mail]> and Nicholas Tollervey
+# <[e-mail]>.
+#
+# 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 3 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.
+
+"""Bootstrap code starts and runs Todo."""
+
+from commandant import builtins
+from commandant.controller import CommandController
+
+from todo import __version__
+
+
+def main(argv):
+    """Run the command named in C{argv}.
+
+    If a command name isn't provided the C{help} command is shown.
+
+    @param argv: A list command-line arguments.  The first argument should be
+       the name of the command to run.  Any further arguments are passed to
+       the command.
+    """
+    if len(argv) < 2:
+        argv.append("help")
+
+    controller = CommandController("todo", __version__,
+                                   "Todo is a task tracker for teams!",
+                                   "https://launchpad.net/todo")
+    controller.load_module(builtins)
+    controller.install_bzrlib_hooks()
+    try:
+        controller.run(argv[1:])
+    except StandardError, e:
+        print e