source: trunk/README @ 412

Revision 412, 4.7 KB checked in by thomas, 8 years ago (diff)

releasing 0.2.7

Line 
1moap is a swiss army knife for project maintainers and developers.
2It aims to help in keeping you in the flow of maintaining, developing and
3releasing, automating whatever tasks can be automated.
4
5FEATURES
6--------
7The 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
30Future features planned include:
31- support for other VCS systems
32- sending patches and attaching them to bug trackers
33- working with quilt
34
35DEPENDENCIES
36------------
37moap requires Python 2.3.
38
39moap 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
48GETTING MOAP
49------------
50Preferably, install moap from a package supplied by your distribution.
51If no package is available, you can build it from a source tarball.
52If you want to hack on it or want to try the bleeding edge version, you
53can check it out from subversion.
54
55If you are building from a source tarball or checkout, you can choose to
56use 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
83RUNNING MOAP
84------------
85moap is self-documenting.
86moap -h gives you the basic instructions.
87
88moap implements a tree of commands; for example, the top-level 'changelog'
89command has a number of sub-commands.
90
91Positioning of arguments is important;
92  moap doap -f (file) show
93is correct, while
94  moap doap show -f (file)
95is not, because the -f argument applies to the doap command.
96
97EXAMPLES
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
118DOGFOODING
119----------
120moap is hip to the kid's lingo and is 100% dogfoodable.  The ChangeLog is
121managed with moap changelog commands.  The list of files that SVN should ignore
122is managed with moap ignore.  The list of bugs fixed is generated with moap
123doap bug query.  The releases are announced to freshmeat with moap doap
124freshmeat.  Mails get sent out with moap doap mail.
125 
126DEBUGGING
127---------
128You can set the MOAP_DEBUG environment variable to get debug output.
129The variable takes a comma-separated list of category:value strings.
130
131To get all debugging, set MOAP_DEBUG to *:5
132
133BUGS, ENHANCEMENTS, ...
134-----------------------
135All issues can be filed at
136http://thomas.apestaart.org/moap/trac/newticket
137
138DOAP
139----
140For more information on DOAP, see http://usefulinc.com/doap/
141
142You can create a DOAP file easily using the DOAP A Matic website:
143http://crschmidt.net/semweb/doapamatic/
144
145Python projects using setuptools can easily get a DOAP file generated
146by registering with CheeseShop:
147
148  python setup.py sdist register
149 
150The DOAP file ends up here:
151http://cheeseshop.python.org/pypi?:action=doap&name=<YOUR_PROJECT_NAME>
152
153CONTACT
154-------
155The moap project page is http://thomas.apestaart.org/moap/trac/
156
157There is no mailing list yet.  You can mail me at
158thomas <at> apestaart <dot> org for now.
Note: See TracBrowser for help on using the repository browser.