##// END OF EJS Templates
rhodecode-enterprise-ce
RSS
docs: mention working with frontend using grunt and polymer
ergo -
r701:b24d0c2b default
parent child Browse files
Show More
Show file before | Show file after | Hide comments
@@ -1,157 +1,160 b''
1 .. _dev-setup:
1 .. _dev-setup:
2
2
3 ===================
3 ===================
4 Development setup
4 Development setup
5 ===================
5 ===================
6
6
7
7
8 RhodeCode Enterprise runs inside a Nix managed environment. This ensures build
8 RhodeCode Enterprise runs inside a Nix managed environment. This ensures build
9 environment dependencies are correctly declared and installed during setup.
9 environment dependencies are correctly declared and installed during setup.
10 It also enables atomic upgrades, rollbacks, and multiple instances of RhodeCode
10 It also enables atomic upgrades, rollbacks, and multiple instances of RhodeCode
11 Enterprise running with isolation.
11 Enterprise running with isolation.
12
12
13 To set up RhodeCode Enterprise inside the Nix environment, use the following steps:
13 To set up RhodeCode Enterprise inside the Nix environment, use the following steps:
14
14
15
15
16
16
17 Setup Nix Package Manager
17 Setup Nix Package Manager
18 -------------------------
18 -------------------------
19
19
20 To install the Nix Package Manager, please run::
20 To install the Nix Package Manager, please run::
21
21
22 $ curl https://nixos.org/nix/install | sh
22 $ curl https://nixos.org/nix/install | sh
23
23
24 or go to https://nixos.org/nix/ and follow the installation instructions.
24 or go to https://nixos.org/nix/ and follow the installation instructions.
25 Once this is correctly set up on your system, you should be able to use the
25 Once this is correctly set up on your system, you should be able to use the
26 following commands:
26 following commands:
27
27
28 * `nix-env`
28 * `nix-env`
29
29
30 * `nix-shell`
30 * `nix-shell`
31
31
32
32
33 .. tip::
33 .. tip::
34
34
35 Update your channels frequently by running ``nix-channel --upgrade``.
35 Update your channels frequently by running ``nix-channel --upgrade``.
36
36
37
37
38 Switch nix to the latest STABLE channel
38 Switch nix to the latest STABLE channel
39 ---------------------------------------
39 ---------------------------------------
40
40
41 run::
41 run::
42
42
43 nix-channel --add https://nixos.org/channels/nixos-16.03 nixpkgs
43 nix-channel --add https://nixos.org/channels/nixos-16.03 nixpkgs
44
44
45 Followed by::
45 Followed by::
46
46
47 nix-channel --update
47 nix-channel --update
48
48
49
49
50 Clone the required repositories
50 Clone the required repositories
51 -------------------------------
51 -------------------------------
52
52
53 After Nix is set up, clone the RhodeCode Enterprise Community Edition and
53 After Nix is set up, clone the RhodeCode Enterprise Community Edition and
54 RhodeCode VCSServer repositories into the same directory.
54 RhodeCode VCSServer repositories into the same directory.
55 To do this, use the following example::
55 To do this, use the following example::
56
56
57 mkdir rhodecode-develop && cd rhodecode-develop
57 mkdir rhodecode-develop && cd rhodecode-develop
58 hg clone https://code.rhodecode.com/rhodecode-enterprise-ce
58 hg clone https://code.rhodecode.com/rhodecode-enterprise-ce
59 hg clone https://code.rhodecode.com/rhodecode-vcsserver
59 hg clone https://code.rhodecode.com/rhodecode-vcsserver
60
60
61 .. note::
61 .. note::
62
62
63 If you cannot clone the repository, please request read permissions
63 If you cannot clone the repository, please request read permissions
64 via support@rhodecode.com
64 via support@rhodecode.com
65
65
66
66
67
67
68 Enter the Development Shell
68 Enter the Development Shell
69 ---------------------------
69 ---------------------------
70
70
71 The final step is to start the development shell. To do this, run the
71 The final step is to start the development shell. To do this, run the
72 following command from inside the cloned repository::
72 following command from inside the cloned repository::
73
73
74 cd ~/rhodecode-enterprise-ce
74 cd ~/rhodecode-enterprise-ce
75 nix-shell
75 nix-shell
76
76
77 .. note::
77 .. note::
78
78
79 On the first run, this will take a while to download and optionally compile
79 On the first run, this will take a while to download and optionally compile
80 a few things. The following runs will be faster. The development shell works
80 a few things. The following runs will be faster. The development shell works
81 fine on both MacOS and Linux platforms.
81 fine on both MacOS and Linux platforms.
82
82
83
83
84
84
85 Creating a Development Configuration
85 Creating a Development Configuration
86 ------------------------------------
86 ------------------------------------
87
87
88 To create a development environment for RhodeCode Enterprise,
88 To create a development environment for RhodeCode Enterprise,
89 use the following steps:
89 use the following steps:
90
90
91 1. Create a copy of `~/rhodecode-enterprise-ce/configs/development.ini`
91 1. Create a copy of `~/rhodecode-enterprise-ce/configs/development.ini`
92 2. Adjust the configuration settings to your needs
92 2. Adjust the configuration settings to your needs
93
93
94 .. note::
94 .. note::
95
95
96 It is recommended to use the name `dev.ini`.
96 It is recommended to use the name `dev.ini`.
97
97
98
98
99 Setup the Development Database
99 Setup the Development Database
100 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
100 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
101
101
102 To create a development database, use the following example. This is a one
102 To create a development database, use the following example. This is a one
103 time operation::
103 time operation::
104
104
105 paster setup-rhodecode dev.ini \
105 paster setup-rhodecode dev.ini \
106 --user=admin --password=secret \
106 --user=admin --password=secret \
107 --email=admin@example.com \
107 --email=admin@example.com \
108 --repos=~/my_dev_repos
108 --repos=~/my_dev_repos
109
109
110
110
111 Compile CSS and JavaScript
111 Compile CSS and JavaScript
112 ^^^^^^^^^^^^^^^^^^^^^^^^^^
112 ^^^^^^^^^^^^^^^^^^^^^^^^^^
113
113
114 To use the application's frontend, you will need to compile the CSS and
114 To use the application's frontend and prepare it for production deployment,
115 JavaScript with Grunt. This is easily done from within the nix-shell using the
115 you will need to compile the CSS and JavaScript with Grunt.
116 following command::
116 This is easily done from within the nix-shell using the following command::
117
118 grunt
117
119
118 make web-build
120 When developing new features you will need to recompile following any
121 changes made to the CSS or JavaScript files when developing the code::
119
122
120 You will need to recompile following any changes made to the CSS or JavaScript
123 grunt watch
121 files.
122
124
125 This prepares the development (with comments/whitespace) versions of files.
123
126
124 Start the Development Server
127 Start the Development Server
125 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
128 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
126
129
127 From the rhodecode-vcsserver directory, start the development server in another
130 From the rhodecode-vcsserver directory, start the development server in another
128 nix-shell, using the following command::
131 nix-shell, using the following command::
129
132
130 pserve configs/development.ini http_port=9900
133 pserve configs/development.ini http_port=9900
131
134
132 In the adjacent nix-shell which you created for your development server, you may
135 In the adjacent nix-shell which you created for your development server, you may
133 now start CE with the following command::
136 now start CE with the following command::
134
137
135
138
136 rcserver dev.ini
139 rcserver dev.ini
137
140
138 .. note::
141 .. note::
139
142
140 To automatically refresh - and recompile the frontend assets - when changes
143 To automatically refresh - and recompile the frontend assets - when changes
141 are made in the source code, you can use the option `--reload`.
144 are made in the source code, you can use the option `--reload`.
142
145
143
146
144 Run the Environment Tests
147 Run the Environment Tests
145 ^^^^^^^^^^^^^^^^^^^^^^^^^
148 ^^^^^^^^^^^^^^^^^^^^^^^^^
146
149
147 Please make sure that the tests are passing to verify that your environment is
150 Please make sure that the tests are passing to verify that your environment is
148 set up correctly. RhodeCode uses py.test to run tests.
151 set up correctly. RhodeCode uses py.test to run tests.
149 While your instance is running, start a new nix-shell and simply run
152 While your instance is running, start a new nix-shell and simply run
150 ``make test`` to run the basic test suite.
153 ``make test`` to run the basic test suite.
151
154
152
155
153 Need Help?
156 Need Help?
154 ^^^^^^^^^^
157 ^^^^^^^^^^
155
158
156 Join us on Slack via https://rhodecode.com/join or post questions in our
159 Join us on Slack via https://rhodecode.com/join or post questions in our
157 Community Portal at https://community.rhodecode.com
160 Community Portal at https://community.rhodecode.com
Show file before | Show file after | Hide comments
@@ -1,177 +1,182 b''
1
1
2 ======================
2 ======================
3 Contribution Standards
3 Contribution Standards
4 ======================
4 ======================
5
5
6 Standards help to improve the quality of our product and its development. Herein
6 Standards help to improve the quality of our product and its development. Herein
7 we define our standards for processes and development to maintain consistency
7 we define our standards for processes and development to maintain consistency
8 and function well as a community. It is a work in progress; modifications to this
8 and function well as a community. It is a work in progress; modifications to this
9 document should be discussed and agreed upon by the community.
9 document should be discussed and agreed upon by the community.
10
10
11
11
12 --------------------------------------------------------------------------------
12 --------------------------------------------------------------------------------
13
13
14 Code
14 Code
15 ====
15 ====
16
16
17 This provides an outline for standards we use in our codebase to keep our code
17 This provides an outline for standards we use in our codebase to keep our code
18 easy to read and easy to maintain. Much of our code guidelines are based on the
18 easy to read and easy to maintain. Much of our code guidelines are based on the
19 book `Clean Code <http://www.pearsonhighered.com/educator/product/Clean-Code-A-Handbook-of-Agile-Software-Craftsmanship/9780132350884.page>`_
19 book `Clean Code <http://www.pearsonhighered.com/educator/product/Clean-Code-A-Handbook-of-Agile-Software-Craftsmanship/9780132350884.page>`_
20 by Robert Martin.
20 by Robert Martin.
21
21
22 We maintain a Tech Glossary to provide consistency in terms and symbolic names
22 We maintain a Tech Glossary to provide consistency in terms and symbolic names
23 used for items and concepts within the application. This is found in the CE
23 used for items and concepts within the application. This is found in the CE
24 project in /docs-internal/glossary.rst
24 project in /docs-internal/glossary.rst
25
25
26
26
27 Refactoring
27 Refactoring
28 -----------
28 -----------
29 Make it better than you found it!
29 Make it better than you found it!
30
30
31 Our codebase can always use improvement and often benefits from refactoring.
31 Our codebase can always use improvement and often benefits from refactoring.
32 New code should be refactored as it is being written, and old code should be
32 New code should be refactored as it is being written, and old code should be
33 treated with the same care as if it was new. Before doing any refactoring,
33 treated with the same care as if it was new. Before doing any refactoring,
34 ensure that there is test coverage on the affected code; this will help
34 ensure that there is test coverage on the affected code; this will help
35 minimize issues.
35 minimize issues.
36
36
37
37
38 Python
38 Python
39 ------
39 ------
40 For Python, we use `PEP8 <https://www.python.org/dev/peps/pep-0008/>`_.
40 For Python, we use `PEP8 <https://www.python.org/dev/peps/pep-0008/>`_.
41 We adjust lines of code to under 80 characters and use 4 spaces for indentation.
41 We adjust lines of code to under 80 characters and use 4 spaces for indentation.
42
42
43
43
44 JavaScript
44 JavaScript
45 ----------
45 ----------
46 This currently remains undefined. Suggestions welcome!
46 This currently remains undefined. Suggestions welcome!
47
47
48 However, we have decided to go forward with W3C standards and picked
49 WebComponents as the foundation of user interface. New functionality should
50 be implemented as components using the
51 `Polymer Project` <https://www.polymer-project.org>`_ library
52 and should avoid external dependencies like `jquery`.
48
53
49 HTML
54 HTML
50 ----
55 ----
51 Unfortunately, we currently have no strict HTML standards, but there are a few
56 Unfortunately, we currently have no strict HTML standards, but there are a few
52 guidelines we do follow. Templates must work in all modern browsers. HTML should
57 guidelines we do follow. Templates must work in all modern browsers. HTML should
53 be clean and easy to read, and additionally should be free of inline CSS or
58 be clean and easy to read, and additionally should be free of inline CSS or
54 JavaScript. It is recommended to use data attributes for JS actions where
59 JavaScript. It is recommended to use data attributes for JS actions where
55 possible in order to separate it from styling and prevent unintentional changes.
60 possible in order to separate it from styling and prevent unintentional changes.
56
61
57
62
58 LESS/CSS
63 LESS/CSS
59 --------
64 --------
60 We use LESS for our CSS; see :doc:`frontend` for structure and formatting
65 We use LESS for our CSS; see :doc:`frontend` for structure and formatting
61 guidelines.
66 guidelines.
62
67
63
68
64 Linters
69 Linters
65 -------
70 -------
66 Currently, we have a linter for pull requests which checks code against PEP8.
71 Currently, we have a linter for pull requests which checks code against PEP8.
67 We intend to add more in the future as we clarify standards.
72 We intend to add more in the future as we clarify standards.
68
73
69
74
70 --------------------------------------------------------------------------------
75 --------------------------------------------------------------------------------
71
76
72 Naming Conventions
77 Naming Conventions
73 ==================
78 ==================
74
79
75 These still need to be defined for naming everything from Python variables to
80 These still need to be defined for naming everything from Python variables to
76 HTML classes to files and folders.
81 HTML classes to files and folders.
77
82
78
83
79 --------------------------------------------------------------------------------
84 --------------------------------------------------------------------------------
80
85
81 Testing
86 Testing
82 =======
87 =======
83
88
84 Testing is a very important aspect of our process, especially as we are our own
89 Testing is a very important aspect of our process, especially as we are our own
85 quality control team. While it is of course unrealistic to hit every potential
90 quality control team. While it is of course unrealistic to hit every potential
86 combination, our goal is to cover every line of Python code with a test.
91 combination, our goal is to cover every line of Python code with a test.
87
92
88 The following is a brief introduction to our test suite. Our tests are primarily
93 The following is a brief introduction to our test suite. Our tests are primarily
89 written using `py.test <http://pytest.org/>`_
94 written using `py.test <http://pytest.org/>`_
90
95
91
96
92 Acceptance Tests
97 Acceptance Tests
93 ----------------
98 ----------------
94 Also known as "ac tests", these test from the user and business perspective to
99 Also known as "ac tests", these test from the user and business perspective to
95 check if the requirements of a feature are met. Scenarios are created at a
100 check if the requirements of a feature are met. Scenarios are created at a
96 feature's inception and help to define its value.
101 feature's inception and help to define its value.
97
102
98 py.test is used for ac tests; they are located in a repo separate from the
103 py.test is used for ac tests; they are located in a repo separate from the
99 other tests which follow. Each feature has a .feature file which contains a
104 other tests which follow. Each feature has a .feature file which contains a
100 brief description and the scenarios to be tested.
105 brief description and the scenarios to be tested.
101
106
102
107
103 Functional Tests
108 Functional Tests
104 ----------------
109 ----------------
105 These test specific functionality in the application which checks through the
110 These test specific functionality in the application which checks through the
106 entire stack. Typically these are user actions or permissions which go through
111 entire stack. Typically these are user actions or permissions which go through
107 the web browser. They are located in rhodecode/tests.
112 the web browser. They are located in rhodecode/tests.
108
113
109
114
110 Unit Tests
115 Unit Tests
111 ----------
116 ----------
112 These test isolated, individual modules to ensure that they function correctly.
117 These test isolated, individual modules to ensure that they function correctly.
113 They are located in rhodecode/tests.
118 They are located in rhodecode/tests.
114
119
115
120
116 Integration Tests
121 Integration Tests
117 -----------------
122 -----------------
118 These are used for testing performance of larger systems than the unit tests.
123 These are used for testing performance of larger systems than the unit tests.
119 They are located in rhodecode/tests.
124 They are located in rhodecode/tests.
120
125
121
126
122 JavaScript Testing
127 JavaScript Testing
123 ------------------
128 ------------------
124 Currently, we have not defined how to test our JavaScript code.
129 Currently, we have not defined how to test our JavaScript code.
125
130
126
131
127 --------------------------------------------------------------------------------
132 --------------------------------------------------------------------------------
128
133
129 Pull Requests
134 Pull Requests
130 =============
135 =============
131
136
132 Pull requests should generally contain only one thing: a single feature, one bug
137 Pull requests should generally contain only one thing: a single feature, one bug
133 fix, etc.. The commit history should be concise and clean, and the pull request
138 fix, etc.. The commit history should be concise and clean, and the pull request
134 should contain the ticket number (also a good idea for the commits themselves)
139 should contain the ticket number (also a good idea for the commits themselves)
135 to provide context for the reviewer.
140 to provide context for the reviewer.
136
141
137 See also: :doc:`checklist-pull-request`
142 See also: :doc:`checklist-pull-request`
138
143
139
144
140 Reviewers
145 Reviewers
141 ---------
146 ---------
142 Each pull request must be approved by at least one member of the RhodeCode
147 Each pull request must be approved by at least one member of the RhodeCode
143 team. Assignments may be based on expertise or familiarity with a particular
148 team. Assignments may be based on expertise or familiarity with a particular
144 area of code, or simply availability. Switching up or adding extra community
149 area of code, or simply availability. Switching up or adding extra community
145 members for different pull requests helps to share knowledge as well as provide
150 members for different pull requests helps to share knowledge as well as provide
146 other perspectives.
151 other perspectives.
147
152
148
153
149 Responsibility
154 Responsibility
150 --------------
155 --------------
151 The community is responsible for maintaining features and this must be taken
156 The community is responsible for maintaining features and this must be taken
152 into consideration. External contributions must be held to the same standards
157 into consideration. External contributions must be held to the same standards
153 as internal contributions.
158 as internal contributions.
154
159
155
160
156 Feature Switch
161 Feature Switch
157 --------------
162 --------------
158 Experimental and work-in-progress features can be hidden behind one of two
163 Experimental and work-in-progress features can be hidden behind one of two
159 switches:
164 switches:
160
165
161 * A setting can be added to the Labs page in the Admin section which may allow
166 * A setting can be added to the Labs page in the Admin section which may allow
162 customers to access and toggle additional features.
167 customers to access and toggle additional features.
163 * For work-in-progress or other features where customer access is not desired,
168 * For work-in-progress or other features where customer access is not desired,
164 use a custom setting in the .ini file as a trigger.
169 use a custom setting in the .ini file as a trigger.
165
170
166
171
167 --------------------------------------------------------------------------------
172 --------------------------------------------------------------------------------
168
173
169 Tickets
174 Tickets
170 =======
175 =======
171
176
172 Redmine tickets are a crucial part of our development process. Any code added or
177 Redmine tickets are a crucial part of our development process. Any code added or
173 changed in our codebase should have a corresponding ticket to document it. With
178 changed in our codebase should have a corresponding ticket to document it. With
174 this in mind, it is important that tickets be as clear and concise as possible,
179 this in mind, it is important that tickets be as clear and concise as possible,
175 including what the expected outcome is.
180 including what the expected outcome is.
176
181
177 See also: :doc:`checklist-tickets`
182 See also: :doc:`checklist-tickets`
General Comments 0
You need to be logged in to leave comments. Login now