docs: updates to contributor documentation #4039

acceptance_tests/README.rst

@@ -1,47 +1,47 b''
 README - Quickstart
 ===================
 
-This folder contains functional tests and the automation of specification
+This folder contains the functional tests and automation of specification
 examples. Details about testing can be found in
 `/docs-internal/testing/index.rst`.
 
 
 Setting up your Rhodecode Enterprise instance
 ---------------------------------------------
 
 The tests will create users and repositories as needed, so you can start with a
 new and empty instance.
 
 Use the following example call for the database setup of Enterprise::
 
    paster setup-rhodecode \
      --user=admin \
      --email=[e-mail] \
      --password=secret \
      --api-key=9999999999999999999999999999999999999999 \
      your-enterprise-config.ini
 
-This way the username, password and auth token of the admin user will match the
+This way the username, password, and auth token of the admin user will match the
 defaults from the test run.
 
 
 Usage
 -----
 
 1. Make sure your Rhodecode Enterprise instance is running at
    http://localhost:5000.
 
 2. Enter `nix-shell` from the acceptance_tests folder::
 
      cd acceptance_tests
-     nix-shell -I ~/dev
+     nix-shell
 
    Make sure that `rcpkgs` and `rcnixpkgs` are available on the nix path.
 
 3. Run the tests::
 
      py.test -c example.ini -vs
 
    The parameter ``-vs`` allows you to see debugging output during the test
    run. Check ``py.test --help`` and the documentation at http://pytest.org to
    learn all details about the test runner.

docs/contributing/contributing.rst

@@ -1,19 +1,19 b''
 .. _contributing:
 
 Contributing to RhodeCode
 =========================
 
 
 
-Welcome to contribution guides and development docs of RhodeCode.
+Welcome to the contribution guides and development docs of RhodeCode.
 
 
 
 .. toctree::
    :maxdepth: 1
 
    testing/index
    dev-setup
    db-schema
    dev-settings
    api

docs/contributing/db-schema.rst

@@ -1,52 +1,52 b''
 =======================
 DB Schema and Migration
 =======================
 
-To create or alter tables in the database it's necessary to change a couple of
+To create or alter tables in the database, it's necessary to change a couple of
 files, apart from configuring the settings pointing to the latest database
 schema.
 
 
 Database Model and ORM
 ----------------------
 
 On ``rhodecode.model.db`` you will find the database definition of all tables and 
-fields. Any fresh install database will be correctly created by the definitions 
-here. So, any change to this files will affect the tests without having to change
+fields. Any freshly installed database will be correctly created by the definitions 
+here. So, any change to this file will affect the tests without having to change
 any other file.
 
-A second layer are the businness classes that are inside ``rhodecode.model``. 
+A second layer are the business classes inside ``rhodecode.model``. 
 
 
 Database Migration
 ------------------
 
 Three files play a role when creating database migrations:
 
     * Database schema inside ``rhodecode.lib.dbmigrate``
     * Database version inside ``rhodecode.lib.dbmigrate`` 
     * Configuration ``__dbversion__`` at ``rhodecode.__init__``
 
 
 Schema is a snapshot of the database version BEFORE the migration. So, it's
 the initial state before any changes were added. The name convention is
-the latest release version where the snapshot were created, and not the 
+the latest release version where the snapshot was created, and not the 
 target version of this code.
 
 Version is the method that will define how to UPGRADE/DOWNGRADE the database.
 
 ``rhodecode.__init__`` contains only a variable that defines up to which version of 
 the database will be used to upgrade. Eg.: ``__dbversion__ = 45``
 
 
 For examples on how to create those files, please see the existing code.
 
 
 Migration Command
 ^^^^^^^^^^^^^^^^^
 
-After you changed the database ORM and migration files, you can run::
+After you've changed the database ORM and migration files, you can run::
 
    paster upgrade-db <ini-file> 
 
-And the database will be upgraded up to the version defined in the ``__init__`` file.
  No newline at end of file
