--- a/docs/admin/install.rst	Thu Dec 19 14:57:19 2013 -0700
+++ b/docs/admin/install.rst	Sun Jan 12 11:45:03 2014 -0700
@@ -4,168 +4,153 @@
 
 Downloading
 ===========
-For moin2, there is currently no packaged download available, so you have to get
-it from the repository.
-You can use one of two repository URLs and either use Mercurial to keep a 
-constantly updated copy of the code or download an archive of the files in tar.gz format:
-
-Using Mercurial to clone one of the repositories::
+The recommended way to download moin2 is to clone
+the moin2 Mercurial repository or its mirror. Open a terminal
+window or a command prompt, cd to the directory that will hold
+your project root directory and enter either one of the commands
+below::
 
  hg clone http://hg.moinmo.in/moin/2.0 moin-2.0
+
  OR
+
  hg clone http://bitbucket.org/thomaswaldmann/moin-2.0 moin-2.0
 
 Now make sure your work directory is using the default branch::
 
  hg up -C default
 
-Alternatively, visit http://hg.moinmo.in/moin/2.0 with your web browser and download the archive
-(usually for the "default" branch) and unpack it.
+An alternative installation method is to download the bz2 archive
+from http://hg.moinmo.in/moin/2.0 and unpack it. Once unpacked,
+continue to follow the instructions below.
 
 Installing
 ==========
 Before you can run moin, you need to install it:
 
-Developer install
------------------
-Using your standard Python install or a virtualenv directory
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Please make sure you have `virtualenv` installed, it includes `pip`.
-
-If you just want to run moin in-place in your mercurial working directory
-with your normal system installation of Python, run the following command
-from your mercurial moin2 working directory. You should not run this as an
-administrator or root user; use your standard user account::
-
- python quickinstall.py
-
-This will use virtualenv to create a directory `../venv-PROJECT-PYTHON/`
-(PROJECT is same as your current project directory, e.g. moin-2.0, PYTHON is
-the name of your python interpreter, e.g. python), create a virtual environment
-for MoinMoin and then install moin2 including all dependencies into that
-directory.
-
-`pip` will automatically fetch all dependencies from PyPI and install them, so
-this may take a while.
-It will also compile the translations (`*.po` files) to binary `*.mo` files.
-
-Please review the output of the quickinstall script, and check whether there were fatal errors.
-
-Further, the quickinstall script will create a `moin` script for your
-platform which you can use for starting the built-in server or invoke moin script commands.
-
-After you activated the virtual environment, the built-in server script, which is named 
-`moin`, will be in the standard PATH, so you can just run the command `moin` on the command line.
-
-**Note:** in this special mode, it won't copy the MoinMoin code to the virtualenv directory,
-it will run everything from your work dir, so you can modify code and directly try it out.
-You only need to do this installation procedure once.
-
-Using a different Python
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-If you rather like a different Python, just use it to invoke the quickinstall.py
-script - the same python will then be used for the virtual env also::
-
- /opt/pypy/bin/pypy quickinstall.py  # for linux
-
-
-Activating the virtual env
---------------------------
-
-IMPORTANT: you always need to activate the virtual environment before running
-anything that executes moin code! Otherwise it won't find the moin command,
-nor the moin code nor the libraries it needs. Also, if you want to install
-additional software into the virtual environment, activate it before running pip!::
-
- source ../venv-moin-2.0-python/bin/activate  # for linux (or other posix OSes)
- # or
- ..\venv-moin-2.0-python\Scripts\activate.bat  # for windows
-
-As you have activated the virtual env now, the moin command should be in your
-path now, so you can invoke it using "moin".
-
-Note: the quickinstall script outputs the correct commands for activating
-the virtual env and for the moin executable file.
-
-Letting moin find the wiki configuration
-----------------------------------------
+Using your standard user account, run the following command
+from the project root directory. Replace <python> in the command
+below with the path to a python 2.7 executable. This is usually
+just "python", but may be "python2.7", "/opt/pypy/bin/pypy"
+or even <some-other-path-to-python>::
 
