| 1 | moap is a swiss army knife for project maintainers and developers. |
|---|
| 2 | It aims to help in keeping you in the flow of maintaining, developing and |
|---|
| 3 | releasing, automating whatever tasks can be automated. |
|---|
| 4 | |
|---|
| 5 | FEATURES |
|---|
| 6 | -------- |
|---|
| 7 | The current list of features includes: |
|---|
| 8 | |
|---|
| 9 | - parse DOAP files and: |
|---|
| 10 | - submit releases to Freshmeat |
|---|
| 11 | - send out release announcement mails |
|---|
| 12 | - create iCal and RSS release feeds from DOAP file(s) |
|---|
| 13 | - template them using Genshi or Cheetah |
|---|
| 14 | - look up project home page rank on Google and Yahoo for given queries |
|---|
| 15 | - version control tools: |
|---|
| 16 | - currently supports Bazaar, CVS, Darcs, Git, SVN, git-svn |
|---|
| 17 | - maintain ignore lists |
|---|
| 18 | - prepare ChangeLog entry based on local diff, using ctags |
|---|
| 19 | - check in based on ChangeLog entry |
|---|
| 20 | - show diff based on last ChangeLog entry |
|---|
| 21 | - archive checkout |
|---|
| 22 | - bug tracker tools: |
|---|
| 23 | - show individual bugs and queries from trac and bugzilla |
|---|
| 24 | - developed in Python, with unit tests and coverage |
|---|
| 25 | - get list of contributors from ChangeLog |
|---|
| 26 | - search through ChangeLog |
|---|
| 27 | - bash completion |
|---|
| 28 | - administering a trac installation |
|---|
| 29 | |
|---|
| 30 | Future features planned include: |
|---|
| 31 | - support for other VCS systems |
|---|
| 32 | - sending patches and attaching them to bug trackers |
|---|
| 33 | - working with quilt |
|---|
| 34 | |
|---|
| 35 | DEPENDENCIES |
|---|
| 36 | ------------ |
|---|
| 37 | moap requires Python 2.3. |
|---|
| 38 | |
|---|
| 39 | moap can make use of: |
|---|
| 40 | - the Redland python bindings (RDF), for parsing of DOAP files |
|---|
| 41 | - bzr, cvs, darcs, git, git-svn, and svn, for handling checkouts |
|---|
| 42 | - Genshi and Cheetah, for templating |
|---|
| 43 | - exuberant-ctags, for tag extraction |
|---|
| 44 | - Twisted's trial, for unit tests |
|---|
| 45 | - epydoc, for API documentation |
|---|
| 46 | - trac, for maintaining a trac installation |
|---|
| 47 | |
|---|
| 48 | GETTING MOAP |
|---|
| 49 | ------------ |
|---|
| 50 | Preferably, install moap from a package supplied by your distribution. |
|---|
| 51 | If no package is available, you can build it from a source tarball. |
|---|
| 52 | If you want to hack on it or want to try the bleeding edge version, you |
|---|
| 53 | can check it out from subversion. |
|---|
| 54 | |
|---|
| 55 | If you are building from a source tarball or checkout, you can choose to |
|---|
| 56 | use moap installed or uninstalled. |
|---|
| 57 | |
|---|
| 58 | - getting: |
|---|
| 59 | - Change to a directory where you want to put the moap source code |
|---|
| 60 | (For example, $HOME/dev/ext or $HOME/prefix/src) |
|---|
| 61 | - source: download tarball, unpack, and change to its directory |
|---|
| 62 | - checkout: |
|---|
| 63 | svn co https://thomas.apestaart.org/moap/svn/trunk moap |
|---|
| 64 | cd moap |
|---|
| 65 | ./autogen.sh |
|---|
| 66 | |
|---|
| 67 | - building: |
|---|
| 68 | ./configure |
|---|
| 69 | make |
|---|
| 70 | |
|---|
| 71 | - you can now choose to install it or run it uninstalled. |
|---|
| 72 | - installing: |
|---|
| 73 | make install |
|---|
| 74 | - running uninstalled: |
|---|
| 75 | ln -sf `pwd`/misc/moap-uninstalled $HOME/bin/moap-trunk |
|---|
| 76 | moap-trunk |
|---|
| 77 | (this drops you in a shell where everything is set up to use moap) |
|---|
| 78 | |
|---|
| 79 | - test basic functionality: |
|---|
| 80 | moap doap show |
|---|
| 81 | (should show you project information for moap itself) |
|---|
| 82 | |
|---|
| 83 | RUNNING MOAP |
|---|
| 84 | ------------ |
|---|
| 85 | moap is self-documenting. |
|---|
| 86 | moap -h gives you the basic instructions. |
|---|
| 87 | |
|---|
| 88 | moap implements a tree of commands; for example, the top-level 'changelog' |
|---|
| 89 | command has a number of sub-commands. |
|---|
| 90 | |
|---|
| 91 | Positioning of arguments is important; |
|---|
| 92 | moap doap -f (file) show |
|---|
| 93 | is correct, while |
|---|
| 94 | moap doap show -f (file) |
|---|
| 95 | is not, because the -f argument applies to the doap command. |
|---|
| 96 | |
|---|
| 97 | EXAMPLES |
|---|
| 98 | -------- |
|---|
| 99 | - to get help on the changelog command: |
|---|
| 100 | moap cl -h |
|---|
| 101 | |
|---|
| 102 | - to create a new ChangeLog entry based on the local modifications: |
|---|
| 103 | moap cl prep |
|---|
| 104 | |
|---|
| 105 | - to check in all files mentioned in the latest ChangeLog entry: |
|---|
| 106 | moap cl ci |
|---|
| 107 | |
|---|
| 108 | - update ignore lists: |
|---|
| 109 | moap ignore |
|---|
| 110 | (then edit the file and keep only the files that need to be ignored) |
|---|
| 111 | |
|---|
| 112 | - show information about your project: |
|---|
| 113 | moap doap show |
|---|
| 114 | |
|---|
| 115 | - submit the 0.2.0 release of your project to freshmeat: |
|---|
| 116 | moap doap -v 0.2.0 freshmeat |
|---|
| 117 | |
|---|
| 118 | DOGFOODING |
|---|
| 119 | ---------- |
|---|
| 120 | moap is hip to the kid's lingo and is 100% dogfoodable. The ChangeLog is |
|---|
| 121 | managed with moap changelog commands. The list of files that SVN should ignore |
|---|
| 122 | is managed with moap ignore. The list of bugs fixed is generated with moap |
|---|
| 123 | doap bug query. The releases are announced to freshmeat with moap doap |
|---|
| 124 | freshmeat. Mails get sent out with moap doap mail. |
|---|
| 125 | |
|---|
| 126 | DEBUGGING |
|---|
| 127 | --------- |
|---|
| 128 | You can set the MOAP_DEBUG environment variable to get debug output. |
|---|
| 129 | The variable takes a comma-separated list of category:value strings. |
|---|
| 130 | |
|---|
| 131 | To get all debugging, set MOAP_DEBUG to *:5 |
|---|
| 132 | |
|---|
| 133 | BUGS, ENHANCEMENTS, ... |
|---|
| 134 | ----------------------- |
|---|
| 135 | All issues can be filed at |
|---|
| 136 | http://thomas.apestaart.org/moap/trac/newticket |
|---|
| 137 | |
|---|
| 138 | DOAP |
|---|
| 139 | ---- |
|---|
| 140 | For more information on DOAP, see http://usefulinc.com/doap/ |
|---|
| 141 | |
|---|
| 142 | You can create a DOAP file easily using the DOAP A Matic website: |
|---|
| 143 | http://crschmidt.net/semweb/doapamatic/ |
|---|
| 144 | |
|---|
| 145 | Python projects using setuptools can easily get a DOAP file generated |
|---|
| 146 | by registering with CheeseShop: |
|---|
| 147 | |
|---|
| 148 | python setup.py sdist register |
|---|
| 149 | |
|---|
| 150 | The DOAP file ends up here: |
|---|
| 151 | http://cheeseshop.python.org/pypi?:action=doap&name=<YOUR_PROJECT_NAME> |
|---|
| 152 | |
|---|
| 153 | CONTACT |
|---|
| 154 | ------- |
|---|
| 155 | The moap project page is http://thomas.apestaart.org/moap/trac/ |
|---|
| 156 | |
|---|
| 157 | There is no mailing list yet. You can mail me at |
|---|
| 158 | thomas <at> apestaart <dot> org for now. |
|---|
