Update readme (#1206)

CMakeLists.txt

@@ -109,6 +109,9 @@ add_custom_command(
   COMMAND ${CMAKE_COMMAND} -E copy
     ${CMAKE_CURRENT_SOURCE_DIR}/README.rst
     ${CMAKE_CURRENT_BINARY_DIR}/build.rst/README.rst
+  COMMAND ${CMAKE_COMMAND} -E copy
+    ${CMAKE_CURRENT_SOURCE_DIR}/CONTRIBUTING.rst
+    ${CMAKE_CURRENT_BINARY_DIR}/build.rst/CONTRIBUTING.rst
   COMMAND ${CMAKE_COMMAND} -E copy
     ${CMAKE_CURRENT_SOURCE_DIR}/CHANGELOG.rst
     ${CMAKE_CURRENT_BINARY_DIR}/build.rst/CHANGELOG.rst

CONTRIBUTING.rst

@@ -0,0 +1,138 @@
+================================================================================
+Contributing
+================================================================================
+
+The workflow for Cartridge contributors is different from that for Cartridge
+users. It implies building the project from source (documentation, Web UI)
+and running tests.
+
+--------------------------------------------------------------------------------
+Submitting a pull request
+--------------------------------------------------------------------------------
+
+1. `Fork <https://github.com/tarantool/cartridge/fork>`_ and clone the repository.
+2. `Build <#building-from-source>`_ it and `run <#running-a-demo-cluster>`_ it.
+3. Make a change, add `tests <#running-tests>`_, and make sure they still pass.
+4. Commit the changes and push them to your fork.
+5. `Submit <https://github.com/tarantool/cartridge/compare>`_ a pull request.
+
+Here are a few things you can do that will increase the likelihood of your pull
+request being accepted:
+
+- Describe *what* you do in the pull request description, and *why* you do it.
+- Add an auto-test that covers your changes.
+- Keep your change as focused as possible. One scope |--| one pull request.
+- Write a `good commit message <https://chris.beams.io/posts/git-commit/>`_.
+
+See other related resources:
+
+- `How to Contribute to Open Source <https://opensource.guide/how-to-contribute/>`_
+- `Using Pull Requests <https://help.github.com/articles/about-pull-requests/>`_
+- `GitHub Help <https://help.github.com>`_
+
+--------------------------------------------------------------------------------
+Building from source
+--------------------------------------------------------------------------------
+
+The fastest way to build the project is to skip building the Web UI:
+
+.. code-block:: bash
+
+    CMAKE_DUMMY_WEBUI=true tarantoolctl rocks make
+
+But if you want to build the frontend too, you'll also need
+``nodejs`` >= 12 and ``npm`` >= 6, see instructions
+`here <https://nodejs.org/en/download/package-manager/>`_.
+
+Documentation is generated from source code, but only if the ``ldoc``
+and ``sphinx`` tools are installed:
+
+.. code-block:: bash
+
+    pip install -r rst/requirements.txt
+    tarantoolctl rocks install ldoc --server=https://tarantool.github.io/LDoc/
+    tarantoolctl rocks make
+
+--------------------------------------------------------------------------------
+Running a demo cluster
+--------------------------------------------------------------------------------
+
+There are several example entry points which are mostly used for testing,
+but can also be useful for demo purposes or experiments:
+
+.. code-block:: bash
+
+    cartridge start
+
+    # or select a specific entry point
+    # cartridge start --script ./test/entrypoint/srv_vshardless.lua
+
+It can be accessed through the Web UI (http://localhost:8081)
+or via the binary protocol:
+
+.. code-block:: bash
+
+    tarantoolctl connect admin@localhost:3301
+
+    # or via console socket
+    # tarantoolctl connect unix/:./tmp/run/cartridge.srv-1.control
+
+If you also need the stateful failover mode, launch an external state provider
+|--| ``stateboard``:
+
+.. code-block:: bash
+
+    cartridge start --stateboard
+
+And set failover parameters according to ``instances.yml``. The defaults are:
+
+* State provider URI: ``localhost:4401``;
+* Password: ``qwerty``.
+
+For more details about ``cartridge-cli``, see its
+`usage <https://github.com/tarantool/cartridge-cli#usage>`_.
+
+--------------------------------------------------------------------------------
+Running tests
+--------------------------------------------------------------------------------
+
+.. code-block:: bash
+
+    # Backend
+    tarantoolctl rocks install luacheck
+    tarantoolctl rocks install luatest 0.5.2
+    .rocks/bin/luacheck .
+    .rocks/bin/luatest -v
+
+    # Frontend
+    npm install [email protected]
+    ./frontend-test.sh
+    ./cypress-test.sh
+
+    # Collect coverage
+    tarantoolctl rocks install luacov
+    tarantoolctl rocks install luacov-console
+    .rocks/bin/luatest -v --coverage
+    .rocks/bin/luacov-console `pwd`
+    .rocks/bin/luacov-console -s
+
+Find more about testing tools here:
+
+- `luacheck <https://github.com/tarantool/luacheck/#luacheck>`_
+- `luatest <https://github.com/tarantool/luatest#overview>`_
+- `cypress <https://docs.cypress.io>`_
+
+--------------------------------------------------------------------------------
+Updating auto-generated sources
+--------------------------------------------------------------------------------
+
+If the GraphQL API is changed, the ``doc/schema.graphql`` should be updated:
+
+.. code-block:: bash
+
+    npm install [email protected]
+    ./fetch-schema.sh
+
+.. |--| unicode:: U+2013   .. en dash
+.. |---| unicode:: U+2014  .. em dash, trimming surrounding whitespace
+   :trim:

README.rst

@@ -1,12 +1,36 @@
 .. _cartridge_readme:
 
 ================================================================================
-Tarantool Cartridge: a framework for distributed applications development
+Tarantool Cartridge
 ================================================================================
 
+A framework for distributed applications development.
+
+.. raw:: html
+
+  <a href="https://github.com/tarantool/cartridge/actions?query=workflow%3A%22Backend+Test%22">
+    <img src="https://github.com/tarantool/cartridge/workflows/Backend%20Test/badge.svg">
+  </a>
+  <a href="https://github.com/tarantool/cartridge/actions?query=workflow%3A%22Frontend+Test%22">
+    <img src="https://github.com/tarantool/cartridge/workflows/Frontend%20Test/badge.svg">
+  </a>
+  <br/>
+  <a href="https://t.me/tarantool">
+    <img src="https://img.shields.io/badge/telegram%20(EN)-tarantool-blue?logo=telegram&style=social">
+  </a>
+  <br/>
+  <a href="https://t.me/tarantoolru">
+    <img src="https://img.shields.io/badge/telegram%20(RU)-tarantoolru-blue?logo=telegram&style=social">
+  </a>
+
 .. raw:: html
 
-    <img src="https://github.com/tarantool/cartridge/blob/master/cartridge.png" height="400px">
+  <p align="center">
+    <img
+      src="https://github.com/tarantool/cartridge/raw/master/cartridge.png"
+      height="400px"
+    >
+  </p>
 
 .. contents::
 
@@ -115,110 +139,13 @@ See:
 * `Cartridge API reference <https://www.tarantool.io/en/doc/latest/book/cartridge/cartridge_api/>`_
 
 --------------------------------------------------------------------------------
-Contribution
+Contributing
 --------------------------------------------------------------------------------
 
-The workflow for Cartridge contributors may be different from that for Cartridge
-users as it it implies building the project from source (documentation, Web UI)
-and running tests.
-
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Building from source
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The fastest way to build the project is to skip building the Web UI:
-
-.. code-block:: bash
-
-    CMAKE_DUMMY_WEBUI=true tarantoolctl rocks make
-
-But if you want to build the frontend too, you'll also need:
-
-* ``nodejs`` >= 12 (see these `instructions <https://github.com/nodesource/distributions>`_);
-* ``npm`` >= 6.
-
-Documentation is generated from source code, but only if the ``ldoc`` and ``sphinx``
-tools are installed:
-
-.. code-block:: bash
-
-    pip install 'sphinx==3.0.3'
-    tarantoolctl rocks install \
-      https://raw.githubusercontent.com/tarantool/LDoc/tarantool/ldoc-scm-2.rockspec \
-      --server=http://rocks.moonscript.org
-    tarantoolctl rocks make
-
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Running a demo cluster
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-There are several example entry points which are mostly used for testing,
-but can also be useful for demo purposes or experiments:
-
-.. code-block:: bash
-
-    cartridge start
-
-    # or select a specific entry point
-    # cartridge start --script ./test/entrypoint/srv_vshardless.lua
-
-It can be accessed through the Web UI (http://localhost:8081)
-or via the binary protocol:
-
-.. code-block:: bash
-
-    tarantoolctl connect admin@localhost:3301
-
-If you also need the stateful failover mode, launch an external state provider
-|--| ``stateboard``:
-
-.. code-block:: bash
-
-    cartridge start --stateboard
-
-And set failover parameters according to ``instances.yml``. The defaults are:
-
-* State provider URI: ``localhost:4401``;
-* Password: ``qwerty``.
-
-For more details about ``cartridge-cli``, see its
-`usage <https://github.com/tarantool/cartridge-cli#usage>`_.
-
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Auto-generated sources
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-After the GraphQL API is changed, don't forget to fetch the schema
-``doc/schema.graphql``:
-
-.. code-block:: bash
-
-    npm install [email protected]
-    ./fetch-schema.sh
-
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Running tests
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. code-block:: bash
-
-    # Backend
-    tarantoolctl rocks install luacheck
-    tarantoolctl rocks install luatest 0.5.0
-    .rocks/bin/luacheck .
-    .rocks/bin/luatest -v
-
-    # Frontend
-    npm install [email protected]
-    ./frontend-test.sh
-    ./cypress-test.sh
-
-    # Collect coverage
-    tarantoolctl rocks install luacov
-    tarantoolctl rocks install luacov-console
-    .rocks/bin/luatest -v --coverage
-    .rocks/bin/luacov-console `pwd`
-    .rocks/bin/luacov-console -s
+The most essential contribution is your *feedback*, don't hesitate to
+`open an issue <https://github.com/tarantool/cartridge/issues/new>`_.
+If you'd like to propose some changes in code, see the contribution
+`guide <https://github.com/tarantool/cartridge/blob/master/CONTRIBUTING.rst>`_.
 
 .. |--| unicode:: U+2013   .. en dash
 .. |---| unicode:: U+2014  .. em dash, trimming surrounding whitespace