+The database will be upgraded up to the version defined in the ``__init__`` file.
  No newline at end of file

docs/contributing/dev-settings.rst

@@ -1,46 +1,46 b''
 
 ==========================
  Settings for Development
 ==========================
 
 
 We have a few settings which are intended to be used only for development
 purposes. This section contains an overview of them.
 
 
 
 `debug_style`
 =============
 
 Enables the section "Style" in the application. This section provides an
-overview of all components which are found in the frontend style of the
+overview of all components which are found in the frontend of the
 application.
 
 
 
 `vcs.start_server`
 ==================
 
 Starts the server as a subprocess while the system comes up. Intended usage is
 to ease development.
 
 
 
 `[logging]`
 ===========
 
-Use this to configure loggig to your current needs. The documentation of
-Python's `logging` module explains all details. The following snippets are
-useful for day to day development work.
+Use this to configure logging to your current needs. The documentation of
+Python's `logging` module explains all of the details. The following snippets
+are useful for day to day development work.
 
 
 Mute SQL output
 ---------------
 
 They come out of the package `sqlalchemy.engine`::
 
   [logger_sqlalchemy]
   level = WARNING
   handlers = console_sql
   qualname = sqlalchemy.engine
   propagate = 0

docs/contributing/dev-setup.rst

@@ -1,141 +1,141 b''
 
 ===================
  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 for efficient cluster management.
 
-To set up RhodeCode Enterprise inside the Nix environment use the following steps:
+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::
+To install the Nix Package Manager, please run::
 
    $ curl https://nixos.org/nix/install | sh
 
-or go to https://nixos.org/nix/ and follow their installation instructions.
-Once this is correctly set up on your system you should be able to use the
+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 latest STABLE channel
------------------------------------
+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
+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.
+   If you cannot clone the repository, please request read permissions via [e-mail]
 
 
 
 Enter the Development Shell
 ---------------------------
 
-The final step is to start into the development shell. To do this run the
+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 --arg dev true
+   nix-shell
 
 .. note::
 
    On the first run, this will take a while to download and optionally compile
-   a few things. The next runs of it will be faster.
+   a few things. The following runs will be faster.
 
 
 
 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 call it `dev.ini`.
+      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
+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
 
 
 Start the Development Server
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 When starting the development server, you should start the vcsserver as a
-separate process. To do this use one of the following examples:
+separate process. To do this, use one of the following examples:
 
 1. Set the `start.vcs_server` flag in the ``dev.ini`` file to true. For example:
 
    .. code-block:: python
 
       ### VCS CONFIG ###
       ##################
       vcs.start_server = true
       vcs.server = localhost:9900
       vcs.server.log_level = debug
 
    Then start the server using the following command: ``rcserver dev.ini``
 
 2. Start the development server using the following example::
 
       rcserver --with-vcsserver dev.ini
 
 3. Start the development server in a different terminal using the following
    example::
 
       vcsserver
 
 
 Run the Environment Tests
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Please make sure that the test are passing to verify that your environment is
+Please make sure that the tests are passing to verify that your environment is
 set up correctly. More details about the tests are described in:
 :file:`/docs/dev/testing`.

docs/contributing/testing/index.rst

@@ -1,28 +1,28 b''
 
 
 ============================
  Testing and Specifications
 ============================
 
 
 .. toctree::
    :maxdepth: 2
 
    unit-and-functional
    spec-by-example
    naming-conventions
 
 
 
 Overview
 ========
 
-We have a quite big test suite inside of :file:`rhodecode/tests` which is a mix
+We have a quite large test suite inside of :file:`rhodecode/tests` which is a mix
 of unit tests and functional or integration tests. More details are in
 :ref:`test-unit-and-functional`.
 
 