-moin needs to find the wiki configuration. If you want it to run in the most
-simple way without giving parameters to the moin command, it is easiest if
-you are in the same directory as the configuration files, e.g. wikiconfig.py.
-
-If you are working from a repository workdir, this is the top level
-directory and there is already a ready-to-use wikiconfig.py.
-
-In case you want to just give the configuration file location, make sure you
-use an **absolute path**. moin will try to find its configuration in this
-order:
-
-- command line argument `--config /path/to/wikiconfig.py`
-- environment variable `MOINCFG=/path/to/wikiconfig.py`
-- current directory, file `wikiconfig_local.py`
-- current directory, file `wikiconfig.py`
-
-Initializing index and/or storage
----------------------------------
-If you have an existing storage AND a valid index (for this storage’s content and for this moin version),
-you can skip this section.
-
-If you start from scratch, ie no storage and no index created yet,
-you need to create an empty storage and an empty index::
-
- # create storage and index:
- moin index-create -s -i
-
-Loading some items
-------------------
-If you don't want to have a completely empty wiki, you can optionally load
-some example items into the storage like this::
+ <python> quickinstall.py
 
- # load some example items:
- moin load --file contrib/serialized/items.moin
-
-Building the index
-------------------
-If you have some items in your storage, but no index built yet, you need
-to build an index::
-
- moin index-build
-
-
-Installing PIL / pillow
-~~~~~~~~~~~~~~~~~~~~~~~
-For some image processing functions that MoinMoin uses like resizing and rotating,
-you need PIL, which is the Python Imaging Library (sometimes also referred to as
-python-imaging). Instead of PIL, you can also use pillow, which is a compatible
-fork of PIL (with more active maintenance and it also has been ported to Python 3).
+ OR
 
-Windows users who want to install PIL should skip the remainder of this section and read
-Troubleshooting -- PIL Installation Under Windows below.
-
-If you install PIL with pip, then pip will try to find a jpeg support library and associated development
-headers on your system and if you do not have them, there will be no jpeg support in PIL.
-So, if you want jpeg support, make sure you have the jpeg libs/headers::
+ <python> quickinstall.py <path-to-venv> --download-cache <path-to-cache>
 
- # install jpeg library and development headers:
- sudo apt-get install libjpeg62-dev  # Ubuntu / Debian-based
- yum install libjpeg-turbo-devel  # Fedora / Redhat-based
-
-Now activate your virtual environment and install PIL into it::
+The above will download all dependent packages to a cache,
+install the packages in a virtual environment, and compile the translations
+(`*.po` files) to binary `*.mo` files. This process may take several minutes.
 
- pip install pil  # for Linux (or other POSIX OSes)
+The default cache and virtual environment directory names are:
 
-Alternatively, if you prefer to use pillow::
+ * ~/.pip/pip-download-cache # windows: ~\\pip\\pip-download-cache
+ * ../<PROJECT>-venv-<PYTHON>/
 
- pip install pillow  # for Linux (or other POSIX OSes)
+where <PROJECT> is the name of the project root directory, and <PYTHON>
+is the name of your python interpreter. As noted above, the default
+names may be overridden.
 
