diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fee5c85..812b33d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -7,83 +7,33 @@ you need to respect: * no hard-wired external services * no support for ancient browsers (e.g. IE6-9) +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. + +To set up a development environment, see +[docs/DEVELOPMENT.md](https://github.com/posativ/isso/blob/master/docs/DEVELOPMENT.md) + + Reporting Issues ---------------- -### Disqus import fails +* **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 `` -tag first, as second step, replace all email addresses with a generic one ( -email tag). + 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 + `` tag first, as second step, replace all `` addresses + with a generic one. -### embed.min.js-related issues + If you can't do this, please send the dump to `info@posativ.org` (you find + my GPG key on the servers). -In case of a JavaScript traceback, please setup Isso in development mode -described below. Otherwise it is very hard to "guess" the reason. +* **embed.min.js-related issues** -### isso-related issues + 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. -Copy and paste traceback into a ticket and provide some details of your usage. +* **isso-related issues** - -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 - - -``` - - -Optimization ------------- - - ~> npm install -g requirejs uglifyjs - ~> cd isso/js - ~> r.js -o build.embed.js - ~> r.js -o build.count.js + Copy and paste traceback into a ticket and provide some details of your usage. diff --git a/README.md b/README.md index e9641d9..a2800bd 100644 --- a/README.md +++ b/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. - -Other Documents ---------------- +Documentation +------------- - [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 diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md new file mode 100644 index 0000000..b713d34 --- /dev/null +++ b/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 + + +``` + + +Optimization +------------ + + ~> npm install -g requirejs uglifyjs + ~> cd isso/js + ~> r.js -o build.embed.js + ~> r.js -o build.count.js