Overhaul contribution documentation

Author: FelixHenninger

contributing.md

@@ -1,50 +1,9 @@
 # Contributing
 
-**Thank you for your interest in contributing to `lab.js`! You are more than welcome to join** — whether you have new ideas, suggestions, or would just like to muck in, please be warmly invited to do so: This is an open project! We'd be glad to hear from you, to discuss ideas and approaches, and to get you going. Thank you for taking the time!
+**Thank you for your interest in contributing to `lab.js`! You are more than welcome to join** — whether you have new ideas, suggestions, or would just like to muck in, please be warmly invited to do so: This is an open project -- We'd be glad to hear from you, to discuss ideas and approaches, and to get you going. Thank you for taking the time!
 
 Together, **we're building a tool to help scientists understand behavior and cognition in its many forms, and to conduct their research efficiently and transparently**.
 
 ----
 
-### Working together
-
-We expect all members of our community to conform to our [**code of conduct**](code-of-conduct.md), and to be excellent to one another. We strive to meet the [Apache Foundation's guidelines](https://www.apache.org/foundation/policies/conduct) in our work together.
-
-### Reaching out
-
-We are happy to answer your questions! The best way to get hold of us is to [join our **Slack channel**](https://slackin-nmbrcrnchrs.herokuapp.com/), where you'll often find somebody around. We'd be thrilled to have your company!
-
-----
-
-## How to contribute
-
-### Reporting bugs or making suggestions
-
-**Notice something amiss, or some room for improvement?** You're already helping by letting us know — we'd love to hear from you, and try to make things work for everyone. We track bugs and tasks using [issues](https://github.com/felixhenninger/lab.js/issues?q=is%3Aopen). Here are some steps you can take to help us fix things and help you quickly:
-
-#### Before submitting an issue
-* **Please take a quick [look whether the problem or idea has been reported already](https://github.com/felixhenninger/lab.js/issues?q=is%3Aopen)**. You can try the search function with some related terms for a cursory check. If you find a previous report, please add a comment there instead of opening a new issue. If you're unsure, you're welcome to ask!
-
-#### Submitting a (great) bug report
-* **Pick a descriptive title** that clearly identifies the issue.
-* **Describe the steps that led to the problem** so that we can go through the same sequence. Does the problem reoccur when you go through the same steps once more? It is a huge help if you can provide us all the information needed to recreate the problem.
-* **Briefly describe what you had expected** and how that differed from what happened, and possibly, why.
-
-#### Making a suggestion
-* Summarize your idea with a **clear title**.
-* **Describe your suggestion in as much detail as possible**. How would it change the usage of the software?
-* **Explain how the suggestion would be useful** to most users.
-
-### Contribute to the code
-
-#### Building the project
-
-There's an [**overview of the code and intro to the build process**](https://labjs.readthedocs.io/en/latest/meta/contribute.html) in the documentation if you're interested, but as always, we'd be happy to help you get started.
-
-#### Finding a place to start
-
-**If you're searching for a place to contribute, please do let us know**: There's always things to do, and we'd be glad to help you find something that fits your interests and resources. If you're writing a tool that might interoperate with this one, we're more than happy to link things up; if you're looking to extend or build on this project, we'd be thrilled to provide a stepping stone for you!
-
-You might also find a task that interests and suits you, or an inspiration, in our
-* [Good **first bugs**](https://github.com/felixhenninger/lab.js/issues?q=is%3Aopen+is%3Aissue+label%3A"Good+first+bug") to help you get started
-* [Upcoming **milestones**](https://github.com/felixhenninger/lab.js/milestones)
+As for details, do reach out to us; there's much more information in the [contribution section](https://labjs.readthedocs.io/en/latest/meta/contribute/index.html) of the project documentation. There, you'll find pointers to different ways of contributing (*spoiler*: writing code isn't the only one), how to find your way around the repository, and how to find us so that we can help you get started. **Welcome to our community!**

docs/index.rst

@@ -44,6 +44,6 @@ All `contributors`_ are listed in the repository.
    :caption: Meta
    :hidden:
 
-   meta/contribute.rst
+   meta/contribute/index.rst
    meta/teach.rst
    meta/roadmap.rst

docs/meta/contribute.rst

@@ -0,0 +1,92 @@
+Building things
+===============
+
+The project repository contains the code underlying the ``lab.js`` library and the builder interface. To condense both into a single library file for distribution with studies, and an uploadable version of the builder, please follow these additional steps after downloading. You'll need a local installation of `node.js`_ and `npm`_.
+
+You'll notice that many of the commands start with ``npm`` -- that's because we use `npm scripts`_ as shortcuts for most build steps.
+
+----
+
+Bootstrapping the project
+-------------------------
+
+The library and builder interface are contained in the same repository because they share several pieces of code. Both are coordinated by `Lerna`_, which can initialize all parts at once by running the following commands in the project directory:
+
+.. code::
+
+  npm install && npm run bootstrap
+
+.. _Lerna: https://lernajs.io/
+
+----
+
+Compiling the library
+---------------------
+
+Changing to the ``packages/library`` directory and running
+
+.. code::
+
+  npm install
+
+will install all dependencies for the ``lab.js`` library, whereafter
+
+.. code::
+
+  npm run build:js
+
+will output a transpiled version in the ``packages/library/build`` directory. If you would like the transpiled output to be updated automatically as you make changes, ``npm run watch:js`` will do that for you.
+
+.. code::
+
+  npm run build:starterkit
+
+will build the library with all its components (the basic ``HTML`` template, the stylesheet, and several other useful files), and assemble the result into a ``zip`` file for easier distribution. This is the bundle that is included with every release.
+
+There are a few more commands available, which you can see by typing ``npm run`` in the ``packages/library`` folder.
+
+.. _npm scripts: https://docs.npmjs.com/misc/scripts
+.. _node.js: https://nodejs.org/
+.. _npm: https://www.npmjs.com/
+
+----
+
+Working on the builder
+----------------------
+
+The builder interface is created using Facebook's `create-react-app`_ template, and follows the conventions instituted there. If you're looking for details, their documentation provides more information than we ever could.
+
+The main code is found in the ``packages/builder/src`` folder, where the ``components`` subdirectories contain all user-facing interface code, and ``logic`` holds the main application logic.
+
+To install a copy of the builder locally, please download the repository, navigate into the ``packages/builder`` folder, and run ``npm install`` to download all dependencies. Then, typing
+
+.. code::
+
+  npm start
+
+will run the builder application in a **local development server**, and open it in a browser.
+
+.. code::
+
+  npm run build
+
+bundles all files necessary for **deployment**, and creates an optimized version of the application code in the ``packages/builder/build`` folder for you to upload.
+
+.. _create-react-app: https://github.com/facebookincubator/create-react-app/
+
+----
+
+Building the documentation
+--------------------------
+
+The library's documentation is built using `Sphinx`_, which you'll need to `install`_. In addition, it requires the fabulous `Read the Docs Theme`_. Equipped with both, you can run
+
+.. code::
+
+  npm run build:docs
+
+within the project root directory, which will output the html documentation in the ``docs/_build`` subdirectory. Running ``npm run watch:docs`` will update the documentation whenever you make changes.
+
+.. _Sphinx: http://sphinx-doc.org/
+.. _install: http://sphinx-doc.org/tutorial.html#install-sphinx
+.. _Read the Docs Theme: https://github.com/snide/sphinx_rtd_theme

docs/meta/contribute/build.rst

@@ -0,0 +1,9 @@
+Reaching out and finding help
+=============================
+
+**Please be invited to reach out and discuss any questions or ideas you have, or changes you would like to make**: We are happy to answer your questions!
+
+Our `Slack channel`_ is always available for **quick questions** -- we try to be around as much as possible. For long-term **proposals, more formal technical discussions and bug reports**, please use `GitHub issues`_. You are also welcome to drop the main contributors a line or two by email if you prefer.
+
+.. _Slack channel: https://slackin-nmbrcrnchrs.herokuapp.com/
+.. _GitHub issues: https://github.com/felixhenninger/lab.js/issues

docs/meta/contribute/help.rst

@@ -0,0 +1,19 @@
+.. _contribute:
+
+Contribute
+==========
+
+**Thank you for considering contributing** to ``lab.js``! Whether you have an idea or suggestion, if you have spotted a bug or even have a correction handy, whether you would like to add new features or documentation, or improve what's already there, **your help is very welcome** indeed. Similarly, if you enjoy the project and would like to become a contributor, you are very warmly invited to join; we'd be glad to help you find a contribution that fits your interests and resources.
+
+Together, **we're building a tool to help scientists understand behavior and cognition in its many forms, and to conduct their research efficiently and transparently.**
+
+.. toctree::
+   :caption: Contents
+   :maxdepth: 1
+
+   together.rst
+   ways.rst
+   help.rst
+   build.rst
+   navigate.rst
+   test.rst