+Check the output of quickinstall.py to determine whether there were
+fatal errors. The output messages will normally state that stdout
+and stderr messages were written to a file, a few key success/failure
+messages will be extracted and written to the terminal window, and
+finally a message to type "m" to display a menu.
+
+If there are failure messages, see the troubleshooting section below.
+
+Typing 'm" will display a menu similar to::
+
+    usage: "m <target>" where <target> is:
+
+    quickinstall    update virtual environment with required packages
+    docs            create moin html documentation
+    extras          install OpenID, Pillow, pymongo, sqlalchemy, ldap, upload.py
+    interwiki       refresh contrib\interwiki\intermap.txt (hg version control)
+    log <target>    view detailed log generated by <target>, omit to see list
+
+    new-wiki        create empty wiki
+    sample          create wiki and load sample data
+    restore *       create wiki and restore wiki\backup.moin *option, specify file
+    import <dir>    import a moin 1.9 wiki/data instance from <dir>
+
+    run             run built-in wiki server with local OS and logging options
+    backup *        roll 3 prior backups and create new backup *option, specify file
+
+    css             run Stylus to update CSS files
+    tests           run tests, output goes to pytest.txt and pytestpep8.txt
+    coding-std      correct scripts that taint the repository with trailing spaces..
+    api             update moin api docs (files are under hg version control)
+    dist            delete wiki data, then create distribution archive in /dist
+
+    del-all         same as running the 4 del-* commands below
+    del-orig        delete all files matching *.orig
+    del-pyc         delete all files matching *.pyc
+    del-rej         delete all files matching *.rej
+    del-wiki        create a backup, then delete all wiki data
+
+While most of the above menu choices may be executed now, new users should
+do::
+
+ m sample
+
+to create a wiki instance and load it with sample data. Next, run the
+built-in wiki server::
+
+ m run
+
+As the server starts, about 20 log messages will be output to the
+terminal window.  Point your browser to http://127.0.0.1:8080, the
+sample Home page will appear and more log messages will be output
+to the terminal window. Do a quick test by accessing some of the
+demo items and do a modify and save. If all goes well, your installation
+is complete. The built-in wiki server may be stopped by typing ctrl-C
+in the terminal window.
+
+Next Steps
+==========
+
+If you plan on contributing to the moin2 project, there are more
+instructions waiting for you under the Development topic.
+
+If you plan on just using moin2 as a desktop wiki (and maybe
+help by reporting bugs), then some logical menu choices are:
+
+ * `m docs` - to create docs, see User tab, Documentation (local)
+ * `m extras` - to install Pillow for manipulating images
+ * `m del-wiki` - get rid of the sample data
+ * `m new-wiki` or `m import ...` - no data or moin 1.9 data
+ * `m backup` - backup wiki data as needed or as scheduled
+
+Warning: Backing up data at this point may provide a false sense
+of security because no migration tool has been developed to migrate
+data between moin2 versions.  In its current alpha state, there
+may be code changes that impact the structure of the wiki data or
+indexes. Should this occur, you must start over with an empty
+wiki and somehow copy and paste the contents of all the old wiki
+items into the new wiki. While no such changes are planned,
+they have happened in the past and may happen in the future.
+
+If you installed moin2 by cloning the Moin2 Mercurial repository,
+then you will likely want to install updates on a periodic basis.
+To determine if there are updates available, open a terminal
+window or command prompt, cd to your project root, and enter the
+command below::
+
+  hg incoming
+
+If there are any updates, a brief description of each update will
+be displayed. To add the updates to your cloned repository, do::
+
+  hg pull -u
 
 Troubleshooting
----------------
+===============
 
 PyPi down
-~~~~~~~~~
+---------
 Now and then, PyPi might be down or unreachable.
 
 There are mirrors b.pypi.python.org, c.pypi.python.org, d.pypi.python.org
@@ -175,49 +160,45 @@
  [global]
  index-url = http://c.pypi.python.org/simple
 
-In case that doesn't work either, try our mini pypi that should have all
-packages you need for moin::
-
- # put this into ~/.pip/pip.conf
- [global]
- index-url = http://pypi.moinmo.in/simple
-
 Bad Network Connection
-~~~~~~~~~~~~~~~~~~~~~~
-If you have a poor or limited network connection, you may run into trouble with the commands issued by
-the quickinstall script.
-You may see tracebacks from pip, timeout errors, etc. See the output of the quickinstall script.
-
-If this is the case, try it manually::
-
- # create a virtual environment:
- virtualenv env
-
- # enter your virtual environment:
- source env/bin/activate
+----------------------
+If you have a poor or limited network connection, you may run into
+trouble with the commands issued by the quickinstall.py script.
+You may see tracebacks from pip, timeout errors, etc. within the output
+of the quickinstall script.
 