-Apart from that we start to apply "Specification by Example" and maintain a
-collection of such specifications together with an implementation so that it can
-be validated in an automatic way. The files can be found in
+Apart from that, we are starting to apply "Specification by Example" and maintain
+a collection of such specifications together with an implementation so that it
+can be validated in an automatic way. The files can be found in
 :file:`acceptance_tests`. More details are in :ref:`test-spec-by-example`.

docs/contributing/testing/spec-by-example.rst

@@ -1,75 +1,75 b''
 
 .. _test-spec-by-example:
 
 ==========================
  Specification by Example
 ==========================
 
 
 .. Avoid duplicating the quickstart instructions by importing the README
    file.
 
 .. include:: ../../../acceptance_tests/README.rst
 
 
 
 Choices of technology and tools
 ===============================
 
 
 `nix` as runtime environment
 ----------------------------
 
 We settled to use the `nix` tools to provide us the needed environment for
 running the tests.
 
 
 
 `Gherkins` as specification language
 ------------------------------------
 
 To specify by example, we settled on Gherkins as the semi-formal specification
 language.
 
 
 `py.test` as a runner
 ---------------------
 
 After experimenting with `behave` and `py.test` our choice was `pytest-bdd`
 because it allows us to use our existing knowledge about `py.test` and avoids
 that we have to learn another tool.
 
 
 
 Concepts
 ========
 
 The logic is structured around the design pattern of "page objects". The
 documentation of `python-selemium` contains a few more details about this
 pattern.
 
 
 
 Page Objects
 ------------
 
 We introduce an abstraction class for every page which we have to interact with
 in order to validate the specifications.
 
 The implementation for the page objects is inside of the module
 :mod:`page_objects`. The class :class:`page_objects.base.BasePage` should be
 used as a base for all page object implementations.
 
 
 
 Locators
 --------
 
 The specific information how to locate an element inside of the DOM tree of a
-page is kept in a separate class. This class serves mainly as a data container,
+page is kept in a separate class. This class serves mainly as a data container;
 it shall not contain any logic.
 
 The reason for keeping the locators separate is that we expect a frequent need
-for change whenever we work on our templates. In such a case it is more
-efficient to have all locators together and update them there instead of having
-to find all locators inside of the logic of a page object.
+for change whenever we work on our templates. In such a case, it is more
+efficient to have all of thelocators together and update them there instead of
+having to find every locator inside of the logic of a page object.

docs/contributing/testing/unit-and-functional.rst

@@ -1,61 +1,61 b''
 
 .. _test-unit-and-functional:
 
 ===========================
  Unit and Functional Tests
 ===========================
 
 
 
 py.test based test suite
 ========================
 
 
 The test suite is in the folder :file:`rhodecode/tests/` and should be run with
 the test runner `py.test` inside of your `nix-shell` environment::
 
    # In case you need the cythonized version
    CYTHONIZE=1 python setup.py develop --prefix=$tmp_path
 
    py.test rhodecode
 
 
 
 py.test integration
 -------------------
 
 The integration with the test runner is based on the following three parts:
 
 - `pytest_pylons` is a py.test plugin which does the integration with the
-  Pylons web framework. It sets up the Pylons environment based on a given ini
+  Pylons web framework. It sets up the Pylons environment based on the given ini
   file.
 
   Tests which depend on the Pylons environment to be set up must request the
   fixture `pylonsapp`.
 
 - :file:`rhodecode/tests/plugin.py` contains the integration of py.test with
   RhodeCode Enterprise itself.
 
 - :file:`conftest.py` plugins are used to provide a special integration for
   certain groups of tests based on the directory location.
 
 
 
 VCS backend selection
 ---------------------
 
 The py.test integration provides a parameter `--backends`. It will skip all
 tests which are marked for other backends.
 
 To run only Subversion tests::
 
    py.test rhodecode --backends=svn
 
 
 
 Frontend / Styling support
 ==========================
 
 All relevant style components have an example inside of the "Style" section
 within the application. Enable the setting `debug_style` to make this section
 visible in your local instance of the application.