##// END OF EJS Templates
docs: updates to contributor documentation #4039
lisaq -
r271:401985cc default
parent child
Show More
@@ -1,47 +1,47
1 README - Quickstart
1 README - Quickstart
2 ===================
2 ===================
3
3
4 This folder contains functional tests and the automation of specification
4 This folder contains the functional tests and automation of specification
5 examples. Details about testing can be found in
5 examples. Details about testing can be found in
6 `/docs-internal/testing/index.rst`.
6 `/docs-internal/testing/index.rst`.
7
7
8
8
9 Setting up your Rhodecode Enterprise instance
9 Setting up your Rhodecode Enterprise instance
10 ---------------------------------------------
10 ---------------------------------------------
11
11
12 The tests will create users and repositories as needed, so you can start with a
12 The tests will create users and repositories as needed, so you can start with a
13 new and empty instance.
13 new and empty instance.
14
14
15 Use the following example call for the database setup of Enterprise::
15 Use the following example call for the database setup of Enterprise::
16
16
17 paster setup-rhodecode \
17 paster setup-rhodecode \
18 --user=admin \
18 --user=admin \
19 --email=admin@example.com \
19 --email=admin@example.com \
20 --password=secret \
20 --password=secret \
21 --api-key=9999999999999999999999999999999999999999 \
21 --api-key=9999999999999999999999999999999999999999 \
22 your-enterprise-config.ini
22 your-enterprise-config.ini
23
23
24 This way the username, password and auth token of the admin user will match the
24 This way the username, password, and auth token of the admin user will match the
25 defaults from the test run.
25 defaults from the test run.
26
26
27
27
28 Usage
28 Usage
29 -----
29 -----
30
30
31 1. Make sure your Rhodecode Enterprise instance is running at
31 1. Make sure your Rhodecode Enterprise instance is running at
32 http://localhost:5000.
32 http://localhost:5000.
33
33
34 2. Enter `nix-shell` from the acceptance_tests folder::
34 2. Enter `nix-shell` from the acceptance_tests folder::
35
35
36 cd acceptance_tests
36 cd acceptance_tests
37 nix-shell -I ~/dev
37 nix-shell
38
38
39 Make sure that `rcpkgs` and `rcnixpkgs` are available on the nix path.
39 Make sure that `rcpkgs` and `rcnixpkgs` are available on the nix path.
40
40
41 3. Run the tests::
41 3. Run the tests::
42
42
43 py.test -c example.ini -vs
43 py.test -c example.ini -vs
44
44
45 The parameter ``-vs`` allows you to see debugging output during the test
45 The parameter ``-vs`` allows you to see debugging output during the test
46 run. Check ``py.test --help`` and the documentation at http://pytest.org to
46 run. Check ``py.test --help`` and the documentation at http://pytest.org to
47 learn all details about the test runner.
47 learn all details about the test runner.
@@ -1,19 +1,19
1 .. _contributing:
1 .. _contributing:
2
2
3 Contributing to RhodeCode
3 Contributing to RhodeCode
4 =========================
4 =========================
5
5
6
6
7
7
8 Welcome to contribution guides and development docs of RhodeCode.
8 Welcome to the contribution guides and development docs of RhodeCode.
9
9
10
10
11
11
12 .. toctree::
12 .. toctree::
13 :maxdepth: 1
13 :maxdepth: 1
14
14
15 testing/index
15 testing/index
16 dev-setup
16 dev-setup
17 db-schema
17 db-schema
18 dev-settings
18 dev-settings
19 api
19 api
@@ -1,52 +1,52
1 =======================
1 =======================
2 DB Schema and Migration
2 DB Schema and Migration
3 =======================
3 =======================
4
4
5 To create or alter tables in the database it's necessary to change a couple of
5 To create or alter tables in the database, it's necessary to change a couple of
6 files, apart from configuring the settings pointing to the latest database
6 files, apart from configuring the settings pointing to the latest database
7 schema.
7 schema.
8
8
9
9
10 Database Model and ORM
10 Database Model and ORM
11 ----------------------
11 ----------------------
12
12
13 On ``rhodecode.model.db`` you will find the database definition of all tables and
13 On ``rhodecode.model.db`` you will find the database definition of all tables and
14 fields. Any fresh install database will be correctly created by the definitions
14 fields. Any freshly installed database will be correctly created by the definitions
15 here. So, any change to this files will affect the tests without having to change
15 here. So, any change to this file will affect the tests without having to change
16 any other file.
16 any other file.
17
17
18 A second layer are the businness classes that are inside ``rhodecode.model``.
18 A second layer are the business classes inside ``rhodecode.model``.
19
19
20
20
21 Database Migration
21 Database Migration
22 ------------------
22 ------------------
23
23
24 Three files play a role when creating database migrations:
24 Three files play a role when creating database migrations:
25
25
26 * Database schema inside ``rhodecode.lib.dbmigrate``
26 * Database schema inside ``rhodecode.lib.dbmigrate``
27 * Database version inside ``rhodecode.lib.dbmigrate``
27 * Database version inside ``rhodecode.lib.dbmigrate``
28 * Configuration ``__dbversion__`` at ``rhodecode.__init__``
28 * Configuration ``__dbversion__`` at ``rhodecode.__init__``
29
29
30
30
31 Schema is a snapshot of the database version BEFORE the migration. So, it's
31 Schema is a snapshot of the database version BEFORE the migration. So, it's
32 the initial state before any changes were added. The name convention is
32 the initial state before any changes were added. The name convention is
33 the latest release version where the snapshot were created, and not the
33 the latest release version where the snapshot was created, and not the
34 target version of this code.
34 target version of this code.
35
35
36 Version is the method that will define how to UPGRADE/DOWNGRADE the database.
36 Version is the method that will define how to UPGRADE/DOWNGRADE the database.
37
37
38 ``rhodecode.__init__`` contains only a variable that defines up to which version of
38 ``rhodecode.__init__`` contains only a variable that defines up to which version of
39 the database will be used to upgrade. Eg.: ``__dbversion__ = 45``
39 the database will be used to upgrade. Eg.: ``__dbversion__ = 45``
40
40
41
41
42 For examples on how to create those files, please see the existing code.
42 For examples on how to create those files, please see the existing code.
43
43
44
44
45 Migration Command
45 Migration Command
46 ^^^^^^^^^^^^^^^^^
46 ^^^^^^^^^^^^^^^^^
47
47
48 After you changed the database ORM and migration files, you can run::
48 After you've changed the database ORM and migration files, you can run::
49
49
50 paster upgrade-db <ini-file>
50 paster upgrade-db <ini-file>
51
51
52 And the database will be upgraded up to the version defined in the ``__init__`` file. No newline at end of file
52 The database will be upgraded up to the version defined in the ``__init__`` file. No newline at end of file
@@ -1,46 +1,46
1
1
2 ==========================
2 ==========================
3 Settings for Development
3 Settings for Development
4 ==========================
4 ==========================
5
5
6
6
7 We have a few settings which are intended to be used only for development
7 We have a few settings which are intended to be used only for development
8 purposes. This section contains an overview of them.
8 purposes. This section contains an overview of them.
9
9
10
10
11
11
12 `debug_style`
12 `debug_style`
13 =============
13 =============
14
14
15 Enables the section "Style" in the application. This section provides an
15 Enables the section "Style" in the application. This section provides an
16 overview of all components which are found in the frontend style of the
16 overview of all components which are found in the frontend of the
17 application.
17 application.
18
18
19
19
20
20
21 `vcs.start_server`
21 `vcs.start_server`
22 ==================
22 ==================
23
23
24 Starts the server as a subprocess while the system comes up. Intended usage is
24 Starts the server as a subprocess while the system comes up. Intended usage is
25 to ease development.
25 to ease development.
26
26
27
27
28
28
29 `[logging]`
29 `[logging]`
30 ===========
30 ===========
31
31
32 Use this to configure loggig to your current needs. The documentation of
32 Use this to configure logging to your current needs. The documentation of
33 Python's `logging` module explains all details. The following snippets are
33 Python's `logging` module explains all of the details. The following snippets
34 useful for day to day development work.
34 are useful for day to day development work.
35
35
36
36
37 Mute SQL output
37 Mute SQL output
38 ---------------
38 ---------------
39
39
40 They come out of the package `sqlalchemy.engine`::
40 They come out of the package `sqlalchemy.engine`::
41
41
42 [logger_sqlalchemy]
42 [logger_sqlalchemy]
43 level = WARNING
43 level = WARNING
44 handlers = console_sql
44 handlers = console_sql
45 qualname = sqlalchemy.engine
45 qualname = sqlalchemy.engine
46 propagate = 0
46 propagate = 0
@@ -1,141 +1,141
1
1
2 ===================
2 ===================
3 Development setup
3 Development setup
4 ===================
4 ===================
5
5
6
6
7 RhodeCode Enterprise runs inside a Nix managed environment. This ensures build
7 RhodeCode Enterprise runs inside a Nix managed environment. This ensures build
8 environment dependencies are correctly declared and installed during setup.
8 environment dependencies are correctly declared and installed during setup.
9 It also enables atomic upgrades, rollbacks, and multiple instances of RhodeCode
9 It also enables atomic upgrades, rollbacks, and multiple instances of RhodeCode
10 Enterprise for efficient cluster management.
10 Enterprise for efficient cluster management.
11
11
12 To set up RhodeCode Enterprise inside the Nix environment use the following steps:
12 To set up RhodeCode Enterprise inside the Nix environment, use the following steps:
13
13
14
14
15
15
16 Setup Nix Package Manager
16 Setup Nix Package Manager
17 -------------------------
17 -------------------------
18
18
19 To install the Nix Package Manager please run::
19 To install the Nix Package Manager, please run::
20
20
21 $ curl https://nixos.org/nix/install | sh
21 $ curl https://nixos.org/nix/install | sh
22
22
23 or go to https://nixos.org/nix/ and follow their installation instructions.
23 or go to https://nixos.org/nix/ and follow the installation instructions.
24 Once this is correctly set up on your system you should be able to use the
24 Once this is correctly set up on your system, you should be able to use the
25 following commands:
25 following commands:
26
26
27 * `nix-env`
27 * `nix-env`
28
28
29 * `nix-shell`
29 * `nix-shell`
30
30
31
31
32 .. tip::
32 .. tip::
33
33
34 Update your channels frequently by running ``nix-channel --upgrade``.
34 Update your channels frequently by running ``nix-channel --upgrade``.
35
35
36
36
37 Switch nix to latest STABLE channel
37 Switch nix to the latest STABLE channel
38 -----------------------------------
38 ---------------------------------------
39
39
40 run::
40 run::
41
41
42 nix-channel --add https://nixos.org/channels/nixos-16.03 nixpkgs
42 nix-channel --add https://nixos.org/channels/nixos-16.03 nixpkgs
43
43
44 Followed by::
44 Followed by::
45
45
46 nix-channel --update
46 nix-channel --update
47
47
48
48
49 Clone the required repositories
49 Clone the required repositories
50 -------------------------------
50 -------------------------------
51
51
52 After Nix is set up, clone the RhodeCode Enterprise Community Edition, and
52 After Nix is set up, clone the RhodeCode Enterprise Community Edition and
53 RhodeCode VCSServer repositories into the same directory.
53 RhodeCode VCSServer repositories into the same directory.
54 To do this, use the following example::
54 To do this, use the following example::
55
55
56 mkdir rhodecode-develop && cd rhodecode-develop
56 mkdir rhodecode-develop && cd rhodecode-develop
57 hg clone https://code.rhodecode.com/rhodecode-enterprise-ce
57 hg clone https://code.rhodecode.com/rhodecode-enterprise-ce
58 hg clone https://code.rhodecode.com/rhodecode-vcsserver
58 hg clone https://code.rhodecode.com/rhodecode-vcsserver
59
59
60 .. note::
60 .. note::
61
61
62 If you cannot clone the repository, please request read permissions.
62 If you cannot clone the repository, please request read permissions via support@rhodecode.com
63
63
64
64
65
65
66 Enter the Development Shell
66 Enter the Development Shell
67 ---------------------------
67 ---------------------------
68
68
69 The final step is to start into the development shell. To do this run the
69 The final step is to start the development shell. To do this, run the
70 following command from inside the cloned repository::
70 following command from inside the cloned repository::
71
71
72 cd ~/rhodecode-enterprise-ce
72 cd ~/rhodecode-enterprise-ce
73 nix-shell --arg dev true
73 nix-shell
74
74
75 .. note::
75 .. note::
76
76
77 On the first run, this will take a while to download and optionally compile
77 On the first run, this will take a while to download and optionally compile
78 a few things. The next runs of it will be faster.
78 a few things. The following runs will be faster.
79
79
80
80
81
81
82 Creating a Development Configuration
82 Creating a Development Configuration
83 ------------------------------------
83 ------------------------------------
84
84
85 To create a development environment for RhodeCode Enterprise,
85 To create a development environment for RhodeCode Enterprise,
86 use the following steps:
86 use the following steps:
87
87
88 1. Create a copy of `~/rhodecode-enterprise-ce/configs/development.ini`
88 1. Create a copy of `~/rhodecode-enterprise-ce/configs/development.ini`
89 2. Adjust the configuration settings to your needs
89 2. Adjust the configuration settings to your needs
90
90
91 .. note::
91 .. note::
92
92
93 It is recommended to call it `dev.ini`.
93 It is recommended to use the name `dev.ini`.
94
94
95
95
96 Setup the Development Database
96 Setup the Development Database
97 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
97 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
98
98
99 To create a development database use the following example. This is a one
99 To create a development database, use the following example. This is a one
100 time operation::
100 time operation::
101
101
102 paster setup-rhodecode dev.ini \
102 paster setup-rhodecode dev.ini \
103 --user=admin --password=secret \
103 --user=admin --password=secret \
104 --email=admin@example.com \
104 --email=admin@example.com \
105 --repos=~/my_dev_repos
105 --repos=~/my_dev_repos
106
106
107
107
108 Start the Development Server
108 Start the Development Server
109 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
109 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
110
110
111 When starting the development server, you should start the vcsserver as a
111 When starting the development server, you should start the vcsserver as a
112 separate process. To do this use one of the following examples:
112 separate process. To do this, use one of the following examples:
113
113
114 1. Set the `start.vcs_server` flag in the ``dev.ini`` file to true. For example:
114 1. Set the `start.vcs_server` flag in the ``dev.ini`` file to true. For example:
115
115
116 .. code-block:: python
116 .. code-block:: python
117
117
118 ### VCS CONFIG ###
118 ### VCS CONFIG ###
119 ##################
119 ##################
120 vcs.start_server = true
120 vcs.start_server = true
121 vcs.server = localhost:9900
121 vcs.server = localhost:9900
122 vcs.server.log_level = debug
122 vcs.server.log_level = debug
123
123
124 Then start the server using the following command: ``rcserver dev.ini``
124 Then start the server using the following command: ``rcserver dev.ini``
125
125
126 2. Start the development server using the following example::
126 2. Start the development server using the following example::
127
127
128 rcserver --with-vcsserver dev.ini
128 rcserver --with-vcsserver dev.ini
129
129
130 3. Start the development server in a different terminal using the following
130 3. Start the development server in a different terminal using the following
131 example::
131 example::
132
132
133 vcsserver
133 vcsserver
134
134
135
135
136 Run the Environment Tests
136 Run the Environment Tests
137 ^^^^^^^^^^^^^^^^^^^^^^^^^
137 ^^^^^^^^^^^^^^^^^^^^^^^^^
138
138
139 Please make sure that the test are passing to verify that your environment is
139 Please make sure that the tests are passing to verify that your environment is
140 set up correctly. More details about the tests are described in:
140 set up correctly. More details about the tests are described in:
141 :file:`/docs/dev/testing`.
141 :file:`/docs/dev/testing`.
@@ -1,28 +1,28
1
1
2
2
3 ============================
3 ============================
4 Testing and Specifications
4 Testing and Specifications
5 ============================
5 ============================
6
6
7
7
8 .. toctree::
8 .. toctree::
9 :maxdepth: 2
9 :maxdepth: 2
10
10
11 unit-and-functional
11 unit-and-functional
12 spec-by-example
12 spec-by-example
13 naming-conventions
13 naming-conventions
14
14
15
15
16
16
17 Overview
17 Overview
18 ========
18 ========
19
19
20 We have a quite big test suite inside of :file:`rhodecode/tests` which is a mix
20 We have a quite large test suite inside of :file:`rhodecode/tests` which is a mix
21 of unit tests and functional or integration tests. More details are in
21 of unit tests and functional or integration tests. More details are in
22 :ref:`test-unit-and-functional`.
22 :ref:`test-unit-and-functional`.
23
23
24
24
25 Apart from that we start to apply "Specification by Example" and maintain a
25 Apart from that, we are starting to apply "Specification by Example" and maintain
26 collection of such specifications together with an implementation so that it can
26 a collection of such specifications together with an implementation so that it
27 be validated in an automatic way. The files can be found in
27 can be validated in an automatic way. The files can be found in
28 :file:`acceptance_tests`. More details are in :ref:`test-spec-by-example`.
28 :file:`acceptance_tests`. More details are in :ref:`test-spec-by-example`.
@@ -1,75 +1,75
1
1
2 .. _test-spec-by-example:
2 .. _test-spec-by-example:
3
3
4 ==========================
4 ==========================
5 Specification by Example
5 Specification by Example
6 ==========================
6 ==========================
7
7
8
8
9 .. Avoid duplicating the quickstart instructions by importing the README
9 .. Avoid duplicating the quickstart instructions by importing the README
10 file.
10 file.
11
11
12 .. include:: ../../../acceptance_tests/README.rst
12 .. include:: ../../../acceptance_tests/README.rst
13
13
14
14
15
15
16 Choices of technology and tools
16 Choices of technology and tools
17 ===============================
17 ===============================
18
18
19
19
20 `nix` as runtime environment
20 `nix` as runtime environment
21 ----------------------------
21 ----------------------------
22
22
23 We settled to use the `nix` tools to provide us the needed environment for
23 We settled to use the `nix` tools to provide us the needed environment for
24 running the tests.
24 running the tests.
25
25
26
26
27
27
28 `Gherkins` as specification language
28 `Gherkins` as specification language
29 ------------------------------------
29 ------------------------------------
30
30
31 To specify by example, we settled on Gherkins as the semi-formal specification
31 To specify by example, we settled on Gherkins as the semi-formal specification
32 language.
32 language.
33
33
34
34
35 `py.test` as a runner
35 `py.test` as a runner
36 ---------------------
36 ---------------------
37
37
38 After experimenting with `behave` and `py.test` our choice was `pytest-bdd`
38 After experimenting with `behave` and `py.test` our choice was `pytest-bdd`
39 because it allows us to use our existing knowledge about `py.test` and avoids
39 because it allows us to use our existing knowledge about `py.test` and avoids
40 that we have to learn another tool.
40 that we have to learn another tool.
41
41
42
42
43
43
44 Concepts
44 Concepts
45 ========
45 ========
46
46
47 The logic is structured around the design pattern of "page objects". The
47 The logic is structured around the design pattern of "page objects". The
48 documentation of `python-selemium` contains a few more details about this
48 documentation of `python-selemium` contains a few more details about this
49 pattern.
49 pattern.
50
50
51
51
52
52
53 Page Objects
53 Page Objects
54 ------------
54 ------------
55
55
56 We introduce an abstraction class for every page which we have to interact with
56 We introduce an abstraction class for every page which we have to interact with
57 in order to validate the specifications.
57 in order to validate the specifications.
58
58
59 The implementation for the page objects is inside of the module
59 The implementation for the page objects is inside of the module
60 :mod:`page_objects`. The class :class:`page_objects.base.BasePage` should be
60 :mod:`page_objects`. The class :class:`page_objects.base.BasePage` should be
61 used as a base for all page object implementations.
61 used as a base for all page object implementations.
62
62
63
63
64
64
65 Locators
65 Locators
66 --------
66 --------
67
67
68 The specific information how to locate an element inside of the DOM tree of a
68 The specific information how to locate an element inside of the DOM tree of a
69 page is kept in a separate class. This class serves mainly as a data container,
69 page is kept in a separate class. This class serves mainly as a data container;
70 it shall not contain any logic.
70 it shall not contain any logic.
71
71
72 The reason for keeping the locators separate is that we expect a frequent need
72 The reason for keeping the locators separate is that we expect a frequent need
73 for change whenever we work on our templates. In such a case it is more
73 for change whenever we work on our templates. In such a case, it is more
74 efficient to have all locators together and update them there instead of having
74 efficient to have all of thelocators together and update them there instead of
75 to find all locators inside of the logic of a page object.
75 having to find every locator inside of the logic of a page object.
@@ -1,61 +1,61
1
1
2 .. _test-unit-and-functional:
2 .. _test-unit-and-functional:
3
3
4 ===========================
4 ===========================
5 Unit and Functional Tests
5 Unit and Functional Tests
6 ===========================
6 ===========================
7
7
8
8
9
9
10 py.test based test suite
10 py.test based test suite
11 ========================
11 ========================
12
12
13
13
14 The test suite is in the folder :file:`rhodecode/tests/` and should be run with
14 The test suite is in the folder :file:`rhodecode/tests/` and should be run with
15 the test runner `py.test` inside of your `nix-shell` environment::
15 the test runner `py.test` inside of your `nix-shell` environment::
16
16
17 # In case you need the cythonized version
17 # In case you need the cythonized version
18 CYTHONIZE=1 python setup.py develop --prefix=$tmp_path
18 CYTHONIZE=1 python setup.py develop --prefix=$tmp_path
19
19
20 py.test rhodecode
20 py.test rhodecode
21
21
22
22
23
23
24 py.test integration
24 py.test integration
25 -------------------
25 -------------------
26
26
27 The integration with the test runner is based on the following three parts:
27 The integration with the test runner is based on the following three parts:
28
28
29 - `pytest_pylons` is a py.test plugin which does the integration with the
29 - `pytest_pylons` is a py.test plugin which does the integration with the
30 Pylons web framework. It sets up the Pylons environment based on a given ini
30 Pylons web framework. It sets up the Pylons environment based on the given ini
31 file.
31 file.
32
32
33 Tests which depend on the Pylons environment to be set up must request the
33 Tests which depend on the Pylons environment to be set up must request the
34 fixture `pylonsapp`.
34 fixture `pylonsapp`.
35
35
36 - :file:`rhodecode/tests/plugin.py` contains the integration of py.test with
36 - :file:`rhodecode/tests/plugin.py` contains the integration of py.test with
37 RhodeCode Enterprise itself.
37 RhodeCode Enterprise itself.
38
38
39 - :file:`conftest.py` plugins are used to provide a special integration for
39 - :file:`conftest.py` plugins are used to provide a special integration for
40 certain groups of tests based on the directory location.
40 certain groups of tests based on the directory location.
41
41
42
42
43
43
44 VCS backend selection
44 VCS backend selection
45 ---------------------
45 ---------------------
46
46
47 The py.test integration provides a parameter `--backends`. It will skip all
47 The py.test integration provides a parameter `--backends`. It will skip all
48 tests which are marked for other backends.
48 tests which are marked for other backends.
49
49
50 To run only Subversion tests::
50 To run only Subversion tests::
51
51
52 py.test rhodecode --backends=svn
52 py.test rhodecode --backends=svn
53
53
54
54
55
55
56 Frontend / Styling support
56 Frontend / Styling support
57 ==========================
57 ==========================
58
58
59 All relevant style components have an example inside of the "Style" section
59 All relevant style components have an example inside of the "Style" section
60 within the application. Enable the setting `debug_style` to make this section
60 within the application. Enable the setting `debug_style` to make this section
61 visible in your local instance of the application.
61 visible in your local instance of the application.
General Comments 0
You need to be logged in to leave comments. Login now