docs: mention working with frontend using grunt and polymer

docs/contributing/dev-setup.rst

@@ -1,157 +1,160 b''
 .. _dev-setup:
 
 ===================
  Development setup
 ===================
 
 
 RhodeCode Enterprise runs inside a Nix managed environment. This ensures build
 environment dependencies are correctly declared and installed during setup.
 It also enables atomic upgrades, rollbacks, and multiple instances of RhodeCode
 Enterprise running with isolation.
 
 To set up RhodeCode Enterprise inside the Nix environment, use the following steps:
 
 
 
 Setup Nix Package Manager
 -------------------------
 
 To install the Nix Package Manager, please run::
 
    $ curl https://nixos.org/nix/install | sh
 
 or go to https://nixos.org/nix/ and follow the installation instructions.
 Once this is correctly set up on your system, you should be able to use the
 following commands:
 
 * `nix-env`
 
 * `nix-shell`
 
 
 .. tip::
 
    Update your channels frequently by running ``nix-channel --upgrade``.
 
 
 Switch nix to the latest STABLE channel
 ---------------------------------------
 
 run::
 
    nix-channel --add https://nixos.org/channels/nixos-16.03 nixpkgs
 
 Followed by::
 
    nix-channel --update
 
 
 Clone the required repositories
 -------------------------------
 
 After Nix is set up, clone the RhodeCode Enterprise Community Edition and
 RhodeCode VCSServer repositories into the same directory.
 To do this, use the following example::
 
     mkdir rhodecode-develop && cd rhodecode-develop
     hg clone https://code.rhodecode.com/rhodecode-enterprise-ce
     hg clone https://code.rhodecode.com/rhodecode-vcsserver
 
 .. note::
 
    If you cannot clone the repository, please request read permissions
    via [e-mail]
 
 
 
 Enter the Development Shell
 ---------------------------
 
 The final step is to start the development shell. To do this, run the
 following command from inside the cloned repository::
 
    cd ~/rhodecode-enterprise-ce
    nix-shell
 
 .. note::
 
    On the first run, this will take a while to download and optionally compile
    a few things. The following runs will be faster. The development shell works
    fine on both MacOS and Linux platforms.
 
 
 
 Creating a Development Configuration
 ------------------------------------
 
 To create a development environment for RhodeCode Enterprise,
 use the following steps:
 
 1. Create a copy of `~/rhodecode-enterprise-ce/configs/development.ini`
 2. Adjust the configuration settings to your needs
 
 .. note::
 
   It is recommended to use the name `dev.ini`.
 
 
 Setup the Development Database
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 To create a development database, use the following example. This is a one
 time operation::
 
     paster setup-rhodecode dev.ini \
         --user=admin --password=secret \
         --email=[e-mail] \
         --repos=~/my_dev_repos
 
 
 Compile CSS and JavaScript
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-To use the application's frontend, you will need to compile the CSS and
-JavaScript with Grunt. This is easily done from within the nix-shell using the
-following command::
+To use the application's frontend and prepare it for production deployment,
+you will need to compile the CSS and JavaScript with Grunt.
+This is easily done from within the nix-shell using the following command::
+
+    grunt
 
-    make web-build
+When developing new features you will need to recompile following any
+changes made to the CSS or JavaScript files when developing the code::
 
-You will need to recompile following any changes made to the CSS or JavaScript
-files.
+    grunt watch
 
+This prepares the development (with comments/whitespace) versions of files.
 
 Start the Development Server
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 From the rhodecode-vcsserver directory, start the development server in another
 nix-shell, using the following command::
 
       pserve configs/development.ini http_port=9900
 
 In the adjacent nix-shell which you created for your development server, you may
 now start CE with the following command::
 
 
       rcserver dev.ini
 
 .. note::
 
   To automatically refresh - and recompile the frontend assets - when changes
   are made in the source code, you can use the option `--reload`.
 
 
 Run the Environment Tests
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Please make sure that the tests are passing to verify that your environment is
 set up correctly. RhodeCode uses py.test to run tests.
 While your instance is running, start a new nix-shell and simply run
 ``make test`` to run the basic test suite.
 
 
 Need Help?
 ^^^^^^^^^^
 
 Join us on Slack via https://rhodecode.com/join or post questions in our
 Community Portal at https://community.rhodecode.com

docs/contributing/standards.rst

