Add CONTRIBUTING.md and update developer docs

CONTRIBUTING.md

@@ -0,0 +1,41 @@
+# Contributing
+
+The developer docs are here:
+https://conversejs.org/docs/html/development.html
+
+## Quickstart
+
+### With GNU Make:
+
+```
+make serve_bg
+make watch
+```
+
+Go to http://localhost:8000/dev.html
+
+Then modify `dev.html` so that `converse.initialize()` is called with relevant settings.
+
+
+### Without GNU Make:
+
+```
+npm install
+npm run serve &
+npm run watch
+```
+
+Webpack will "watch" the source files and automatically recreate the build if they
+are modified. So you don't have to do anything to rebuild whenever you've
+change something in a file but you will have to manually reload the browser tab
+to see the changes in the browser.
+
+
+## Live reloading
+
+If you want to have live reloading whenever any of the source files change, you
+can run ``make devserver`` (or ``npm run devserver``).
+
+Then go to http://localhost:8080
+
+Then modify `webpack.html` so that `converse.initialize()` is called with relevant settings.

Makefile

@@ -3,7 +3,6 @@ BOOTSTRAP		= ./node_modules/
 BUILDDIR		= ./docs
 KARMA			?= ./node_modules/.bin/karma
 CLEANCSS		?= ./node_modules/clean-css-cli/bin/cleancss
-HTTPSERVE	 	?= ./node_modules/.bin/http-server
 HTTPSERVE_PORT	?= 8000
 INKSCAPE		?= inkscape
 INSTALL			?= install
@@ -52,11 +51,11 @@ help:
 
 .PHONY: serve
 serve: node_modules dist
-	$(HTTPSERVE) -p $(HTTPSERVE_PORT) -c-1
+	npm run serve -- -p $(HTTPSERVE_PORT)
 
 .PHONY: serve_bg
 serve_bg: node_modules
-	$(HTTPSERVE) -p $(HTTPSERVE_PORT) -c-1 -s &
+	npm run serve -- -p $(HTTPSERVE_PORT) -s &
 
 certs:
 	mkdir certs
@@ -151,7 +150,7 @@ dev: node_modules
 
 .PHONY: devserver
 devserver: node_modules
-	npm run serve
+	npm run devserver
 
 ########################################################################
 ## Builds
@@ -257,7 +256,7 @@ docsdev: ./bin/activate requirements.txt
 html: doc
 
 .PHONY: doc
-doc: node_modules docsdev apidoc
+doc: node_modules docsdev
 	rm -rf $(BUILDDIR)/html
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	make apidoc

docs/source/setup_dev_environment.rst

@@ -8,6 +8,8 @@
 Setting up a dev environment
 ============================
 
+.. _`webserver`:
+
 Installing the 3rd party dependencies
 =====================================
 
@@ -19,64 +21,73 @@ repository:
     git clone https://github.com/conversejs/converse.js.git
     cd converse.js
 
-
 We use development tools which depend on Node.js and NPM (the Node package manager).
 
 It's recommended that you use `NVM <https://github.com/nvm-sh/nvm>`_ (the Node version manager)
 to make sure you have the right version of Node.
 
 Refer to the `NVM Github page <https://github.com/nvm-sh/nvm#install--update-script>`_ for instructions on how to install it.
 
-Once NVM is installed, you can run the following inside your checkout of the Converse Git repository:
+To set up a Converse development environment, you now run the following:
 
 ::
 
-    nvm install
+    make serve_bg
+    make watch
 
-.. note::
-    You will always have to first run ``nvm install`` in a new terminal session in order to use the
-    recommended version of Node before working on Converse.
+Alternatively, if you're using Windows, or don't have GNU Make installed, you can run the
+following:
 
+::
 
-To set up the Converse development environment, you now run ``make dev``.
+    npm install
+    npm run serve &
+    npm run watch
 
-::
 
-    make dev
+Then go to http://localhost:8000/dev.html to load Converse.
 
-Alternatively, if you're using Windows, or don't have GNU Make installed, you can run the
-following:
+Modify `dev.html <https://github.com/conversejs/converse.js/blob/master/dev.html>`_
+so that `converse.initialize()` is called with the relevant settings.
 
-::
+Webpack will "watch" the source files and automatically recreate the build if they
+are modified. So you don't have to do anything to rebuild whenever you've
+change something in a file but you will have to manually reload the browser tab
+to see the changes in the browser.
+
+Live reloading
+--------------
+
+If you want to have live reloading whenever any of the source files change, you
+can run ``make devserver`` (or ``npm run devserver``) which uses `webpack-dev-server <https://github.com/webpack/webpack-dev-server>`_.
 
-  npm install
-  npm run lerna
+Then go to http://localhost:8080.
 