- # confirm the problems by running:
- pip install -e .
-
-Now install each package into your virtual env manually:
-
-* Find the required packages by looking at "install_requires" within `setup.py`.
-* Download each required package from http://pypi.python.org/
-* Install each of them individually::
-
-    pip install package.tar
+If this is the case, you may try rerunning the "python quickinstall.py"
+script multiple times. With each subsequent run, packages that are
+all ready cached (view the contents of pip-download-cache) will not
+be downloaded again. Hopefully, any temporary download errors will
+cease with multiple tries.
 
-* Now try again::
-
-    pip install -e .
-
-Repeat these steps until you don't see fatal errors.
+ActiveState Python
+------------------
+While ActiveState bundles pip and virtualenv in its distribution,
+there are two missing files. The result is the following error
+messages followed by a traceback::
 
-PIL/pillow Installation Under Windows
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-PIL version 1.1.7 does not install correctly via "pip install pil" on Windows.
-Some users have had success using "pip install pillow", a fork of PIL fixing
-a packaging issue. Other users have resorted to installing PIL 1.1.6 in the
-main Python directory using the Windows installers available at
-http://www.pythonware.com/products/pil/
 
+  Cannot find sdist setuptools-*.tar.gz
+  Cannot find sdist pip-*.tar.gz
+
+To install the missing files, do the following and then rerun
+"python quickinstall.py"::
+
+  \Python27\Scripts\pip.exe uninstall virtualenv
+  \Python27\Scripts\easy_install virtualenv
+
+Other Issues
+------------
+
+If you encounter some other issue not described above, try
+researching the unresolved issues at
+https://bitbucket.org/thomaswaldmann/moin-2.0/issues?status=new&status=open.
+If you find a similar issue, please
+add a note saying you also have the problem and add any new
+information that may assist in the problem resolution.
+
+If you cannot find a similar issue please create a new issue.
+Or, if you are not sure what to do, join us on IRC at #moin-dev
+and describe the problem you have encountered.

--- a/docs/admin/requirements.rst	Thu Dec 19 14:57:19 2013 -0700
+++ b/docs/admin/requirements.rst	Sun Jan 12 11:45:03 2014 -0700
@@ -2,15 +2,43 @@
 Requirements
 ============
 
-MoinMoin requires Python 2.7.x.
-We usually test using CPython and this is what we recommend.
+MoinMoin requires Python 2.7.x. A CPython distribution is
+recommended because it will likely be the fastest and most stable.
+Most developers use a CPython distribution for testing.
+Typical linux distributions will either have Python 2.7 installed by
+default or will have a package manager that will install Python 2.7
+as a secondary Python.
+Windows users may download CPython distributions from  http://www.python.org/ or
+http://www.activestate.com/.
 
-You can also try PyPy, it seems to work.
+An alternative implementation of Python, PyPy, is available
+from http://pypy.org/.
+
+The `virtualenv` Python package is also required. The
+installation process for `virtualenv` varies with your OS and
+Python distribution.
+Many linux distributions have a package manager that may do
+the installation. Windows users (and perhaps others) may download
+setuptools from https://pypi.python.org/pypi/setuptools. Once setuptools is installed, do "`easy_install virtualenv`". Current ActiveState
+distributions include virtualenv in the installation bundle.
+If all else fails, try Google.
+
+Mercurial (hg) is required should you wish to contribute
+patches to the moin2 development effort. Even if you do not
+intend to contribute, Mercurial is highly recommended as it
+will make it easy for you to obtain fixes and enhancements
+from the moin2 repositories. Mercurial can be installed
+with most linux package managers or downloaded
+from http://mercurial.selenic.com/. As an alternative,
+most Windows users will prefer to install TortoiseHG
+(includes Mercurial) from
+http://tortoisehg.bitbucket.org/.
+
 
 Servers
 =======
 