@@ -1,177 +1,182 b''
 
 ======================
 Contribution Standards
 ======================
 
 Standards help to improve the quality of our product and its development. Herein
 we define our standards for processes and development to maintain consistency
 and function well as a community. It is a work in progress; modifications to this
 document should be discussed and agreed upon by the community.
 
 
 --------------------------------------------------------------------------------
 
 Code
 ====
 
 This provides an outline for standards we use in our codebase to keep our code
 easy to read and easy to maintain. Much of our code guidelines are based on the
 book `Clean Code <http://www.pearsonhighered.com/educator/product/Clean-Code-A-Handbook-of-Agile-Software-Craftsmanship/9780132350884.page>`_
 by Robert Martin.
 
 We maintain a Tech Glossary to provide consistency in terms and symbolic names
 used for items and concepts within the application. This is found in the CE
 project in /docs-internal/glossary.rst
 
 
 Refactoring
 -----------
 Make it better than you found it!
 
 Our codebase can always use improvement and often benefits from refactoring.
 New code should be refactored as it is being written, and old code should be
 treated with the same care as if it was new. Before doing any refactoring,
 ensure that there is test coverage on the affected code; this will help
 minimize issues.
 
 
 Python
 ------
 For Python, we use `PEP8 <https://www.python.org/dev/peps/pep-0008/>`_.
 We adjust lines of code to under 80 characters and use 4 spaces for indentation.
 
 
 JavaScript
 ----------
 This currently remains undefined. Suggestions welcome!
 
+However, we have decided to go forward with W3C standards and picked
+WebComponents as the foundation of user interface. New functionality should
+be implemented as components using the
+`Polymer Project` <https://www.polymer-project.org>`_ library
+and should avoid external dependencies like `jquery`.
 
 HTML
 ----
 Unfortunately, we currently have no strict HTML standards, but there are a few
 guidelines we do follow. Templates must work in all modern browsers. HTML should
 be clean and easy to read, and additionally should be free of inline CSS or
 JavaScript. It is recommended to use data attributes for JS actions where
 possible in order to separate it from styling and prevent unintentional changes.
 
 
 LESS/CSS
 --------
 We use LESS for our CSS; see :doc:`frontend` for structure and formatting
 guidelines.
 
 
 Linters
 -------
 Currently, we have a linter for pull requests which checks code against PEP8.
 We intend to add more in the future as we clarify standards.
 
 
 --------------------------------------------------------------------------------
 
 Naming Conventions
 ==================
 
 These still need to be defined for naming everything from Python variables to
 HTML classes to files and folders.
 
 
 --------------------------------------------------------------------------------
 
 Testing
 =======
 
 Testing is a very important aspect of our process, especially as we are our own
 quality control team. While it is of course unrealistic to hit every potential
 combination, our goal is to cover every line of Python code with a test. 
 
 The following is a brief introduction to our test suite. Our tests are primarily
 written using `py.test <http://pytest.org/>`_
 
 
 Acceptance Tests
 ----------------
 Also known as "ac tests", these test from the user and business perspective to
 check if the requirements of a feature are met. Scenarios are created at a
 feature's inception and help to define its value.
 
 py.test is used for ac tests; they are located in a repo separate from the
 other tests which follow. Each feature has a .feature file which contains a
 brief description and the scenarios to be tested.
 
 
 Functional Tests
 ----------------
 These test specific functionality in the application which checks through the
 entire stack. Typically these are user actions or permissions which go through
 the web browser. They are located in rhodecode/tests.
 
 
 Unit Tests
 ----------
 These test isolated, individual modules to ensure that they function correctly.
 They are located in rhodecode/tests.
 
 
 Integration Tests
 -----------------
 These are used for testing performance of larger systems than the unit tests.
 They are located in rhodecode/tests.
 
 
 JavaScript Testing
 ------------------
 Currently, we have not defined how to test our JavaScript code.
 
 
 --------------------------------------------------------------------------------
 
 Pull Requests
 =============
 
 Pull requests should generally contain only one thing: a single feature, one bug
 fix, etc.. The commit history should be concise and clean, and the pull request
 should contain the ticket number (also a good idea for the commits themselves)
 to provide context for the reviewer.
 
 See also: :doc:`checklist-pull-request`
 
 
 Reviewers
 ---------
 Each pull request must be approved by at least one member of the RhodeCode
 team. Assignments may be based on expertise or familiarity with a particular
 area of code, or simply availability. Switching up or adding extra community
 members for different pull requests helps to share knowledge as well as provide
 other perspectives.
 
 
 Responsibility
 --------------
 The community is responsible for maintaining features and this must be taken
 into consideration. External contributions must be held to the same standards
 as internal contributions.
 
 
 Feature Switch
 --------------
 Experimental and work-in-progress features can be hidden behind one of two
 switches:
 
 * A setting can be added to the Labs page in the Admin section which may allow
   customers to access and toggle additional features.
 * For work-in-progress or other features where customer access is not desired,
   use a custom setting in the .ini file as a trigger.
 
 
 --------------------------------------------------------------------------------
 
 Tickets
 =======
 
 Redmine tickets are a crucial part of our development process. Any code added or
 changed in our codebase should have a corresponding ticket to document it. With
 this in mind, it is important that tickets be as clear and concise as possible,
 including what the expected outcome is.
 
 See also: :doc:`checklist-tickets`