-This will install the Node development tools and Converse's dependencies.
+Instead of ``dev.html``, `webpack.html <https://github.com/conversejs/converse.js/blob/master/webpack.html>`_
+is now being used as the served HTML file, and you'll need to modify that file to
+change the settings passed to ``converse.initialize``.
 
-The front-end dependencies are those JavaScript files on which
-Converse directly depends and which will be loaded in the browser as part of
-the bundle in ``dist/converse.js`` (or ``dist/converse.min.js``).
+Troubleshooting
+---------------
 
-To see the 3rd party dependencies (not just the front-end dependencies, but
-also ones necessary for development tasks like making builds), take a look at
-the list under the ``devDependencies`` in `package.json <https://github.com/jcbrand/converse.js/blob/master/package.json>`_.
+After running ``make watch``, you should now have a new *node_modules* directory
+which contains all the external dependencies of Converse.
 
-.. note::
-    After running ```make dev```, you should now have a new *node_modules* directory
-    which contains all the external dependencies of Converse.
-    If this directory does NOT exist, something must have gone wrong.
-    Double-check the output of ```make dev``` to see if there are any errors
-    listed. For support, you can ask in our chatroom: `[email protected] <xmpp:[email protected]>`_.
+If this directory does NOT exist, something must have gone wrong.
 
-    If you don't have an XMPP client installed, follow this link to
-    `conversejs.org <https://conversejs.org/fullscreen#converse/[email protected]>`_
-    where you can log in and be taken directly to the chatroom.
+Double-check the output of ``make watch`` to see if there are any errors
+listed.
+
+For support, you can ask in our chatroom: `[email protected] <xmpp:[email protected]>`_.
+
+If you don't have an XMPP client installed, follow this link to
+`conversejs.org <https://conversejs.org/fullscreen#converse/[email protected]>`_
+where you can log in and be taken directly to the chatroom.
 
 
 .. _`dependency-libsignal`:
 
-Libsignal
+libsignal
 ---------
 
 If you want OMEMO encryption, you need to load `libsignal <https://github.com/signalapp/libsignal-protocol-javascript>`_ separately in your page.
@@ -90,51 +101,3 @@ under the `GPLv3 <https://github.com/signalapp/libsignal-protocol-javascript/blo
 which requires all other dependent JavaScript code to also be open sourced under the same
 license. You might not be willing to adhere to those terms, which is why you
 need to decide for yourself whether you're going to load libsignal or not.
-
-
-.. _`webserver`:
-
-Setting up a webserver
-======================
-
-When making changes to Converse, either development or theming changes,
-you'll want to preview them in your browser.
-
-For this, you'll need to serve the development files via a web server,
-so that you can see your local changes in the browser.
-
-Manually starting a web server
-------------------------------
-
-To both set up the development environment and also start up a web browser to
-serve the files for you, you can run::
-
-    make serve
-
-.. note::
-    To run the "make" commands, you'll need `GNUMake <https://www.gnu.org/software/make>`_
-    installed on your computer. If you use GNU/Linux or \*BSD, it should be installed or
-    available via your package manager. For Mac, you'll need to install XCode and in
-    Windows you can use `Chocolatey <https://chocolatey.org/>`_.
-
-After running ``make serve`` you can open http://localhost:8000 in your webbrowser to see the Converse website.
-
-When developing or changing the theme, you'll want to load all the
-unminified JS and CSS resources as separate files. To do this, open http://localhost:8000/dev.html instead.
-
-You might want to open `dev.html <https://github.com/conversejs/converse.js/blob/master/dev.html>`_ in your text editor or IDE as well, to see
-how ``converse.initialize`` is called and to potentially change any of the
-settings.
-
-Starting a web server with live reloading
------------------------------------------
-
-Alternatively, if you want to have live reloading whenever any of the source files change, you
-can run ``make devserver`` (which will use `webpack-dev-server <https://github.com/webpack/webpack-dev-server>`_).
-
-Instead of ``dev.html`` being used, `webpack.html <https://github.com/conversejs/converse.js/blob/master/webpack.html>`_
-is now being used as the HTML template, and you'll need to modify that file if
-you want to change the settings passed to ``converse.initialize``.
-
-If you're running ``make devserver``, you need to open http://localhost:8080.
-

package.json

@@ -38,7 +38,8 @@
     "headless": "webpack --config webpack/webpack.headless.js",
     "headless-dev": "webpack --config webpack/webpack.headless.js --mode=development",
     "nodeps": "webpack --config webpack/webpack.nodeps.js",
-    "serve": "webpack serve --config webpack/webpack.serve.js",
+    "serve": "http-server -c-1",
+    "devserver": "webpack serve --config webpack/webpack.serve.js",
     "watch": "webpack --watch --config webpack/webpack.build.js --mode=development",
     "types": "tsc --declaration --emitDeclarationOnly --allowJs",
     "check:types": "tsc --noEmit"