move developer section from CONTRIBUTING into its own document

CONTRIBUTING.md

@@ -7,83 +7,33 @@ you need to respect:
 * no hard-wired external services
 * no support for ancient browsers (e.g. IE6-9)
 
-Reporting Issues
+If you create a feature request, start a new branch. If you fix an issue,
-----------------
+start off the *master* branch and pull request against the master. I'll
-
+cherry-pick/backport the fix onto the current legacy (maintenance) release.
-### Disqus import fails
-
-If `isso import /path/to/disqus.xml` fails, please do *NOT* attach the raw
-dump file to GH:Issues. Please anonymize all IP addresses inside the `<ipAddress>`
-tag first, as second step, replace all email addresses with a generic one (
-email tag).
-
-### embed.min.js-related issues
-
-In case of a JavaScript traceback, please setup Isso in development mode
-described below. Otherwise it is very hard to "guess" the reason.
-
-### isso-related issues
-
-Copy and paste traceback into a ticket and provide some details of your usage.
-
-
-Development
------------
-
-If you want to hack on Isso or track down issues, there's an alternate
-way to set up Isso. It requires a lot more dependencies and effort.
-
-Requirements:
 
-- Python 2.6, 2.7 or 3.3
+To set up a development environment, see
-- Ruby 1.8 or higher
+[docs/DEVELOPMENT.md](https://github.com/posativ/isso/blob/master/docs/DEVELOPMENT.md)
-- Node.js, [NPM](https://npmjs.org/) and [Bower](http://bower.io/)
 
-On Debian/Ubuntu install the following packages
 
-    ~> sudo aptitude install python-setuptools python-dev npm ruby
+Reporting Issues
-    ~> ln -s /usr/bin/nodejs /usr/bin/node
+----------------
-
-Get the repository:
-
-    ~> git clone https://github.com/posativ/isso.git
-    ~> cd isso/
-
-Install `virtualenv` and create a new environment for Isso (recommended):
-
-    ~> pip install virtualenv
-    ~> virtualenv .
-    ~> source ./bin/activate
-
-Install Isso dependencies:
-
-    ~> python setup.py develop
-    ~> isso run
-
-Compile SCSS to CSS:
-
-    ~> gem install sass
-    ~> scss --watch isso/css/isso.scss
-
-Install JS components:
 
-    ~> cd isso/js
+*   **Disqus import fails**
-    ~> bower install almond q requirejs requirejs-domready requirejs-text
 
+    If `isso import /path/to/disqus.xml` fails, please do *NOT* attach the raw
+    dump file to GH:Issues. Please anonymize all IP addresses inside the
+    `<ipAddress>` tag first, as second step, replace all `<email>` addresses
+    with a generic one.
 
-Integration
+    If you can't do this, please send the dump to `info@posativ.org` (you find
------------
+    my GPG key on the servers).
 
-```html
+*   **embed.min.js-related issues**
-<script src="/isso/js/config.js"></script>
-<script data-main="/isso/js/embed" src="/isso/js/components/requirejs/require.js"></script>
-```
 
+    If you get a cryptic JavaScript error in the console, embed `embed.dev.js`
+    instead of `embed.min.js` and create an issue with ±10 lines of code around
+    the error.
 
-Optimization
+*   **isso-related issues**
-------------
 
-    ~> npm install -g requirejs uglifyjs
+    Copy and paste traceback into a ticket and provide some details of your usage.
-    ~> cd isso/js
-    ~> r.js -o build.embed.js
-    ~> r.js -o build.count.js

README.md

@@ -129,13 +129,14 @@ This functionality is already included when you embed `embed.min.js`, do
 *not* mix `embed.min.js` and `count.min.js` in a single document.
 
 
-
+Documentation
-Other Documents
+-------------
----------------
 
 - [Configuration](https://github.com/posativ/isso/blob/master/docs/CONFIGURATION.rst)
 - [API overview](https://github.com/posativ/isso/raw/master/docs/API.md)
 - [uWSGI usage](https://github.com/posativ/isso/blob/master/docs/uWSGI.md)
+- [Contributing](https://github.com/posativ/isso/blob/master/CONTRIBUTING.md)
+- [Development](https://github.com/posativ/isso/blob/master/docs/DEVELOPMENT.md)
 
 
 Alternatives

docs/DEVELOPMENT.md

@@ -0,0 +1,60 @@
+Development
+===========
+
+If you want to hack on Isso or track down issues, there's an alternate
+way to set up Isso. It requires a lot more dependencies and effort.
+
+Requirements:
+
+- Python 2.6, 2.7 or 3.3
+- Ruby 1.8 or higher
+- Node.js, [NPM](https://npmjs.org/) and [Bower](http://bower.io/)
+
+On Debian/Ubuntu install the following packages
+
+    ~> sudo aptitude install python-setuptools python-dev npm ruby
+    ~> ln -s /usr/bin/nodejs /usr/bin/node
+
+Get the repository:
+
+    ~> git clone https://github.com/posativ/isso.git
+    ~> cd isso/
+
+Install `virtualenv` and create a new environment for Isso (recommended):
+
+    ~> pip install virtualenv
+    ~> virtualenv .
+    ~> source ./bin/activate
+
+Install Isso dependencies:
+
+    ~> python setup.py develop
+    ~> isso run
+
+Compile SCSS to CSS:
+
+    ~> gem install sass
+    ~> scss --watch isso/css/isso.scss
+
+Install JS components:
+
+    ~> cd isso/js
+    ~> bower install almond q requirejs requirejs-domready requirejs-text
+
+
+Integration
+-----------
+
+```html
+<script src="/isso/js/config.js"></script>
+<script data-main="/isso/js/embed" src="/isso/js/components/requirejs/require.js"></script>
+```
+
+
+Optimization
+------------
+
+    ~> npm install -g requirejs uglifyjs
+    ~> cd isso/js
+    ~> r.js -o build.embed.js
+    ~> r.js -o build.count.js