-For moin, you can use any server compatible with WSGI:
+For moin2, you can use any server compatible with WSGI:
 
 * the builtin "moin" server is recommended for desktop wikis, testing,
   debugging, development, adhoc-wikis, etc.
@@ -24,24 +52,15 @@
 Dependencies
 ============
 
-For dependency information, please see setup.py.
-
-If you use easy_install or pip or our ``quickinstall`` script, then
-dependencies are usually automatically dealt with.
-
+Dependent packages will be automatically downloaded and installed during the moin2 installation process. For a list of dependencies, see setup.py.
 
 Clients
 =======
 On the client side, you need:
 
-* a decent web browser that supports W3C standards HTML 5 and CSS 2.1 as well
-  as JavaScript:
+* a web browser that supports W3C standards HTML 5, CSS 2.1, and JavaScript:
 
-  - any current version of Firefox, Chrome, Opera, Safari, Internet Explorer
-    (IE9 or IE10) should work.
-  - usage of older Internet Explorer versions is not recommended and not
-    supported because they are known for causing issues.
-    For Windows 7 (or 8) Microsoft provides IE9 or IE10.
-* Java browser plugin (optional, needed if you want to use TWikiDraw or
-  AnyWikiDraw drawing applets).
+  - any current version of Firefox, Chrome, Opera, Safari, Maxthon, Internet Explorer (IE9 or newer).
+  - use of older Internet Explorer versions is not recommended and not supported.
 
+* a Java browser plugin is required only if you want to use the TWikiDraw or AnyWikiDraw drawing applets.

--- a/docs/devel/development.rst	Thu Dec 19 14:57:19 2013 -0700
+++ b/docs/devel/development.rst	Sun Jan 12 11:45:03 2014 -0700
@@ -23,119 +23,174 @@
 
 * http://bitbucket.org/thomaswaldmann/moin-2.0/issues
 
-Code Repositories (using Mercurial DVCS):
+Code Repositories (using Mercurial DVCS http://mercurial.selenic.com/):
 
 * http://hg.moinmo.in/moin/2.0  (main repository)
 * http://bitbucket.org/thomaswaldmann/moin-2.0  (bitbucket mirror for your
   convenience, simplifying forking and contributing)
 
-Code review (get feedback about code changes):
+Code review (always use this to get feedback about code changes):
 
-* http://codereview.appspot.com/
+* http://code.google.com/p/rietveld/wiki/CodeReviewHelp
+* http://codereview.appspot.com/ (list of current codereview activity)
 
-Pastebin (temporary stuff - do not use for code reviews, do not use from issue
-tracker or for any long-term needed stuff):
+Pastebin (temporary storage - do not use for code review or any long-term need):
 
 * http://rn0.ru/
 
-
 Typical development workflow
 ============================
 
-This is the typical workflow for non-trivial changes and developers that likely
-want to contribute more than one change:
-
-* create your own development environment (only once):
-
-  - create a google account (if you don't have one already, it's free), so you
-    can use codereview.appspot.com
-  - create a bitbucket account (if you don't have one already, it's free)
-  - clone ("fork") the main repository on bitbucket, so you have your own bb
-    repo to publish your work
-  - clone your own bb repo to your local development machine
-  - do a development install from your local repo - read the moin2 install docs
-    for detailled instructions.
-  - join #moin-dev IRC channel and stay there whenever possible
-
-* find some stuff to work on:
-
-  - look at the issue tracker to find some stuff you can solve
-  - in case you want to work on some (non-trivial) new issue or idea that is
-    not on the issue tracker yet, first create an issue there with a detailled
-    description of it
-  - discuss with / get feedback from other developers on the #moin-dev IRC
-    channel
-
-* work on the stuff:
+This is the typical workflow for anyone that wants to contribute to the development of Moin2.
 
