From a102d92ae4358f70bb489eb655eabc1ff700adb6 Mon Sep 17 00:00:00 2001 From: Felix Henninger Date: Mon, 31 Jul 2017 15:29:32 +0200 Subject: [PATCH] Overhaul contribution documentation --- contributing.md | 45 +-------- docs/index.rst | 2 +- docs/meta/contribute.rst | 163 ------------------------------ docs/meta/contribute/build.rst | 92 +++++++++++++++++ docs/meta/contribute/help.rst | 9 ++ docs/meta/contribute/index.rst | 19 ++++ docs/meta/contribute/navigate.rst | 81 +++++++++++++++ docs/meta/contribute/test.rst | 26 +++++ docs/meta/contribute/together.rst | 10 ++ docs/meta/contribute/ways.rst | 57 +++++++++++ 10 files changed, 297 insertions(+), 207 deletions(-) delete mode 100644 docs/meta/contribute.rst create mode 100644 docs/meta/contribute/build.rst create mode 100644 docs/meta/contribute/help.rst create mode 100644 docs/meta/contribute/index.rst create mode 100644 docs/meta/contribute/navigate.rst create mode 100644 docs/meta/contribute/test.rst create mode 100644 docs/meta/contribute/together.rst create mode 100644 docs/meta/contribute/ways.rst diff --git a/contributing.md b/contributing.md index 47f10a002..b53154d41 100644 --- a/contributing.md +++ b/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!** diff --git a/docs/index.rst b/docs/index.rst index 81a382c2b..db609f843 100644 --- a/docs/index.rst +++ b/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 diff --git a/docs/meta/contribute.rst b/docs/meta/contribute.rst deleted file mode 100644 index f165f9b77..000000000 --- a/docs/meta/contribute.rst +++ /dev/null @@ -1,163 +0,0 @@ -.. _contribute: - -Contribute -========== - -**Thank you for considering contributing** to ``lab.js``! Whether you have a 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. - -**Please be invited to reach out and discuss any changes you would like to make**: We have a lot of ideas and code lying about, and might be able to give you a head start. If you are are planning to add significant amounts of additional functionality, we might ask you to build an external add-on or a :ref:`plugin ` first before including your code in ``lab.js`` itself. In any case, we are happy to help you getting started! - -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 if you prefer. - -If you are familiar with Git and GitHub, please feel free to fork the repository and submit pull requests; otherwise, **your contributions are welcome in any shape or form**. - -We expect contributions to conform to the `Developer Certificate of Origin`_. We encourage contributors to `'sign off' patches`_ as the Linux kernel developers do. - -.. _Slack channel: https://slackin-nmbrcrnchrs.herokuapp.com/ -.. _GitHub issues: https://github.com/felixhenninger/lab.js/issues -.. _Developer Certificate of Origin: http://developercertificate.org/ -.. _'sign off' patches: https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/Documentation/process/submitting-patches.rst#n416 - ----- - -High-level code overview ------------------------- - -Library -^^^^^^^ - -The source code underlying the ``lab.js`` library is contained in the ``library/src`` folder of the repository. For ease of development, the code is split across several files. - -User-facing code -"""""""""""""""" - -``core.js`` · Core user-facing classes - This code defines the core user-facing parts of the library, notably the :js:class:`core.Component` and its simplest derivative, the :js:class:`core.Dummy` component. - - If you are looking to understand the internals of the library, this is the place to start -- all the core functionality is defined here. We strive to keep this code especially well-commented and understandable, please do let us know if we can explain something better! - -``html.js`` · HTML-based components - All elements that use ``HTML`` for showing content: :js:class:`html.Screen` and :js:class:`html.Form`. - -``canvas.js`` · Canvas-based components - Components in this file rely on the ``Canvas`` for showing content: :js:class:`canvas.Screen` and :js:class:`canvas.Sequence`. - -``flow.js`` · Flow control - These components are not so much for displaying information, but for controlling the overall flow of the experiment. In particular, this file includes the source for :js:class:`flow.Sequence`, :js:class:`flow.Loop` and :js:class:`flow.Parallel`. - -``data.js`` · Data handling - The code contained in this file takes care of data storage and export. It defines the :js:class:`data.Store` class that logs and formats the experiments' output. - -Utilities -""""""""" - -The library also contains a range of utility functions and classes for internal use. These are generally not exposed to end-users, but are used extensively throughout the library code. - -``util/eventAPI.js`` · Low-level helpers and event handlers - This file defines the :js:class:`EventHandler` class that provides a very basic `publish-subscribe`_ architecture to all other classes in the library. - - This is really the backbone of the library, which relies heavily on this design for everything that happens. This is the place to dig deepest into the inner machinations of ``lab.js`` . - - .. _publish-subscribe: https://en.wikipedia.org/wiki/Publish–subscribe_pattern - -``util/domEvents.js`` · Document event handling - The code in this file deals with assigning handlers to document events, and establishing and removing the links between both. The resulting :js:class:`DomConnection` class encapsulates this functionality, and is used within each component to handle document events. - -Unit tests -"""""""""" - -The ``test`` directory contains the **automated test suite** that covers most of the library's functionality. This is what allows us to sleep at night, and we highly recommend using it to ensure that any changes you make do not break compatibility. The tests are organized into files depending on the functionality they cover -- these correspond in name to those of the library as described above. - -To run the tests, please build the library first (see below) -- the tests will cover your local development copy. You can run the tests by opening the file ``test/index.html`` in your browser. You should (hopefully) see a lot of green tick marks! -Running the tests will also provide you a good indication of whether the library is supported by any particular browser, however be warned that there may be some false negatives (wrongly failing tests) because many tests use EcmaScript 2016 function shorthand which not all browsers support. If this is an issue for you, please contact us for a work-around. - ----- - -Builder -^^^^^^^ - -The graphical builder interface resides in the repository's ``builder/src`` directory. It is structured as a `React`_ application, building on the `create-react-app`_ template. The internal state is managed using `Redux`_. - -``components`` · User interface components - The application is broken down into distinct components, for example the editor or the sidebar, each of which contain their own logic and styles. If you are looking for a specific part of the user interface to improve, this is where you'll find it. - -``logic`` · Application logic - Besides the user interface, the builder contains a substantial amount of application logic that governs how studies are put together, saved into and loaded from files, and exported to a local preview mode as well as publishable study bundles. - -.. _React: https://facebook.github.io/react/ -.. _Redux: http://redux.js.org/ - ----- - -Building lab.js ---------------- - -In the repository, only the underlying code is present. To condense all of this into a single file you can use directly to power your studies, please follow the following steps. - -Compiling the library -^^^^^^^^^^^^^^^^^^^^^ - -Releases are built using `npm scripts`_. To produce a build, you will need a local installation of `node.js`_ and `npm`_. Running - -.. code:: - - npm install - -within the build directory will install all necessary dependencies, whereafter - -.. code:: - - npm run build:js - -will output a transpiled version in the ``build`` directory. - -.. 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. - -While developing, automatic transpiling when a file has changed is handy. Running ``npm run watch:js`` will run the transpilation anew whenever a file is changed. - -.. _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. Their documentation provides more information than we ever could. - -To summarize just the bare necessities: The main code is found in the ``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 ``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. - -.. _create-react-app: https://github.com/facebookincubator/create-react-app/ - -Building the documentation -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The library's documentation is built using `Sphinx`_, which you will need to `install`_. In addition, you'll need the fabulous `Read the Docs Theme`_. Equipped with both, you can run - -.. code:: - - make html - - -within the ``docs`` folder, which will output the html documentation in the ``docs/_build`` subdirectory. - -.. _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 diff --git a/docs/meta/contribute/build.rst b/docs/meta/contribute/build.rst new file mode 100644 index 000000000..98cb9a469 --- /dev/null +++ b/docs/meta/contribute/build.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 diff --git a/docs/meta/contribute/help.rst b/docs/meta/contribute/help.rst new file mode 100644 index 000000000..34bc57f2e --- /dev/null +++ b/docs/meta/contribute/help.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 diff --git a/docs/meta/contribute/index.rst b/docs/meta/contribute/index.rst new file mode 100644 index 000000000..4dd9c4766 --- /dev/null +++ b/docs/meta/contribute/index.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 diff --git a/docs/meta/contribute/navigate.rst b/docs/meta/contribute/navigate.rst new file mode 100644 index 000000000..ce42bf78a --- /dev/null +++ b/docs/meta/contribute/navigate.rst @@ -0,0 +1,81 @@ +Finding your way around the code +================================ + +If you look into the library code, you'll find annotations and explanations alongside the JavaScript source. However, it can be difficult to find the place you're looking for. The following page is meant as an overview; if you have any further questions, do let us know. + +---- + +Library +------- + +The source code underlying the ``lab.js`` library is contained in the ``packages/library/src`` folder of the repository. For ease of development, the code is split across several files. + +User-facing code +^^^^^^^^^^^^^^^^ + +``core.js`` · Core user-facing classes + This code defines the core user-facing parts of the library, notably the :js:class:`core.Component` and its simplest derivative, the :js:class:`core.Dummy` component. + + If you are looking to understand the internals of the library, this is the place to start -- all the core functionality is defined here. We strive to keep this code especially well-commented and understandable, please do let us know if we can explain something better! + +``html.js`` · HTML-based components + All elements that use ``HTML`` for showing content: :js:class:`html.Screen`, :js:class:`html.Form` and :js:class:`html.Frame`. These are probably most commonly used in studies. + +``canvas.js`` · Canvas-based components + Components in this file rely on the ``Canvas`` for showing content, for extra performance: :js:class:`canvas.Screen`, :js:class:`canvas.Sequence` and :js:class:`canvas.Frame`. + +``flow.js`` · Flow control + These components are not so much for displaying information, but for controlling the overall flow of the experiment. In particular, this file includes the source for :js:class:`flow.Sequence`, :js:class:`flow.Loop` and :js:class:`flow.Parallel`. + +``data.js`` · Data handling + The code contained in this file takes care of data storage and export. It defines the :js:class:`data.Store` class that logs and formats the experiments' output. + +Utilities +^^^^^^^^^ + +The library also contains a range of utility functions and classes for internal use. These are generally not exposed to end-users, but are used extensively throughout the library code. + +``util/eventAPI.js`` · Low-level helpers and event handlers + This file defines the :js:class:`EventHandler` class that provides a very basic `publish-subscribe`_ architecture to all other classes in the library. + + This is really the backbone of the library, which relies heavily on this design for everything that happens. This is the place to dig deepest into the inner machinations of ``lab.js`` . + + .. _publish-subscribe: https://en.wikipedia.org/wiki/Publish–subscribe_pattern + +``util/domEvents.js`` · Document event handling + The code in this file deals with assigning handlers to document events, and establishing and removing the links between both. The resulting :js:class:`DomConnection` class encapsulates this functionality, and is used within each component to handle document events. + +``util/fromObject.js`` · Construct studies from serialized representations + Many of the studies built with ``lab.js`` -- for example those constructed using the builder, aren't programmed in JavaScript code directly. Instead, users provide a static representation of their study, and rely on the library to assemble the appropriate code. This is what the code in this file is for. + +``util/fullscreen.js`` · Fullscreen helpers + This file provides functions to enter and leave fullscreen mode across all browsers. + +``util/options.js`` · Option parsing + The code in this file helps with substituting component :js:attr:`parameters ` in the content and options of components. + +``util/preload.js`` · Media preloading + Preloading images and other static assets. + +``util/random.js`` · Random number generation + Anything that needs to be sampled, drawn, suffled or generated randomly goes through this code. + +``util/tree.js`` · Tree traversal + A more complex study built with ``lab.js`` will often resemble a tree structure, in that there is a central :js:class:`sequence ` as a stem, which contains other components. These child components may, in turn, contain others nested inside them. This nested, or tree-like structure, frequently needs to be navigated, and the utilities in this file help with that. + +---- + +Builder +------- + +The graphical builder interface resides in the repository's ``builder/src`` directory. It is structured as a `React`_ application, building on the `create-react-app`_ template. The internal state is managed using `Redux`_. + +``components`` · User interface components + The application is broken down into distinct components, for example the editor or the sidebar, each of which contain their own logic and styles. If you are looking for a specific part of the user interface to improve, this is where you'll find it. + +``logic`` · Application logic + Besides the user interface, the builder contains a substantial amount of application logic that governs how studies are put together, saved into and loaded from files, and exported to a local preview mode as well as publishable study bundles. + +.. _React: https://facebook.github.io/react/ +.. _Redux: http://redux.js.org/ +.. _create-react-app: https://github.com/facebookincubator/create-react-app/ diff --git a/docs/meta/contribute/test.rst b/docs/meta/contribute/test.rst new file mode 100644 index 000000000..023614984 --- /dev/null +++ b/docs/meta/contribute/test.rst @@ -0,0 +1,26 @@ +Running tests +============= + +Don't be fooled by us listing them last -- **tests are a vital part of our work and infrastructure**. They are what allows us to sleep at night while colleagues the world over rely on our software. When you or any of us proposes a change, automated tests will verify it, and together, we'll write new tests to cover any added functionality. + +---- + +Library +------- + +You'll find the **tests for the core library** in the ``packages/library/test`` directory. After building the library, you can test its functionality by opening ``index.html`` in any browser, which will run a series of checks to ensure that everything works as designed. You should (hopefully) see a lot of green tick marks! + +During development, you might find it easier and faster to run **automated tests from the command line**. The command ``npm test``, run in the ``packages/library`` folder, will do that for you, provided that you have a version of the chrome browser installed. + +To run **cross-browser tests**, you'll need an account at `Sauce Labs`_, and setup your computer so that your login credentials are available. Then, you can run ``npm run test:sauce`` to automatically run the entire test suite across the full range of supported browsers. + +We also take great pride in our good **test coverage**, for which statistics can be generated using the command ``npm run test:coverage``. + +.. _Sauce Labs: http://saucelabs.com/ + +---- + +Builder +------- + +Unit tests for the builder cover the core application logic. By running ``npm test`` in the ``packages/builder`` directory, you'll get continuously updated test results. diff --git a/docs/meta/contribute/together.rst b/docs/meta/contribute/together.rst new file mode 100644 index 000000000..d295c228c --- /dev/null +++ b/docs/meta/contribute/together.rst @@ -0,0 +1,10 @@ +Working together +================ + +**We would like ours to be an open, welcoming and supportive community, and are committed to making this possible.** We expect all members to meet our `Code of Conduct`_ in all their interactions, to be excellent to one another and to help others do the same. The `Apache Foundation's guidelines `_ provide a blueprint for the kind of project we strive to be. + +Please make sure you understand and accept the terms outlined in the documents linked above; if you have questions or suggestions, please let us know. **Welcome to our community!** + +.. _Code of Conduct: https://github.com/FelixHenninger/lab.js/blob/master/code-of-conduct.md +.. _Apache Foundation guidelines: https://www.apache.org/foundation/policies/conduct + diff --git a/docs/meta/contribute/ways.rst b/docs/meta/contribute/ways.rst new file mode 100644 index 000000000..284d1617a --- /dev/null +++ b/docs/meta/contribute/ways.rst @@ -0,0 +1,57 @@ +Ways to contribute +================== + +**Thank you for considering contributing** to ``lab.js``! We're thrilled to have you around. This page summarizes a few of the many different ways in which you can help. + +We would like to stress at this point that **contributions can take may forms**, and often don't require writing code -- maybe something could be documented more clearly, maybe a feature could be more helpful, a design more inviting. Help is welcome in any of these areas! + +**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 proud to provide a stepping stone for you! + +---- + + +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 `GitHub issues`_. Here are some steps you can take to help us fix things and help you quickly and more effectively: + +**Before submitting an issue** + +* **Please take a quick look whether the problem or idea has been reported already** (there's a list of `open issues`_). 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? Is it specific to a particular browser? Can you share the study in which the error occurs? 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. + +.. _Slack channel: https://slackin-nmbrcrnchrs.herokuapp.com/ +.. _GitHub issues: https://github.com/felixhenninger/lab.js/issues +.. _open issues: https://github.com/felixhenninger/lab.js/issues?q=is%3Aopen + +---- + +Contributing code and/or documentation +-------------------------------------- + +**Wow, thank you for considering making a contribution to the code or documentation!** You have won a special place in our heart already. As an open project, we welcome contributions from everybody, and we will gladly help you make yours. + +**We would like to encourage you to reach out** before you start working: Between our contributors, we have a lot of ideas and code lying around, and might be able to give you a head start. If you are are planning to add significant amounts of additional functionality, we might ask you to build an external add-on or a :ref:`plugin ` first before including your code in ``lab.js`` itself. In any case, we would be thrilled to help you get started! + +If you're looking for a way to **get started**, you might find a task that interests and suits you, or an inspiration, in our collection of `good first bugs`_ or the list of `upcoming milestones`_. We would be happy, though, to help you find something that works for you. + +If you are familiar with Git and GitHub, please feel free to fork the repository and submit pull requests; otherwise, **your contributions are welcome in any shape or form**. If you would like to learn to handle GitHub, a nice way to get started is the course `How to Contribute to an Open Source Project on GitHub`_ by Kent C. Dodds. + +We would like contributions to conform to the `Developer Certificate of Origin`_ to make sure that the **licensing** works out. We encourage contributors to `'sign off' patches`_ as the Linux kernel developers do. If you're not familiar with the process, please don't let that stop you; we'll gladly walk you through the process when you submit a change. + +.. _good first bugs: https://github.com/felixhenninger/lab.js/issues?q=is%3Aopen+is%3Aissue+label%3A"Good+first+bug" +.. _upcoming milestones: https://github.com/felixhenninger/lab.js/milestones +.. _How to Contribute to an Open Source Project on GitHub: https://egghead.io/courses/how-to-contribute-to-an-open-source-project-on-github +.. _Developer Certificate of Origin: http://developercertificate.org/ +.. _'sign off' patches: https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/Documentation/process/submitting-patches.rst#n416