DOC-318: Add doc about dev env best practices (#13261)

* Added doc about dev env best practices. Translations doc in crm updated with info from commerce
* changes according to the @kisakova review
* changed structure of the community guide for crm and commerce. Doc contents unified. Added more text to the guide index.
* updated community guide index: added more introductory text, added more links to Contribute section; updated menu name (to make shorter)

Author: alverena

community/code_dev_env.rst

@@ -0,0 +1,102 @@
+.. _doc--dev-env-best-practices:
+
+Set Up a Development Environment
+================================
+
+Developers who write a code for Oro applications occasionally face challenges regarding the local development environment and usually successfully overcome them. This article describes best practices in setting up a development environment and recommendations on how to avoid the most common issues. All of the described best practices are mere recommendations, however, they can speed up the development process and make it more convenient.
+
+.. contents:: :local:
+
+Hardware Best Practices
+-----------------------
+
+Hard disk
+^^^^^^^^^
+
+Use a solid-state drive (SSD). An Oro application uses lots of files (vendors, cache), so good read speed accelerates page loadings while good write speed helps warm up and clear cache faster.
+
+RAM
+^^^^
+
+Make sure that you have enough RAM for your environment. An Oro application creates numerous processes (web server, cron, consumers) and may use external services (DB, search index, message queue), each of which might consume significant amount of memory.
+
+For example, the Enterprise version of the Oro application with several thousand entities, Elasticsearch search index, RabbitMQ and 4 consumers requires between 2GB and 4GB of RAM. When there is not enough memory and an OS uses swap, the application may encounter performance issues and a developer has to wait longer than usual.
+
+Software Best Practices
+-----------------------
+
+File System
+^^^^^^^^^^^^
+
+One of the ways to increase development speed is to make sure that all of the required files are stored in RAM instead of the disk drive. You can move DB files, search index storage, application files, application cache, etc. there.
+
+In UNIX-based operating systems, you can use `ramfs <https://wiki.debian.org/ramfs>`__ or `tmpfs <https://en.wikipedia.org/wiki/Tmpfs>`__ to create virtual RAM partitions. In Windows, you can use special software to create a RAM disk.
+
+Containers
+^^^^^^^^^^
+
+If you prefer to develop an application in a container-based environment, remember that the code should not be stored on virtual file systems with low read/write speed as by default an Oro application performs a significant amount of requests to the file system.
+
+If you are using Docker or Vagrant, check the `default configuration for these containers <https://github.com/oroinc/environment>`__.
+
+IDE
+^^^^
+
+Ensure that your IDE supports autocomplete, quick search, quick navigation, code generation, code formatting, and other useful features. For example, `PhpStorm <https://www.jetbrains.com/phpstorm/>`__ with `Symfony plugin <https://plugins.jetbrains.com/plugin/7219-symfony-plugin>`__ and `Oro plugin <https://plugins.jetbrains.com/plugin/8449-oro-phpstorm-plugin>`__ provides one of the best experiences.
+
+Debugger
+^^^^^^^^
+
+Integrate a debugging tool into your IDE to be able to set breakpoints in a code, see watches and go over a stack trace in real time. See `how to set up integration between PhpStorm and xDebug <https://www.jetbrains.com/help/phpstorm/configuring-xdebug.html>`__.
+
+Code Style
+^^^^^^^^^^
+
+Unified code style improves code readability and helps avoid simple mistakes and typos. You can use `PHP Code Sniffer <https://github.com/squizlabs/PHP_CodeSniffer>`__, `PHP Mess Detector <https://phpmd.org/>`__, `PHP Copy/Paste Detector <https://github.com/sebastianbergmann/phpcpd>`__, `PHP CS Fixer <https://github.com/FriendsOfPHP/PHP-CS-Fixer>`__, and other similar tools. PhpStorm supports integration with `PHP Code Sniffer <https://confluence.jetbrains.com/display/PhpStorm/PHP+Code+Sniffer+in+PhpStorm>`__ and `PHP Mess Detector <https://confluence.jetbrains.com/display/PhpStorm/PHP+Mess+Detector+in+PhpStorm>`__. See the `standard Oro configuration <https://github.com/oroinc/platform/tree/master/build>`__ for these tools.
+
+Tips and Tricks
+---------------
+
+Excluded Directories in PhpStorm
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+By default, PhpStorm performs re-indexation of all files in a project. However, some files, like cache storage and copies of assets, are not usually required during development. To speed up the re-indexation, mark that are not required as excluded, and PhpStorm will not reindex them.
+
+To mark directory as excluded, right-click it in the project panel and select **Mark Directory as > Excluded**.
+
+Here is a list of directories that can be excluded by default:
+
+* app/cache
+* web/bundles
+
+Testing in PhpStorm
+^^^^^^^^^^^^^^^^^^^
+
+If you write tests for your code, integrate `PhpUnit with PhpStorm <https://confluence.jetbrains.com/display/PhpStorm/PHPUnit+support+in+PhpStorm>`__ and use it `for actual testing <https://www.jetbrains.com/help/phpstorm/testing-with-phpunit.html>`__.
+
+You can also set the default configuration for the PhpUnit test runner (path to phpunit.xml, the working directory, etc.). Then you can just right-click a test file and select **Run <file>** to run all tests from the file.
+
+Symfony Debug Toolbar
+^^^^^^^^^^^^^^^^^^^^^
+
+Oro applications are built on top of the Symfony framework which provides the `debug toolbar <http://symfony.com/blog/new-in-symfony-2-8-redesigned-web-debug-toolbar>`__ with lots of useful information, like request data, session variables, DB queries, layout data, etc. Feel free to use all this information during development, or even `add your own sections <http://symfony.com/doc/2.8/profiler/data_collector.html>`__ to the toolbar.
+
+
+See Also
+--------
+
+:ref:`Version Control <code-version-control>`
+
+:ref:`Code Style <doc--community--code-style>`
+
+:ref:`Contribute to Translations <doc--community--ui-translations>`
+
+:ref:`Contribute to Documentation <documentation-standards>`
+
+:ref:`Report an Issue <doc--community--issue-report>`
+
+:ref:`Report a Security Issue <reporting-security-issues>`
+
+:ref:`Contact Community <doc--community--contact-community>`
+
+:ref:`Release Process <doc--community--release>`

community/code_style.rst

@@ -1,12 +1,15 @@
-:orphan:
+..  _doc--community--code-style:
 
 Code Style
-----------
+==========
 
 Code style is a set of conventions about how to write code. It is introduced for easier understanding of the large codebase by the wide-spread Oro community.
 
 The following code styles are used in all Oro projects, except for projects based on the frameworks, libraries or CMS where other conventions have been adopted.
 
+.. contents:: :local:
+    :depth: 3
+
 PHP Code Style
 ^^^^^^^^^^^^^^
 
@@ -18,7 +21,7 @@ PSR-2 is considered a code standard of the PHP code style.
 
 
 Default line break separator is LF (\n) - Unix and OS X style.
-  
+
   .. note:: To eliminate issues with this requirement, it is recommended to configure IDE and always use appropriate line break separator. How to configure this in PHPStorm could be found `here <https://www.jetbrains.com/help/phpstorm/2016.3/configuring-line-separators.html>`_
 
 **DocBlock**
@@ -195,11 +198,11 @@ Cyclomatic complexity is determined by the number of decision points in a method
 
 There are many good reasons to limit cyclomatic complexity. Overly complex modules are more prone to error, harder to understand, test and modify. Deliberately limiting complexity at all stages of software development, for example as a departmental standard, helps avoid the pitfalls associated with high complexity software. But there were occasional reasons for going beyond the agreed-upon limit. For example, Thomas McCabe originally recommended exempting modules consisting of single multi-way decision (“switch” or “case”) statements from the complexity limit. And suggested the most effective policy: “For each module, either limit cyclomatic complexity to 10 (as discussed earlier, an organization can substitute a similar number), or provide a written explanation of why the limit was exceeded.” (see `Structured Testing: A Testing Methodology Using the Cyclomatic Complexity Metric <http://www.mccabe.com/pdf/mccabe-nist235r.pdf>`_).
 
-Cyclomatic complexity limits suggestions are the following: 
+Cyclomatic complexity limits suggestions are the following:
 
 - PHP: 1-4 is low complexity, 5-7 indicates moderate complexity, 8-10 is high complexity, and 11+ is very high complexity (see `PHPMD <https://phpmd.org/rules/codesize.html>`_).
 - `Java <http://www.javaworld.com/article/2074995/dealing-cyclomatic-complexity-in-java-code.html>`_ 1–10 to be considered a Normal application, 11–20 Moderate application, 21–50 Risky application, more than 50 Unstable application (also see `here, by GMetrics <http://gmetrics.sourceforge.net/gmetrics-CyclomaticComplexityMetric.html>`_).
-- .Net: 1 to 10 a simple program, without very much risk; 11 to 20 a more complex program, moderate risk; 21 to 50 a complex, high risk program; > 50 an un-testable `program <https://www.codeproject.com/articles/11719/cyclomatic-code-complexity-analysis-for-microsoft>`_ (very high risk). 
+- .Net: 1 to 10 a simple program, without very much risk; 11 to 20 a more complex program, moderate risk; 21 to 50 a complex, high risk program; > 50 an un-testable `program <https://www.codeproject.com/articles/11719/cyclomatic-code-complexity-analysis-for-microsoft>`_ (very high risk).
 - Microsoft recommendation is to warn when Cyclomatic complexity is more than 25 (`CA1502 <https://msdn.microsoft.com/en-us/library/ms182212.aspx>`_).
 - `McCabe <http://www.mccabe.com/pdf/mccabe-nist235r.pdf>`_ originally proposed the limit of 10 since it has significant supporting evidence, but limits as high as 15 have been used successfully as well.
 
@@ -275,4 +278,25 @@ CSS and HTML Code Style
 ^^^^^^^^^^^^^^^^^^^^^^^
 There are no defined code styles for the CSS and HTML.
 
-It is recommended to use same code style that is used in `Bootstrap <http://getbootstrap.com/>`_.
+It is recommended to use same code style that is used in `Bootstrap <http://getbootstrap.com/>`_.
+
+
+
+See Also
+--------
+
+:ref:`Version Control <code-version-control>`
+
+:ref:`Set Up a Development Environment <doc--dev-env-best-practices>`
+
+:ref:`Contribute to Translations <doc--community--ui-translations>`
+
+:ref:`Contribute to Documentation <documentation-standards>`
+
+:ref:`Report an Issue <doc--community--issue-report>`
+
+:ref:`Report a Security Issue <reporting-security-issues>`
+
+:ref:`Contact Community <doc--community--contact-community>`
+
+:ref:`Release Process <doc--community--release>`

community/code_ui_translations.rst

@@ -0,0 +1,114 @@
+.. _doc--community--ui-translations:
+
+Contributing to Translations
+============================
+
+.. contents:: :local:
+
+Oro applications support localization and internationalization for multiple languages and locales.
+All strings that may be translated are defined in the bundle translation domain files and are exposed via the translation management service `Crowdin <https://crowdin.com/>`__ to enable the collaborative translation efforts.
+
+To contribute to OroCommerce translation into your native language:
+
+#. :ref:`Join the translation team <translations-join-the-team>`.
+
+#. :ref:`Submit your translations <translations-submit>`.
+
+#. Wait for your translation to be approved.
+
+#. :ref:`Ensure that synchronization is enabled for the target language <translations-language-settings>`.
+
+:ref:`Contact Oro translation team <translations-contact>` if you face any issues (e.g., your translation does not appear in the Oro application after it has been approved).
+
+.. _translations-join-the-team:
+
+Join the Translation Team
+-------------------------
+
+#. Sign into your Crowdin account or sign up for a new user account if you don not have one yet:
+
+   a) Open `Crowdin <https://crowdin.com/join>`_ in your browser.
+
+   #) Sign in using your github or social network account (Facebook, Google+, Twitter).
+
+      Alternatively, create a new Crowdin account: enter your email, user name, password and password confirmation, and click **Create account**. Follow the link in the confirmation email to activate you account.
+
+#. Open `OroCommerce project <https://crowdin.com/project/orocommerce>`_.
+
+   .. note:: To offer translations for OroCRM and OroPlatform, please use their dedicated translation projects: `OroCRM project <https://translate.orocrm.com>`_ and `OroPlatform project <http://translate.platform.orocrm.com>`_.
+
+#. Select the target language for OroCommerce translation and click **Join** next to the following message: “You must join the translators team to be able to participate in this project”.
+
+#. Type in the reason for joining the translation team (e.g., "As a developer, I would like to enable Korean translation for OroCommerce and my customization") and click **Join**.
+
+#. Your request will be reviewed by the Oro support team. Upon approval, you will get an email from Crowdin with an invitation to start contributing.
+
+
+.. _translations-submit:
+
+Submit Your Translations
+------------------------
+
+#. To open the translation project, click **Get Involved** in the email from Crowdin that confirms your OroCommerce project team membership.
+
+   Alternatively, use the `OroCommerce project <https://crowdin.com/project/orocommerce>`_ link to open the project.
+
+#. Select the target language (e.g. Korean).
+
+   Translations are stored in yaml files organized by bundles (e.g. OroAlternativeCheckoutBundle, OroCatalogBundle) and by groups (e.g. messages, tooltips).
+
+#. Select the yaml file with the translations you would like to contribute to.
+
+#. Submit your translation. For more information on using Crowdin, please see the `Crowdin tutorial <https://support.crowdin.com/for-translators/onlineworkbench/translation-tutorial/>`_.
+
+After you have submitted the translation, it will be queued for `proofreading <https://support.crowdin.com/for-translators/onlineworkbench/proofreading>`_. Other translators can `vote <https://support.crowdin.com/for-translators/onlineworkbench/voting>`_ for it.
+
+When the translation is approved, it is marked with a green check mark and moved to the end of the list on the translation page. Approved translations are merged (published) to the Oro application translations once a day and become available in Oro application in the language settings (to open the language settings, in the main menu, navigate to **System > Configuration > Language Settings**).
+
+.. _translations-language-settings:
+
+Update Translation in Oro Application
+-------------------------------------
+
+.. TODO: OroCommerce UI has changed. Confirm th correct process for translation sync with crowdin.
+
+1. Navigate to the **System > Localization > Languages** in the main menu.
+
+2. If your target language is not listed, click **Add language**, in the **Add Language** dialog that opens, select the target language from the list and click **Add language**. This will trigger the download of the translation files from the Crowdin project into the Oro application.
+
+3. If the status for your target language is *Disabled*, click the |IcCheck| **Enable** icon at the end of the row.
+   .. This will enable loading the translation updates automatically from the Crowdin project into the Oro application.
+
+4. If you see *Update is available* in the **Updates** column, click |IcCloudDownload| **Update** at the end of the row to update translations from the Crowdin project.
+
+
+.. _translations-contact:
+
+Contact Oro Translation Team
+----------------------------
+
+.. include:: ./issues/translation.rst
+   :start-after: begin
+
+See Also
+--------
+
+:ref:`Version Control <code-version-control>`
+
+:ref:`Code Style <doc--community--code-style>`
+
+:ref:`Set Up a Development Environment <doc--dev-env-best-practices>`
+
+:ref:`Contribute to Documentation <documentation-standards>`
+
+:ref:`Report an Issue <doc--community--issue-report>`
+
+:ref:`Report a Security Issue <reporting-security-issues>`
+
+:ref:`Contact Community <doc--community--contact-community>`
+
+:ref:`Release Process <doc--community--release>`
+
+
+.. include:: /user_guide/include_images.rst
+   :start-after: begin