-  - to avoid double work, add a comment on the issue tracker that you are
-    working on that issue
-  - work in your local repo on your local development machine (make sure you
-    work in the right branch)
-  - concentrate on one issue / one topic, create a clean set of changes (that
-    means not doing more than needed to fix the issue, but also it means fixing
-    the issue completely and everywhere)
-  - write good, clean, easy-to-understand code.
-  - obey PEP-8
-  - do not fix or change unrelated stuff while working, but rather create new
-    issues on the tracker, so it's not forgotten
-  - regularly run the unit tests ("make test"), the amount of failing tests
-    shall not increase due to your changes
-  - if you fix something that had no test, first try to write a (correct, but
-    still failing) test for it, then fix the code and see the test not failing
-    any more
-  - if you implement new functionality, write tests for it first, then
-    implement it
-  - do an own review of your changes. Use hg diff, hg status - read everything
-    you changed - slowly, looking for stuff that can be improved. Fix
-    everything you find that way before requesting feedback from others.
-  - get feedback from other developers about your changes:
-   
-    + put them on codereview (just run python upload.py in your local repo -
-      if it is not first upload, reuse the same ID to update the already
-      existing codereview)
-    + post the codereview URL to #moin-dev IRC channel asking for review
-    + if you want to get feedback on non-code stuff, either use the issue
-      tracker or a pastebin (only use pastebins for temporary stuff)
-  - repeat until everybody is happy with it
-  - do some final testing - practically and using the unit tests
-  - commit your changes to your local repo, use a meaningful commit comment
+create your development environment
+-----------------------------------
 
-* publish your stuff and request it being merged:
+* if you do not have a bitbucket account, create one at https://bitbucket.org
+* fork the main repository on bitbucket: https://bitbucket.org/thomaswaldmann/moin-2.0
+* clone the main repository to your local development machine
 
-  - push the changeset to your public bitbucket repo
-  - create a pull request to request that your changes get pulled into the
-    main repository
-  - optionally, tell about it on the IRC channel
-  - if you fixed an issue from the issue tracker, make sure the issue gets
-    closed after your fix has been merged.
+  - cd to parent directory of your future repo
+  - "hg clone https://bitbucket.org/thomaswaldmann/moin-2.0 moin-2.0"
+* ensure you are in default branch "hg update default"
+* create the virtualenv and download packages: "python quickinstall.py"
+* create a wiki instance and load sample data: "m sample"
+* start the built-in server: "m run"
+* point your browser at http://127.0.0.1:8080/ to access your development wiki
+* key ctrl+C to stop the built-in server
 
