##// END OF EJS Templates
rhodecode-enterprise-ce
RSS
docs: more comprehensive contributor docs #4039
lisaq -
r303:ed619a55 default
parent child Browse files
Show More
Show file before | Show file after | Hide comments
@@ -0,0 +1,137 b''
1 .. _checklist-tickets:
2
3 =================
4 Ticket Checklists
5 =================
6
7
8 Ticket Description
9 ==================
10
11 In general these things really matter in the description:
12
13 - Reasoning / Rationale. Explain "WHY" it makes sense and is important.
14
15 - How to reproduce. Easy to follow steps, that’s important.
16
17 - Observation: The problem (short)
18
19 - Expectation: How it should be (short)
20
21 - Specs: It is fine to draft them as good as it works.
22
23 If anything is unclear, please ask for a review or help on this via the
24 Community Portal or Slack channel.
25
26
27 Checklists for Tickets
28 ======================
29
30 BUG
31 ---
32
33 Definition: An existing function that does not work as expected for the user.
34
35 - Problem description
36 - Steps needed to recreate (gherkin)
37 - Link to the screen in question and/or description of how to find it via
38 navigation
39 - Explanation of what the expected outcome is
40 - Any hints into the source of the problem
41 - Information about platform/browser/db/etc. where applicable
42 - Examples of other similar cases which have different behaviour
43
44 DESIGN
45 ------
46
47 Definition: Styling and user interface issues, including cosmetic improvements
48 or appearance and behaviour of frontend functionality.
49
50 - Screenshot/animation of existing page/behaviour
51 - Sketches or wireframes if available
52 - Link to the screen in question and/or description of how to find it via
53 navigation
54 - Problem description
55 - Explanation of what the expected outcome is
56 - Since this may be examined by a designer; it should be written in a way that a
57 non-developer can understand
58
59 EPIC
60 ----
61
62 Definition: A collection of tickets which together complete a larger overall
63 project.
64
65 - Benefit explanation
66 - Clear objective - when is this complete?
67 - Explanations of exceptions/corner cases
68 - Documentation subtask
69 - Comprehensive wireframes and/or design subtasks
70 - Links to subtasks
71
72 FEATURE
73 -------
74
75 Definition: A new function in the software which previously did not exist.
76
77 - Benefit explanation
78 - Clear objective
79 - Explanations of exceptions/corner cases
80 - Documentation subtask
81 - Comprehensive wireframes and/or design subtasks
82
83 SUPPORT
84 -------
85
86 Definition: An issue related to a customer report.
87
88 - Link to support ticket, if available
89 - Problem description
90 - Steps needed to recreate (gherkin)
91 - Link to the screen in question and/or description of how to find it via
92 navigation
93 - Explanation of what the expected outcome is
94 - Any hints into the source of the problem
95 - Information about platform/browser/db/etc. where applicable
96 - Examples of other similar cases which have different behaviour
97
98 TASK
99 ----
100
101 Definition: An improvement or step towards implementing a feature or fixing
102 a bug. Includes refactoring and other tech debt.
103
104 - Clear objective
105 - Benefit explanation
106 - Links to parent/related tickets
107
108
109 All details below.
110
111
112 External links:
113
114 - Avoid linking to external images; they disappear over time. Please attach any
115 relevant images to the ticket itself.
116
117 - External links in general: They also disappear over time, consider copying the
118 relevant bit of information into a comment or write a paragraph to sum up the
119 general idea.
120
121
122 Hints
123 =====
124
125 Change Description
126 ------------------
127
128 It can be tricky to figure out how to change the description of a ticket. There
129 is a very small pencil which has to be clicked once you see the edit form of a
130 ticket.
131
132
133 .. figure:: images/redmine-description.png
134 :alt: Example of pencil to change the ticket description
135
136 Shows an example of the pencil which lets you change the description.
137
Show file before | Show file after | Hide comments
@@ -0,0 +1,152 b''
1
2 ==================================================
3 Code style and structure guide for frontend work
4 ==================================================
5
6 About: Outline of frontend development practices.
7
8
9
10
11 Templates
12 =========
13
14 - Indent with 4 spaces in general.
15
16 - Embedded Python code follows the same conventions as in the backend.
17
18 A common problem are missed spaces around operators.
19
20
21
22
23 Grunt AND npm2nix
24 =================
25
26
27 ---something goes here ---
28
29
30
31
32 LESS CSS
33 ========
34
35
36 Style
37 -----
38
39 - Use 4 spaces instead of tabs.
40
41 - Avoid ``!important``, it is very often an indicator for a problem.
42
43
44
45
46 Structure
47 ---------
48
49 It is important that we maintain consistency in the LESS files so that things
50 scale properly. CSS is organized using LESS and then compiled into a css file
51 to be used in production. Find the class you need to change and change it
52 there. Do not add overriding styles at the end of the file. The LESS file will
53 be minified; use plenty of spacing and comments for readability.
54
55 These will be kept in auxillary LESS files to be imported (in this order) at the top:
56
57 - `fonts.less` (font-face declarations)
58 - `mixins` (place all LESS mixins here)
59 - `helpers` (basic classes for hiding mobile elements, centering, etc)
60 - `variables` (theme-specific colors, spacing, and fonts which might change later)
61
62
63 Sections of the primary LESS file are as follows. Add comments describing
64 layout and modules.
65
66 .. code-block:: css
67
68 //--- BASE ------------------//
69 Very basic, sitewide styles.
70
71 //--- LAYOUT ------------------//
72 Essential layout, ex. containers and wrappers.
73 Do not put type styles in here.
74
75 //--- MODULES ------------------//
76 Reusable sections, such as sidebars and menus.
77
78 //--- THEME ------------------//
79 Theme styles, typography, etc.
80
81
82
83 Formatting rules
84 ~~~~~~~~~~~~~~~~
85
86 - Each rule should be indented on a separate line (this is helpful for diff
87 checking).
88
89 - Use a space after each colon and a semicolon after each last rule.
90
91 - Put a blank line between each class.
92
93 - Nested classes should be listed after the parent class' rules, separated with a
94 blank line, and indented.
95
96 - Using the below as a guide, place each rule in order of its effect on content,
97 layout, sizing, and last listing minor style changes such as font color and
98 backgrounds. Not every possible rule is listed here; when adding new ones,
99 judge where it should go in the list based on that hierarchy.
100
101 .. code-block:: scss
102
103 .class {
104 content
105 list-style-type
106 position
107 float
108 top
109 right
110 bottom
111 left
112 height
113 max-height
114 min-height
115 width
116 max-width
117 min-width
118 margin
119 padding
120 indent
121 vertical-align
122 text-align
123 border
124 border-radius
125 font-size
126 line-height
127 font
128 font-style
129 font-variant
130 font-weight
131 color
132 text-shadow
133 background
134 background-color
135 box-shadow
136 background-url
137 background-position
138 background-repeat
139 background-cover
140 transitions
141 cursor
142 pointer-events
143
144 .nested-class {
145 position
146 background-color
147
148 &:hover {
149 color
150 }
151 }
152 }
Show file before | Show file after | Hide comments
@@ -0,0 +1,111 b''
1
2 =======================
3 Contributing Overview
4 =======================
5
6
7 RhodeCode Community Edition is an open source code management platform. We
8 encourage contributions to our project from the community. This is a basic
9 overview of the procedures for adding your contribution to RhodeCode.
10
11
12
13 Check the Issue Tracker
14 =======================
15
16 Make an account at https://issues.rhodecode.com/account/register and browse the
17 current tickets for bugs to fix and tasks to do. Have a bug or feature that you
18 can't find in the tracker? Create a new issue for it. When you select a ticket,
19 make sure to assign it to yourself and mark it "in progress" to avoid duplicated
20 work.
21
22
23
24 Sign Up at code.rhodecode.com
25 =============================
26
27 Make an account at https://code.rhodecode.com/ using an email or your existing
28 GitHub, Bitbucket, Google, or Twitter account. Fork the repo you'd like to
29 contribute to; we suggest adding your username to the fork name. Clone your fork
30 to your computer. We use Mercurial for source control management; see
31 https://www.mercurial-scm.org/guide to get started quickly.
32
33
34
35 Set Up A Local Instance
36 =======================
37
38 You will need to set up an instance of RhodeCode CE using VCSServer so that you
39 can see your work locally as you make changes. We recommend using Linux for this
40 but it can also be built on OSX.
41
42 See :doc:`dev-setup` for instructions.
43
44
45
46 Code!
47 =====
48
49 You can now make, see, and test your changes locally. We are always improving to
50 keep our code clean and the cost of maintaining it low. This applies in the same
51 way for contributions. We run automated checks on our pull requests, and expect
52 understandable code. We also aim to provide test coverage for as much of our
53 codebase as possible; any new features should be augmented with tests.
54
55 Keep in mind that when we accept your contribution, we also take responsibility
56 for it; we must understand it to take on that responsibility.
57
58 See :doc:`standards` for more detailed information.
59
60
61
62 Commit And Push Your Changes
63 ============================
64
65 We highly recommend making a new bookmark for each feature, bug, or set of
66 commits you make so that you can point to it when creating your pull request.
67 Please also reference the ticket number in your commit messages. Don't forget to
68 push the bookmark!
69
70
71
72 Submit a Pull Request
73 =====================
74
75 Go to your fork, and choose "Create Pull Request" from the Options menu. Use
76 your bookmark as the source, and choose someone to review it. Don't worry about
77 chosing the right person; we'll assign the best contributor for the job. You'll
78 get feedback and an assigned status.
79
80 Be prepared to make updates to your pull request after some feedback.
81 Collaboration is part of the process and improvements can often be made.
82
83
84
85 Sign the Contributor License Agreement
86 ======================================
87
88 If your contribution is approved, you will need to virtually sign the license
89 agreement in order for it to be merged into the project's codebase. You can read
90 it on our website here: https://rhodecode.com/static/pdf/RhodeCode-CLA.pdf
91
92 To sign, go to code.rhodecode.com
93 and clone the CLA repository. Add your name and make a pull request to add it to
94 the contributor agreement; this serves as your virtual signature. Once your
95 signature is merged, add a link to the relevant commit to your contribution
96 pull request.
97
98
99
100 That's it! We'll take it from there. Thanks for your contribution!
101 ------------------------------------------------------------------
102
103 .. note:: If you have any questions or comments, feel free to contact us through
104 either the community portal(community.rhodecode.com), IRC
105 (irc.freenode.net), or Slack (rhodecode.com/join).
106
107
108
109
110
111
Show file before | Show file after | Hide comments
@@ -0,0 +1,177 b''
1
2 ======================
3 Contribution Standards
4 ======================
5
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
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.
10
11
12 --------------------------------------------------------------------------------
13
14 Code
15 ====
16
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
19 book `Clean Code <http://www.pearsonhighered.com/educator/product/Clean-Code-A-Handbook-of-Agile-Software-Craftsmanship/9780132350884.page>`_
20 by Robert Martin.
21
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
24 project in /docs-internal/glossary.rst
25
26
27 Refactoring
28 -----------
29 Make it better than you found it!
30
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
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
35 minimize issues.
36
37
38 Python
39 ------
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.
42
43
44 JavaScript
45 ----------
46 This currently remains undefined. Suggestions welcome!
47
48
49 HTML
50 ----
51 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
53 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
55 possible in order to separate it from styling and prevent unintentional changes.
56
57
58 LESS/CSS
59 --------
60 We use LESS for our CSS; see :doc:`frontend` for structure and formatting
61 guidelines.
62
63
64 Linters
65 -------
66 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.
68
69
70 --------------------------------------------------------------------------------
71
72 Naming Conventions
73 ==================
74
75 These still need to be defined for naming everything from Python variables to
76 HTML classes to files and folders.
77
78
79 --------------------------------------------------------------------------------
80
81 Testing
82 =======
83
84 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
86 combination, our goal is to cover every line of Python code with a test.
87
88 The following is a brief introduction to our test suite. Our tests are primarily
89 written using `py.test <http://pytest.org/>`_
90
91
92 Acceptance Tests
93 ----------------
94 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
96 feature's inception and help to define its value.
97
98 py.test is used for ac tests; they are located in a folder separate from the
99 other tests which follow. Each feature has a .feature file which contains a
100 brief description and the scenarios to be tested.
101
102
103 Functional Tests
104 ----------------
105 These test specific functionality in the application which checks through the
106 entire stack. Typically these are user actions or permissions which go through
107 the web browser. They are located in rhodecode/tests.
108
109
110 Unit Tests
111 ----------
112 These test isolated, individual modules to ensure that they function correctly.
113 They are located in rhodecode/tests.
114
115
116 Integration Tests
117 -----------------
118 These are used for testing performance of larger systems than the unit tests.
119 They are located in rhodecode/tests.
120
121
122 JavaScript Testing
123 ------------------
124 Currently, we have not defined how to test our JavaScript code.
125
126
127 --------------------------------------------------------------------------------
128
129 Pull Requests
130 =============
131
132 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
134 should contain the ticket number (also a good idea for the commits themselves)
135 to provide context for the reviewer.
136
137 See also: :doc:`checklist-pull-request`
138
139
140 Reviewers
141 ---------
142 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
144 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
146 other perspectives.
147
148
149 Responsibility
150 --------------
151 The community is responsible for maintaining features and this must be taken
152 into consideration. External contributions must be held to the same standards
153 as internal contributions.
154
155
156 Feature Switch
157 --------------
158 Experimental and work-in-progress features can be hidden behind one of two
159 switches:
160
161 * A setting can be added to the Labs page in the Admin section which may allow
162 customers to access and toggle additional features.
163 * 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.
165
166
167 --------------------------------------------------------------------------------
168
169 Tickets
170 =======
171
172 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
174 this in mind, it is important that tickets be as clear and concise as possible,
175 including what the expected outcome is.
176
177 See also: :doc:`checklist-tickets`
Show file before | Show file after | Hide comments
@@ -1,19 +1,20 b''
1 1 .. _contributing:
2 2
3 3 Contributing to RhodeCode
4 4 =========================
5 5
6 6
7 7
8 8 Welcome to the contribution guides and development docs of RhodeCode.
9 9
10 10
11 11
12 12 .. toctree::
13 13 :maxdepth: 1
14 14
15 overview
15 16 testing/index
16 17 dev-setup
17 18 db-schema
18 19 dev-settings
19 20 api
Show file before | Show file after | Hide comments
@@ -1,143 +1,144 b''
1 .. _dev-setup:
1 2
2 3 ===================
3 4 Development setup
4 5 ===================
5 6
6 7
7 8 RhodeCode Enterprise runs inside a Nix managed environment. This ensures build
8 9 environment dependencies are correctly declared and installed during setup.
9 10 It also enables atomic upgrades, rollbacks, and multiple instances of RhodeCode
10 11 Enterprise running with isolation.
11 12
12 13 To set up RhodeCode Enterprise inside the Nix environment, use the following steps:
13 14
14 15
15 16
16 17 Setup Nix Package Manager
17 18 -------------------------
18 19
19 20 To install the Nix Package Manager, please run::
20 21
21 22 $ curl https://nixos.org/nix/install | sh
22 23
23 24 or go to https://nixos.org/nix/ and follow the installation instructions.
24 25 Once this is correctly set up on your system, you should be able to use the
25 26 following commands:
26 27
27 28 * `nix-env`
28 29
29 30 * `nix-shell`
30 31
31 32
32 33 .. tip::
33 34
34 35 Update your channels frequently by running ``nix-channel --upgrade``.
35 36
36 37
37 38 Switch nix to the latest STABLE channel
38 39 ---------------------------------------
39 40
40 41 run::
41 42
42 43 nix-channel --add https://nixos.org/channels/nixos-16.03 nixpkgs
43 44
44 45 Followed by::
45 46
46 47 nix-channel --update
47 48
48 49
49 50 Clone the required repositories
50 51 -------------------------------
51 52
52 53 After Nix is set up, clone the RhodeCode Enterprise Community Edition and
53 54 RhodeCode VCSServer repositories into the same directory.
54 55 To do this, use the following example::
55 56
56 57 mkdir rhodecode-develop && cd rhodecode-develop
57 58 hg clone https://code.rhodecode.com/rhodecode-enterprise-ce
58 59 hg clone https://code.rhodecode.com/rhodecode-vcsserver
59 60
60 61 .. note::
61 62
62 63 If you cannot clone the repository, please request read permissions
63 64 via support@rhodecode.com
64 65
65 66
66 67
67 68 Enter the Development Shell
68 69 ---------------------------
69 70
70 71 The final step is to start the development shell. To do this, run the
71 72 following command from inside the cloned repository::
72 73
73 74 cd ~/rhodecode-enterprise-ce
74 75 nix-shell
75 76
76 77 .. note::
77 78
78 79 On the first run, this will take a while to download and optionally compile
79 80 a few things. The following runs will be faster. The development shell works
80 81 fine on MacOS and Linux platforms.
81 82
82 83
83 84
84 85 Creating a Development Configuration
85 86 ------------------------------------
86 87
87 88 To create a development environment for RhodeCode Enterprise,
88 89 use the following steps:
89 90
90 91 1. Create a copy of `~/rhodecode-enterprise-ce/configs/development.ini`
91 92 2. Adjust the configuration settings to your needs
92 93
93 94 .. note::
94 95
95 96 It is recommended to use the name `dev.ini`.
96 97
97 98
98 99 Setup the Development Database
99 100 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
100 101
101 102 To create a development database, use the following example. This is a one
102 103 time operation::
103 104
104 105 paster setup-rhodecode dev.ini \
105 106 --user=admin --password=secret \
106 107 --email=admin@example.com \
107 108 --repos=~/my_dev_repos
108 109
109 110
110 111 Start the Development Server
111 112 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
112 113
113 114 When starting the development server, you should start the vcsserver as a
114 115 separate process. To do this, use one of the following examples:
115 116
116 117 1. Set the `start.vcs_server` flag in the ``dev.ini`` file to true. For example:
117 118
118 119 .. code-block:: python
119 120
120 121 ### VCS CONFIG ###
121 122 ##################
122 123 vcs.start_server = true
123 124 vcs.server = localhost:9900
124 125 vcs.server.log_level = debug
125 126
126 127 Then start the server using the following command: ``rcserver dev.ini``
127 128
128 129 2. Start the development server using the following example::
129 130
130 131 rcserver --with-vcsserver dev.ini
131 132
132 133 3. Start the development server in a different terminal using the following
133 134 example::
134 135
135 136 vcsserver
136 137
137 138
138 139 Run the Environment Tests
139 140 ^^^^^^^^^^^^^^^^^^^^^^^^^
140 141
141 142 Please make sure that the tests are passing to verify that your environment is
142 143 set up correctly. RhodeCode uses py.test to run tests.
143 144 Please simply run ``make test`` to run the basic test suite.
General Comments 0
You need to be logged in to leave comments. Login now