community/code_version_control.rst

@@ -0,0 +1,67 @@
+.. _code-version-control:
+
+Code Version Control
+====================
+
+.. contents:: :local:
+    :depth: 3
+
+The following is a set of conventions about code version control that strives to provide the best way to communicate
+enough context about every committed code change to fellow developers. These code version control conventions should be used in all Oro projects, except for the projects that adopted some other conventions.
+
+
+Git and Tools
+-------------
+
+`Git <https://git-scm.com/>`_ is the official version control system used for the majority of the Oro projects. It allows for easy distribution of the source code and keeps each change under version control.
+
+`GitHub <https://github.com/>`_ is our main collaborative development tool, so if you do not have an account yet, please `sign up <https://github.com/join>`_.
+
+There is a number of tools to manage git repositories, for instance:
+
+- CLI git tools
+- PhpStorm Git Integration plugin
+- SourceTree
+- SmartGit, to name a few
+
+
+Submit a Pull Request
+---------------------
+
+The best way to contribute a bug fix or enhancement is to submit a pull request to the `OroCommerce <http://github.com/orocommerce/application>`_ repository on GitHub.
+
+Before you submit your pull request consider the following guidelines:
+
+* Search GitHub for an open or closed pull request that relates to your submission. You do not want to duplicate effort.
+* Please sign our :ref:`Contributor License Agreement <contributing--cla>` (CLA) before submitting pull requests. The CLA must be signed for any code or documentation changes to be accepted.
+
+Add a Commit Message
+--------------------
+
+The merge commit message contains the message from the author of the changes. This can help understand what the changes were about and the reasoning behind the changes. Therefore, commit messages should include a list of performed actions or changes in the code:
+
+<Commit summary>
+
+- <action 1>
+- <action 2>
+- <action 3>
+- ...
+
+See Also
+--------
+
+:ref:`Code Style <doc--community--code-style>`
+
+:ref:`Set Up a Development Environment <doc--dev-env-best-practices>`
+
+:ref:`Contribute to Translations <doc--community--ui-translations>`
+
+:ref:`Contribute to Documentation <documentation-standards>`
+
+:ref:`Report an Issue <doc--community--issue-report>`
+
+:ref:`Report a Security Issue <reporting-security-issues>`
+
+:ref:`Contact Community <doc--community--contact-community>`
+
+:ref:`Release Process <doc--community--release>`

community/contact_community.rst

@@ -0,0 +1,20 @@
+.. _doc--community--contact-community:
+
+Contact Community
+-----------------
+
+.. begin
+
+**Thank you for helping us make the Oro products better!**
+
+If you have questions or ideas about how to use, configure, extend or customize OroPlatform, OroCommerce or OroCRM, please direct these to our community forums:
+
+* `OroPlatform community forum <http://www.orocrm.com/forums/forum/oro-platform>`_
+* `OroCommerce community forum <https://www.orocommerce.com/forum>`_
+* `OroCRM community forum <http://www.orocrm.com/forums/forum/orocrm>`_
+
+
+If you would like to join our community team chat channel on `Slack <https://orocommunity.slack.com/>`_,
+please request an invitation: **slack [at] oroinc.com**
+
+.. finish