+add more tools, exercise tools
+------------------------------
+
+* if you do not have a google account, create one at http://codereview.appspot.com
+* download upload.py from http://code.google.com/p/rietveld/wiki/CodeReviewHelp
+  to your repo root, then practice using codereview:
+* make a trivial change to any source file, do "python upload.py"
+* inspect your patch set at http://codereview.appspot.com, add a comment
+* click the "Publish and Mail comments" link, check your email inbox
+* make another trivial change to same source file, do "python upload.py -i nnn"
+  where nnn is ID of existing codereview
+* inspect your patch set again, compare patch set 1 to patch set 2
+* click the "Delete" link to delete patchset 2
+* revert the changes on your local repo "hg revert --all"
+* run the unit tests ("m tests"), note any existing test failures
+* install NodeJS with Linux package manager; Windows users may download from http://nodejs.org/download/
+* install stylus
+
+  - "sudo npm install stylus -g" or windows "npm install stylus -g"
+  - "stylus -V"  # show version number to prove it works
+* run Stylus to regenerate CSS files: "m css", verify nothing changed: "hg diff"
+* run "m coding-std" to see if there are any coding errors
+* run "m api" to see any uncommitted API doc changes
+* use "hg revert --all" to revert any changes from above
+* optional: create local docs "m docs"
+* set options on your favorite editor or IDE
+
+  - convert tabs to 4 spaces
+  - delete trailing blanks on file save
+  - use unix line endings (use Windows line endings on .bat and .cmd files)
+  - use mono-spaced font for editing
+* if you are new to mercurial, read a tutorial (http://hginit.com/),
+  consider printing a cheatsheet
+* if you want a Python IDE, try http://www.jetbrains.com/pycharm/ Free Community Edition
+* if you want a graphical interface to Mercurial, install SourceTree (best for mac) or TortoiseHG (best for Windows)
+* join #moin-dev IRC channel; ask questions, learn what other developers are doing
+
+find a task to work on
+----------------------
+
+* look at the issue tracker to find a task you can solve
+* in case you want to work on some (non-trivial) new issue or idea that is
+  not on the issue tracker, create an issue with a detailed description
+* discuss your chosen task with other developers on the #moin-dev IRC
+  channel
+* to avoid duplicate work, add a comment on the issue tracker that you are
+  working on that issue
+* just before you start to code changes, update your local repo: "hg pull -u"
+
+develop a testing strategy
+--------------------------
+
+* if you fix something that had no test, first try to write a correct,
+  but failing test for it, then fix the code and see a successful test
+* if you implement new functionality, write tests for it first, then
+  implement it
+* make a plan for using a browser to test your changes; which wiki pages are
+  effected, how many browsers must be tested
+* run "m tests" to determine if there are any existing test failures before you make changes
+
+develop a working solution
+--------------------------
+
+* work in your local repo on your local development machine
+  (be sure you work in the right branch)
+* concentrate on one issue / one topic, create a clean set of changes
+  (that means not doing more than needed to fix the issue, but also it
+  means fixing the issue completely and everywhere)
+* write good, clean, easy-to-understand code
+* obey PEP-8
+* do not fix or change code unrelated to your task, if you find
+  unrelated bugs, create new issues on the tracker
+* regularly run the unit tests ("m tests"), the amount of failing tests
+  shall not increase due to your changes
+
+review your working solution
+----------------------------
+
+* use hg diff, hg status - read everything you changed - slowly, look for
+  things that can be improved
+
+  - if you have TortoiseHG or SourceTree, use those graphical tools to review changes
+* look for poor variable names, spelling errors in comments, accidental addition
+  or deletion of blank lines, complex code without comments, missing/extra spaces
+* fix everything you find before requesting feedback from others
+* run tests again "m tests"
+
+get feedback from other developers
+----------------------------------
+
+* add changes to codereview: run "python upload.py" in your local repo
+
+  - to update a codereview, "python upload.py -i nnn" where nnn is ID
+* carefully review your changes again on codereview
+
+  - if you find errors, delete the patchset, fix and upload again
+* if you have questions or want to explain something, add comments and click
+  "Publish+Mail Comments"
+* post the codereview URL to #moin-dev IRC channel asking for review
+* repeat until everybody is happy with your changes
+
+publish your change
+-------------------
+
+* do some final testing - practically and using the unit tests
+* commit your changes to your local repo, use a concise commit comment
+  describing the change
+* pull any changes made by others from the main repo on Bitbucket, then
+  merge and commit
+* push the changeset to your public bitbucket repo
+* create a pull request so your changes will get pulled into the
+  main repository
+* optionally, request a pull on the IRC channel
+* if you fixed an issue from the issue tracker, be sure the issue gets
+  closed after your fix has been pulled into main repo.
+* celebrate, loop back to "find a task to work on"
+
+update your virtualenv
+----------------------
+
+Every week or so, do "m quickinstall" to install new releases of
+dependent packages. If any new packages are installed, do a
+quick check for breakages by running tests, starting the
+build-in server, modify an item, etc.
 
 Alternate contribution workflows
 ================================
-If the above workflow looks like overkill (e.g. for simple changes) or you
-can't work with the tools we usually use, you can also do it like this:
-
-* find an existing issue on the issue tracker about the issue you were fixing
-  (or create a new one), make sure to give (or update) all the details, like:
-
-  - precise version number / changeset hashes of the original code your patch
-    is based on
-  - precise description of the issue, how to reproduce it, tracebacks, ...
-  - why your fix is correct / how you tested it
-* create a patch using the diff tool, attach patch.txt to the issue:
-
-    diff -urN originalcodetree/ modifiedcodetree/ > patch.txt
-
-* if you fixed an issue from the issue tracker, make sure the issue gets
-  closed after your fix has been committed to the main repo.
-
-For trivial fixes (like typos), you can also try just grabbing a developer
-on IRC, telling filename, line number and get it fixed by him.
-
-Note: if developers find that the required changes are not that simple or are
-potentially causing other issues, codereview or other parts of the full
-workflow might be needed.
+If the above workflow looks like overkill (e.g. for simple changes)
+or you can't work with the tools we usually use, then just create or
+update an issue on the issue tracker
+https://bitbucket.org/thomaswaldmann/moin-2.0/issues)
+or join us on IRC #moin-dev.
 
 
 MoinMoin architecture
@@ -159,10 +214,6 @@
 * CKeditor, the GUI editor for (x)html
 * TWikiDraw, AnyWikiDraw, svgdraw drawing tools
 
-.. todo::
-
-   add some nice gfx
-
 
 How MoinMoin works
 ==================
@@ -237,7 +288,8 @@
 -------------------------
 How does moin know what the HTML rendering of an item looks like?
 
-Each Item has some contenttype that is stored in the metadata, also called the input contenttype.
+Each Item has some contenttype that is stored in the metadata, also called
+the input contenttype.
 We also know what we want as output, also called the output contenttype.
 
 Moin uses converters to transform the input data into the output data in
@@ -260,7 +312,7 @@
 Finally, the dom-tree will reach the output converter, which will transform it
 into the desired output format, such as `text/html`.
 
-This is just one example of a supported transformation. There are quite a few 
+This is just one example of a supported transformation. There are quite a few
 converters in `MoinMoin.converter` supporting different input formats,
 dom-dom transformations and output formats.
 
@@ -284,7 +336,7 @@
 To run the tests, activate your virtual env and invoke py.test from the
 toplevel directory::
 
-    make test  # easiest way (all tests, pep8, skipped info)
+    m tests  # easiest way (all tests, pep8, skipped info)
     py.test --pep8  # run all tests, including pep8 checks
     py.test -rs  # run all tests and outputs information about skipped tests
     py.test -k somekeyword  # run the tests matching somekeyword only
@@ -318,9 +370,7 @@
 
 Creating docs
 -------------
-Sphinx can create all kinds of documentation formats. The most
-popular ones are::
+Sphinx can create all kinds of documentation formats. The most common are
+the local HTML docs that are linked to under the User tab.
 
-    cd docs
-    make html  # create html docs (to browse online or in the filesystem)
-
+    m docs

--- a/make.py	Thu Dec 19 14:57:19 2013 -0700
+++ b/make.py	Sun Jan 12 11:45:03 2014 -0700
@@ -81,7 +81,7 @@
 usage: "%s <target>" where <target> is:
 
 quickinstall    update virtual environment with required packages
-docs            create local Sphinx html documentation
+docs            create moin html documentation
 extras          install OpenID, Pillow, pymongo, sqlalchemy, ldap, upload.py
 interwiki       refresh contrib\interwiki\intermap.txt (hg version control)
 log <target>    view detailed log generated by <target>, omit to see list
@@ -97,7 +97,7 @@
 css             run Stylus to update CSS files
 tests           run tests, output goes to pytest.txt and pytestpep8.txt
 coding-std      correct scripts that taint the repository with trailing spaces..
-api             update Sphinx API docs (files are under hg version control)
+api             update moin api docs (files are under hg version control)
 dist            delete wiki data, then create distribution archive in /dist
 
 del-all         same as running the 4 del-* commands below