docs: updates to contributor documentation #4039

acceptance_tests/README.rst

@@ -1,7 +1,7 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`.
 
@@ -21,7 +21,7 b' Use the following example call for the d'
      --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.
 
 
@@ -34,7 +34,7 b' 1. Make sure your Rhodecode Enterprise i'
 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.
 

docs/contributing/contributing.rst

@@ -5,7 +5,7 b' Contributing to RhodeCode'
 
 
 
-Welcome to contribution guides and development docs of RhodeCode.
+Welcome to the contribution guides and development docs of RhodeCode.
 
 
 

docs/contributing/db-schema.rst

@@ -2,7 +2,7 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.
 
@@ -11,11 +11,11 b' 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
@@ -30,7 +30,7 b' Three files play a role when creating da'
 
 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.
@@ -45,8 +45,8 b' For examples on how to create those file'
 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

@@ -13,7 +13,7 b' purposes. This section contains an overv'
 =============
 
 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.
 
 
@@ -29,9 +29,9 b' 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

docs/contributing/dev-setup.rst

@@ -9,19 +9,19 b' environment dependencies are correctly d'
 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`
@@ -34,8 +34,8 b' following commands:'
    Update your channels frequently by running ``nix-channel --upgrade``.
 
 
-Switch nix to latest STABLE channel
------------------------------------
+Switch nix to the latest STABLE channel
+---------------------------------------
 
 run::
 
@@ -49,7 +49,7 b' Followed by::'
 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::
 
@@ -59,23 +59,23 b' To do this, use the following example::'
 
 .. 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.
 
 
 
@@ -90,13 +90,13 b' 2. Adjust the configuration settings to '
 
    .. 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 \
@@ -109,7 +109,7 b' 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:
 
@@ -136,6 +136,6 b' 3. Start the development server in a dif'
 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

@@ -17,12 +17,12 b''
 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

@@ -66,10 +66,10 b' 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

@@ -27,7 +27,7 b' 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