gitlab-monitor 4.0.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (46) hide show
  1. checksums.yaml +7 -0
  2. data/.gitignore +2 -0
  3. data/.gitlab-ci.yml +18 -0
  4. data/.rubocop.yml +34 -0
  5. data/CONTRIBUTING.md +651 -0
  6. data/Gemfile +8 -0
  7. data/Gemfile.lock +75 -0
  8. data/LICENSE +25 -0
  9. data/README.md +110 -0
  10. data/bin/gitlab-mon +17 -0
  11. data/config/gitlab-monitor.yml.example +112 -0
  12. data/gitlab-monitor.gemspec +33 -0
  13. data/lib/gitlab_monitor.rb +18 -0
  14. data/lib/gitlab_monitor/cli.rb +341 -0
  15. data/lib/gitlab_monitor/database.rb +13 -0
  16. data/lib/gitlab_monitor/database/base.rb +44 -0
  17. data/lib/gitlab_monitor/database/bloat.rb +74 -0
  18. data/lib/gitlab_monitor/database/bloat_btree.sql +84 -0
  19. data/lib/gitlab_monitor/database/bloat_table.sql +63 -0
  20. data/lib/gitlab_monitor/database/ci_builds.rb +527 -0
  21. data/lib/gitlab_monitor/database/remote_mirrors.rb +74 -0
  22. data/lib/gitlab_monitor/database/row_count.rb +164 -0
  23. data/lib/gitlab_monitor/database/tuple_stats.rb +53 -0
  24. data/lib/gitlab_monitor/git.rb +144 -0
  25. data/lib/gitlab_monitor/memstats.rb +98 -0
  26. data/lib/gitlab_monitor/memstats/mapping.rb +91 -0
  27. data/lib/gitlab_monitor/prober.rb +40 -0
  28. data/lib/gitlab_monitor/process.rb +122 -0
  29. data/lib/gitlab_monitor/prometheus.rb +64 -0
  30. data/lib/gitlab_monitor/sidekiq.rb +149 -0
  31. data/lib/gitlab_monitor/sidekiq_queue_job_stats.lua +42 -0
  32. data/lib/gitlab_monitor/util.rb +83 -0
  33. data/lib/gitlab_monitor/version.rb +5 -0
  34. data/lib/gitlab_monitor/web_exporter.rb +77 -0
  35. data/spec/cli_spec.rb +31 -0
  36. data/spec/database/bloat_spec.rb +99 -0
  37. data/spec/database/ci_builds_spec.rb +421 -0
  38. data/spec/database/row_count_spec.rb +37 -0
  39. data/spec/fixtures/smaps/sample.txt +10108 -0
  40. data/spec/git_process_proper_spec.rb +27 -0
  41. data/spec/git_spec.rb +52 -0
  42. data/spec/memstats_spec.rb +28 -0
  43. data/spec/prometheus_metrics_spec.rb +17 -0
  44. data/spec/spec_helper.rb +63 -0
  45. data/spec/util_spec.rb +15 -0
  46. metadata +225 -0
@@ -0,0 +1,7 @@
1
+ ---
2
+ SHA256:
3
+ metadata.gz: 4487bba2fd7824febdcd6237160647242b614fa00ff7a110ecd17d3837909795
4
+ data.tar.gz: 570641ed653cb06da85138b998295f8baa74cdc6eaa59f64692971437734c7a4
5
+ SHA512:
6
+ metadata.gz: 1685675bf9aaa8815d4f6da07e350768bd8b6a0355949bc1bf18971d7e8aa1dfad9461503d2e3b07f4d786f15447a873299336f48ba3dbea105f85ad83f0bdd6
7
+ data.tar.gz: f341d7bfdd2e1eb8cc6b680871da8b27495abecf87757f4c110b54d247f3421dbeaae502865e2d6a79d17d4bb72d82e5ea6ee45b2325274a98325fb2121cd9b4
@@ -0,0 +1,2 @@
1
+ .bundle
2
+ config/gitlab-monitor*.yml
@@ -0,0 +1,18 @@
1
+ image: "ruby:2.3"
2
+
3
+ before_script:
4
+ - git config --global user.email "bot@gitlab.com"
5
+ - git config --global user.name "Bot User"
6
+ - bundle install -j $(nproc) --path vendor
7
+
8
+ cache:
9
+ paths:
10
+ - vendor
11
+
12
+ rspec:
13
+ script:
14
+ - bundle exec rspec spec -f d -c
15
+
16
+ rubocop:
17
+ script:
18
+ - bundle exec rubocop
@@ -0,0 +1,34 @@
1
+ AllCops:
2
+ TargetRubyVersion: 2.3
3
+ DisplayCopNames: true
4
+
5
+ # Just use double quotes please
6
+ Style/StringLiterals:
7
+ EnforcedStyle: double_quotes
8
+
9
+ # Jim Weirich block style
10
+ Style/BlockDelimiters:
11
+ EnforcedStyle: semantic
12
+
13
+ Style/SignalException:
14
+ EnforcedStyle: semantic
15
+
16
+ Style/RaiseArgs:
17
+ EnforcedStyle: compact
18
+
19
+ # Lets not freeze all the strings by default
20
+ Style/FrozenStringLiteralComment:
21
+ Enabled: false
22
+
23
+ Metrics/MethodLength:
24
+ Max: 15
25
+
26
+ Metrics/AbcSize:
27
+ Enabled: false
28
+
29
+ # Commonly used screens these days easily fit more than 80 characters.
30
+ Metrics/LineLength:
31
+ Max: 120
32
+
33
+ Metrics/ClassLength:
34
+ Max: 150
@@ -0,0 +1,651 @@
1
+ ## Developer Certificate of Origin + License
2
+
3
+ By contributing to GitLab B.V., You accept and agree to the following terms and
4
+ conditions for Your present and future Contributions submitted to GitLab B.V.
5
+ Except for the license granted herein to GitLab B.V. and recipients of software
6
+ distributed by GitLab B.V., You reserve all right, title, and interest in and to
7
+ Your Contributions. All Contributions are subject to the following DCO + License
8
+ terms.
9
+
10
+ [DCO + License](https://gitlab.com/gitlab-org/dco/blob/master/README.md)
11
+
12
+ _This notice should stay as the first item in the CONTRIBUTING.md file._
13
+
14
+ ---
15
+
16
+ <!-- START doctoc generated TOC please keep comment here to allow auto update -->
17
+ <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
18
+ **Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
19
+
20
+ - [Contribute to GitLab](#contribute-to-gitlab)
21
+ - [Security vulnerability disclosure](#security-vulnerability-disclosure)
22
+ - [Closing policy for issues and merge requests](#closing-policy-for-issues-and-merge-requests)
23
+ - [Helping others](#helping-others)
24
+ - [I want to contribute!](#i-want-to-contribute)
25
+ - [Workflow labels](#workflow-labels)
26
+ - [Type labels (~"feature proposal", ~bug, ~customer, etc.)](#type-labels-feature-proposal-bug-customer-etc)
27
+ - [Subject labels (~wiki, ~"container registry", ~ldap, ~api, etc.)](#subject-labels-wiki-container-registry-ldap-api-etc)
28
+ - [Team labels (~CI, ~Discussion, ~Edge, ~Platform, etc.)](#team-labels-ci-discussion-edge-platform-etc)
29
+ - [Priority labels (~Deliverable and ~Stretch)](#priority-labels-deliverable-and-stretch)
30
+ - [Label for community contributors (~"Accepting Merge Requests")](#label-for-community-contributors-accepting-merge-requests)
31
+ - [Implement design & UI elements](#implement-design--ui-elements)
32
+ - [Issue tracker](#issue-tracker)
33
+ - [Issue triaging](#issue-triaging)
34
+ - [Feature proposals](#feature-proposals)
35
+ - [Issue tracker guidelines](#issue-tracker-guidelines)
36
+ - [Issue weight](#issue-weight)
37
+ - [Regression issues](#regression-issues)
38
+ - [Technical debt](#technical-debt)
39
+ - [Stewardship](#stewardship)
40
+ - [Merge requests](#merge-requests)
41
+ - [Merge request guidelines](#merge-request-guidelines)
42
+ - [Contribution acceptance criteria](#contribution-acceptance-criteria)
43
+ - [Definition of done](#definition-of-done)
44
+ - [Style guides](#style-guides)
45
+ - [Code of conduct](#code-of-conduct)
46
+
47
+ <!-- END doctoc generated TOC please keep comment here to allow auto update -->
48
+
49
+ ---
50
+
51
+ ## Contribute to GitLab
52
+
53
+ Thank you for your interest in contributing to GitLab. This guide details how
54
+ to contribute to GitLab in a way that is efficient for everyone.
55
+
56
+ GitLab comes into two flavors, GitLab Community Edition (CE) our free and open
57
+ source edition, and GitLab Enterprise Edition (EE) which is our commercial
58
+ edition. Throughout this guide you will see references to CE and EE for
59
+ abbreviation.
60
+
61
+ If you have read this guide and want to know how the GitLab [core team]
62
+ operates please see [the GitLab contributing process](PROCESS.md).
63
+
64
+ - [GitLab Inc engineers should refer to the engineering workflow document](https://about.gitlab.com/handbook/engineering/workflow/)
65
+
66
+ ## Security vulnerability disclosure
67
+
68
+ Please report suspected security vulnerabilities in private to
69
+ `support@gitlab.com`, also see the
70
+ [disclosure section on the GitLab.com website](https://about.gitlab.com/disclosure/).
71
+ Please do **NOT** create publicly viewable issues for suspected security
72
+ vulnerabilities.
73
+
74
+ ## Closing policy for issues and merge requests
75
+
76
+ GitLab is a popular open source project and the capacity to deal with issues
77
+ and merge requests is limited. Out of respect for our volunteers, issues and
78
+ merge requests not in line with the guidelines listed in this document may be
79
+ closed without notice.
80
+
81
+ Please treat our volunteers with courtesy and respect, it will go a long way
82
+ towards getting your issue resolved.
83
+
84
+ Issues and merge requests should be in English and contain appropriate language
85
+ for audiences of all ages.
86
+
87
+ If a contributor is no longer actively working on a submitted merge request
88
+ we can decide that the merge request will be finished by one of our
89
+ [Merge request coaches][team] or close the merge request. We make this decision
90
+ based on how important the change is for our product vision. If a Merge request
91
+ coach is going to finish the merge request we assign the
92
+ ~"coach will finish" label.
93
+
94
+ ## Helping others
95
+
96
+ Please help other GitLab users when you can. The channels people will reach out
97
+ on can be found on the [getting help page][getting-help].
98
+
99
+ Sign up for the mailing list, answer GitLab questions on StackOverflow or
100
+ respond in the IRC channel. You can also sign up on [CodeTriage][codetriage] to help with
101
+ the remaining issues on the GitHub issue tracker.
102
+
103
+ ## I want to contribute!
104
+
105
+ If you want to contribute to GitLab, but are not sure where to start,
106
+ look for [issues with the label `Accepting Merge Requests` and weight < 5][accepting-mrs-weight].
107
+ These issues will be of reasonable size and challenge, for anyone to start
108
+ contributing to GitLab.
109
+
110
+ ## Workflow labels
111
+
112
+ To allow for asynchronous issue handling, we use [milestones][milestones-page]
113
+ and [labels][labels-page]. Leads and product managers handle most of the
114
+ scheduling into milestones. Labelling is a task for everyone.
115
+
116
+ Most issues will have labels for at least one of the following:
117
+
118
+ - Type: ~"feature proposal", ~bug, ~customer, etc.
119
+ - Subject: ~wiki, ~"container registry", ~ldap, ~api, etc.
120
+ - Team: ~CI, ~Discussion, ~Edge, ~Frontend, ~Platform, etc.
121
+ - Priority: ~Deliverable, ~Stretch
122
+
123
+ All labels, their meaning and priority are defined on the
124
+ [labels page][labels-page].
125
+
126
+ If you come across an issue that has none of these, and you're allowed to set
127
+ labels, you can _always_ add the team and type, and often also the subject.
128
+
129
+ [milestones-page]: https://gitlab.com/gitlab-org/gitlab-ce/milestones
130
+ [labels-page]: https://gitlab.com/gitlab-org/gitlab-ce/labels
131
+
132
+ ### Type labels (~"feature proposal", ~bug, ~customer, etc.)
133
+
134
+ Type labels are very important. They define what kind of issue this is. Every
135
+ issue should have one or more.
136
+
137
+ Examples of type labels are ~"feature proposal", ~bug, ~customer, ~security,
138
+ and ~"direction".
139
+
140
+ A number of type labels have a priority assigned to them, which automatically
141
+ makes them float to the top, depending on their importance.
142
+
143
+ Type labels are always lowercase, and can have any color, besides blue (which is
144
+ already reserved for subject labels).
145
+
146
+ The descriptions on the [labels page][labels-page] explain what falls under each type label.
147
+
148
+ ### Subject labels (~wiki, ~"container registry", ~ldap, ~api, etc.)
149
+
150
+ Subject labels are labels that define what area or feature of GitLab this issue
151
+ hits. They are not always necessary, but very convenient.
152
+
153
+ If you are an expert in a particular area, it makes it easier to find issues to
154
+ work on. You can also subscribe to those labels to receive an email each time an
155
+ issue is labelled with a subject label corresponding to your expertise.
156
+
157
+ Examples of subject labels are ~wiki, ~"container registry", ~ldap, ~api,
158
+ ~issues, ~"merge requests", ~labels, and ~"container registry".
159
+
160
+ Subject labels are always all-lowercase.
161
+
162
+ ### Team labels (~CI, ~Discussion, ~Edge, ~Platform, etc.)
163
+
164
+ Team labels specify what team is responsible for this issue.
165
+ Assigning a team label makes sure issues get the attention of the appropriate
166
+ people.
167
+
168
+ The current team labels are ~Build, ~CI, ~Discussion, ~Documentation, ~Edge,
169
+ ~Gitaly, ~Platform, ~Prometheus, ~Release, and ~"UX".
170
+
171
+ The descriptions on the [labels page][labels-page] explain what falls under the
172
+ responsibility of each team.
173
+
174
+ Within those team labels, we also have the ~backend and ~frontend labels to
175
+ indicate if an issue needs backend work, frontend work, or both.
176
+
177
+ Team labels are always capitalized so that they show up as the first label for
178
+ any issue.
179
+
180
+ ### Priority labels (~Deliverable and ~Stretch)
181
+
182
+ Priority labels help us clearly communicate expectations of the work for the
183
+ release. There are two levels of priority labels:
184
+
185
+ - ~Deliverable: Issues that are expected to be delivered in the current
186
+ milestone.
187
+ - ~Stretch: Issues that are a stretch goal for delivering in the current
188
+ milestone. If these issues are not done in the current release, they will
189
+ strongly be considered for the next release.
190
+
191
+ ### Label for community contributors (~"Accepting Merge Requests")
192
+
193
+ Issues that are beneficial to our users, 'nice to haves', that we currently do
194
+ not have the capacity for or want to give the priority to, are labeled as
195
+ ~"Accepting Merge Requests", so the community can make a contribution.
196
+
197
+ Community contributors can submit merge requests for any issue they want, but
198
+ the ~"Accepting Merge Requests" label has a special meaning. It points to
199
+ changes that:
200
+
201
+ 1. We already agreed on,
202
+ 1. Are well-defined,
203
+ 1. Are likely to get accepted by a maintainer.
204
+
205
+ We want to avoid a situation when a contributor picks an
206
+ ~"Accepting Merge Requests" issue and then their merge request gets closed,
207
+ because we realize that it does not fit our vision, or we want to solve it in a
208
+ different way.
209
+
210
+ We add the ~"Accepting Merge Requests" label to:
211
+
212
+ - Low priority ~bug issues (i.e. we do not add it to the bugs that we want to
213
+ solve in the ~"Next Patch Release")
214
+ - Small ~"feature proposal" that do not need ~UX / ~"Product work", or for which
215
+ the ~UX / ~"Product work" is already done
216
+ - Small ~"technical debt" issues
217
+
218
+ After adding the ~"Accepting Merge Requests" label, we try to estimate the
219
+ [weight](#issue-weight) of the issue. We use issue weight to let contributors
220
+ know how difficult the issue is. Additionally:
221
+
222
+ - We advertise [~"Accepting Merge Requests" issues with weight < 5][up-for-grabs]
223
+ as suitable for people that have never contributed to GitLab before on the
224
+ [Up For Grabs campaign](http://up-for-grabs.net)
225
+ - We encourage people that have never contributed to any open source project to
226
+ look for [~"Accepting Merge Requests" issues with a weight of 1][firt-timers]
227
+
228
+ [up-for-grabs]: https://gitlab.com/gitlab-org/gitlab-ce/issues?label_name=Accepting+Merge+Requests&scope=all&sort=weight_asc&state=opened
229
+ [firt-timers]: https://gitlab.com/gitlab-org/gitlab-ce/issues?label_name%5B%5D=Accepting+Merge+Requests&scope=all&sort=upvotes_desc&state=opened&weight=1
230
+
231
+ ## Implement design & UI elements
232
+
233
+ Please see the [UX Guide for GitLab].
234
+
235
+ ## Issue tracker
236
+
237
+ To get support for your particular problem please use the
238
+ [getting help channels](https://about.gitlab.com/getting-help/).
239
+
240
+ The [GitLab CE issue tracker on GitLab.com][ce-tracker] is for bugs concerning
241
+ the latest GitLab release and [feature proposals](#feature-proposals).
242
+
243
+ When submitting an issue please conform to the issue submission guidelines
244
+ listed below. Not all issues will be addressed and your issue is more likely to
245
+ be addressed if you submit a merge request which partially or fully solves
246
+ the issue.
247
+
248
+ If you're unsure where to post, post to the [mailing list][google-group] or
249
+ [Stack Overflow][stackoverflow] first. There are a lot of helpful GitLab users
250
+ there who may be able to help you quickly. If your particular issue turns out
251
+ to be a bug, it will find its way from there.
252
+
253
+ If it happens that you know the solution to an existing bug, please first
254
+ open the issue in order to keep track of it and then open the relevant merge
255
+ request that potentially fixes it.
256
+
257
+ ### Issue triaging
258
+
259
+ Our issue triage policies are [described in our handbook]. You are very welcome
260
+ to help the GitLab team triage issues. We also organize [issue bash events] once
261
+ every quarter.
262
+
263
+ The most important thing is making sure valid issues receive feedback from the
264
+ development team. Therefore the priority is mentioning developers that can help
265
+ on those issues. Please select someone with relevant experience from the
266
+ [GitLab team][team]. If there is nobody mentioned with that expertise look in
267
+ the commit history for the affected files to find someone.
268
+
269
+ [described in our handbook]: https://about.gitlab.com/handbook/engineering/issues/issue-triage-policies/
270
+ [issue bash events]: https://gitlab.com/gitlab-org/gitlab-ce/issues/17815
271
+
272
+ ### Feature proposals
273
+
274
+ To create a feature proposal for CE, open an issue on the
275
+ [issue tracker of CE][ce-tracker].
276
+
277
+ For feature proposals for EE, open an issue on the
278
+ [issue tracker of EE][ee-tracker].
279
+
280
+ In order to help track the feature proposals, we have created a
281
+ [`feature proposal`][fpl] label. For the time being, users that are not members
282
+ of the project cannot add labels. You can instead ask one of the [core team]
283
+ members to add the label `feature proposal` to the issue or add the following
284
+ code snippet right after your description in a new line: `~"feature proposal"`.
285
+
286
+ Please keep feature proposals as small and simple as possible, complex ones
287
+ might be edited to make them small and simple.
288
+
289
+ Please submit Feature Proposals using the ['Feature Proposal' issue template](.gitlab/issue_templates/Feature Proposal.md) provided on the issue tracker.
290
+
291
+ For changes in the interface, it can be helpful to create a mockup first.
292
+ If you want to create something yourself, consider opening an issue first to
293
+ discuss whether it is interesting to include this in GitLab.
294
+
295
+ ### Issue tracker guidelines
296
+
297
+ **[Search the issue tracker][ce-tracker]** for similar entries before
298
+ submitting your own, there's a good chance somebody else had the same issue or
299
+ feature proposal. Show your support with an award emoji and/or join the
300
+ discussion.
301
+
302
+ Please submit bugs using the ['Bug' issue template](.gitlab/issue_templates/Bug.md) provided on the issue tracker.
303
+ The text in the parenthesis is there to help you with what to include. Omit it
304
+ when submitting the actual issue. You can copy-paste it and then edit as you
305
+ see fit.
306
+
307
+ ### Issue weight
308
+
309
+ Issue weight allows us to get an idea of the amount of work required to solve
310
+ one or multiple issues. This makes it possible to schedule work more accurately.
311
+
312
+ You are encouraged to set the weight of any issue. Following the guidelines
313
+ below will make it easy to manage this, without unnecessary overhead.
314
+
315
+ 1. Set weight for any issue at the earliest possible convenience
316
+ 1. If you don't agree with a set weight, discuss with other developers until
317
+ consensus is reached about the weight
318
+ 1. Issue weights are an abstract measurement of complexity of the issue. Do not
319
+ relate issue weight directly to time. This is called [anchoring](https://en.wikipedia.org/wiki/Anchoring)
320
+ and something you want to avoid.
321
+ 1. Something that has a weight of 1 (or no weight) is really small and simple.
322
+ Something that is 9 is rewriting a large fundamental part of GitLab,
323
+ which might lead to many hard problems to solve. Changing some text in GitLab
324
+ is probably 1, adding a new Git Hook maybe 4 or 5, big features 7-9.
325
+ 1. If something is very large, it should probably be split up in multiple
326
+ issues or chunks. You can simply not set the weight of a parent issue and set
327
+ weights to children issues.
328
+
329
+ ### Regression issues
330
+
331
+ Every monthly release has a corresponding issue on the CE issue tracker to keep
332
+ track of functionality broken by that release and any fixes that need to be
333
+ included in a patch release (see [8.3 Regressions] as an example).
334
+
335
+ As outlined in the issue description, the intended workflow is to post one note
336
+ with a reference to an issue describing the regression, and then to update that
337
+ note with a reference to the merge request that fixes it as it becomes available.
338
+
339
+ If you're a contributor who doesn't have the required permissions to update
340
+ other users' notes, please post a new note with a reference to both the issue
341
+ and the merge request.
342
+
343
+ The release manager will [update the notes] in the regression issue as fixes are
344
+ addressed.
345
+
346
+ [8.3 Regressions]: https://gitlab.com/gitlab-org/gitlab-ce/issues/4127
347
+ [update the notes]: https://gitlab.com/gitlab-org/release-tools/blob/master/doc/pro-tips.md#update-the-regression-issue
348
+
349
+ ### Technical debt
350
+
351
+ In order to track things that can be improved in GitLab's codebase, we created
352
+ the ~"technical debt" label in [GitLab's issue tracker][ce-tracker].
353
+
354
+ This label should be added to issues that describe things that can be improved,
355
+ shortcuts that have been taken, code that needs refactoring, features that need
356
+ additional attention, and all other things that have been left behind due to
357
+ high velocity of development.
358
+
359
+ Everyone can create an issue, though you may need to ask for adding a specific
360
+ label, if you do not have permissions to do it by yourself. Additional labels
361
+ can be combined with the `technical debt` label, to make it easier to schedule
362
+ the improvements for a release.
363
+
364
+ Issues tagged with the `technical debt` label have the same priority like issues
365
+ that describe a new feature to be introduced in GitLab, and should be scheduled
366
+ for a release by the appropriate person.
367
+
368
+ Make sure to mention the merge request that the `technical debt` issue is
369
+ associated with in the description of the issue.
370
+
371
+ ### Stewardship
372
+
373
+ For issues related to the open source stewardship of GitLab,
374
+ there is the ~"stewardship" label.
375
+
376
+ This label is to be used for issues in which the stewardship of GitLab
377
+ is a topic of discussion. For instance if GitLab Inc. is planning to remove
378
+ features from GitLab CE to make exclusive in GitLab EE, related issues
379
+ would be labelled with ~"stewardship".
380
+
381
+ A recent example of this was the issue for
382
+ [bringing the time tracking API to GitLab CE][time-tracking-issue].
383
+
384
+ [time-tracking-issue]: https://gitlab.com/gitlab-org/gitlab-ce/issues/25517#note_20019084
385
+
386
+ ## Merge requests
387
+
388
+ We welcome merge requests with fixes and improvements to GitLab code, tests,
389
+ and/or documentation. The issues that are specifically suitable for
390
+ community contributions are listed with the label
391
+ [`Accepting Merge Requests` on our issue tracker for CE][accepting-mrs-ce]
392
+ and [EE][accepting-mrs-ee], but you are free to contribute to any other issue
393
+ you want.
394
+
395
+ Please note that if an issue is marked for the current milestone either before
396
+ or while you are working on it, a team member may take over the merge request
397
+ in order to ensure the work is finished before the release date.
398
+
399
+ If you want to add a new feature that is not labeled it is best to first create
400
+ a feedback issue (if there isn't one already) and leave a comment asking for it
401
+ to be marked as `Accepting Merge Requests`. Please include screenshots or
402
+ wireframes if the feature will also change the UI.
403
+
404
+ Merge requests should be opened at [GitLab.com][gitlab-mr-tracker].
405
+
406
+ If you are new to GitLab development (or web development in general), see the
407
+ [I want to contribute!](#i-want-to-contribute) section to get you started with
408
+ some potentially easy issues.
409
+
410
+ To start with GitLab development download the [GitLab Development Kit][gdk] and
411
+ see the [Development section](doc/development/README.md) for some guidelines.
412
+
413
+ ### Merge request guidelines
414
+
415
+ If you can, please submit a merge request with the fix or improvements
416
+ including tests. If you don't know how to fix the issue but can write a test
417
+ that exposes the issue we will accept that as well. In general bug fixes that
418
+ include a regression test are merged quickly while new features without proper
419
+ tests are least likely to receive timely feedback. The workflow to make a merge
420
+ request is as follows:
421
+
422
+ 1. Fork the project into your personal space on GitLab.com
423
+ 1. Create a feature branch, branch away from `master`
424
+ 1. Write [tests](https://gitlab.com/gitlab-org/gitlab-development-kit#running-the-tests) and code
425
+ 1. [Generate a changelog entry with `bin/changelog`][changelog]
426
+ 1. If you are writing documentation, make sure to follow the
427
+ [documentation styleguide][doc-styleguide]
428
+ 1. If you have multiple commits please combine them into a few logically
429
+ organized commits by [squashing them][git-squash]
430
+ 1. Push the commit(s) to your fork
431
+ 1. Submit a merge request (MR) to the `master` branch
432
+ 1. Your merge request needs at least 1 approval but feel free to require more.
433
+ For instance if you're touching backend and frontend code, it's a good idea
434
+ to require 2 approvals: 1 from a backend maintainer and 1 from a frontend
435
+ maintainer
436
+ 1. You don't have to select any approvers, but you can if you really want
437
+ specific people to approve your merge request
438
+ 1. The MR title should describe the change you want to make
439
+ 1. The MR description should give a motive for your change and the method you
440
+ used to achieve it.
441
+ 1. If you are contributing code, fill in the template already provided in the
442
+ "Description" field.
443
+ 1. If you are contributing documentation, choose `Documentation` from the
444
+ "Choose a template" menu and fill in the template.
445
+ 1. Mention the issue(s) your merge request solves, using the `Solves #XXX` or
446
+ `Closes #XXX` syntax to auto-close the issue(s) once the merge request will
447
+ be merged.
448
+ 1. If you're allowed to, set a relevant milestone and labels
449
+ 1. If the MR changes the UI it should include *Before* and *After* screenshots
450
+ 1. If the MR changes CSS classes please include the list of affected pages,
451
+ `grep css-class ./app -R`
452
+ 1. Be prepared to answer questions and incorporate feedback even if requests
453
+ for this arrive weeks or months after your MR submission
454
+ 1. If a discussion has been addressed, select the "Resolve discussion" button
455
+ beneath it to mark it resolved.
456
+ 1. If your MR touches code that executes shell commands, reads or opens files or
457
+ handles paths to files on disk, make sure it adheres to the
458
+ [shell command guidelines](doc/development/shell_commands.md)
459
+ 1. If your code creates new files on disk please read the
460
+ [shared files guidelines](doc/development/shared_files.md).
461
+ 1. When writing commit messages please follow
462
+ [these](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)
463
+ [guidelines](http://chris.beams.io/posts/git-commit/).
464
+ 1. If your merge request adds one or more migrations, make sure to execute all
465
+ migrations on a fresh database before the MR is reviewed. If the review leads
466
+ to large changes in the MR, do this again once the review is complete.
467
+ 1. For more complex migrations, write tests.
468
+ 1. Merge requests **must** adhere to the [merge request performance
469
+ guidelines](doc/development/merge_request_performance_guidelines.md).
470
+ 1. For tests that use Capybara or PhantomJS, see this [article on how
471
+ to write reliable asynchronous tests](https://robots.thoughtbot.com/write-reliable-asynchronous-integration-tests-with-capybara).
472
+
473
+ Please keep the change in a single MR **as small as possible**. If you want to
474
+ contribute a large feature think very hard what the minimum viable change is.
475
+ Can you split the functionality? Can you only submit the backend/API code? Can
476
+ you start with a very simple UI? Can you do part of the refactor? The increased
477
+ reviewability of small MRs that leads to higher code quality is more important
478
+ to us than having a minimal commit log. The smaller an MR is the more likely it
479
+ is it will be merged (quickly). After that you can send more MRs to enhance it.
480
+ The ['How to get faster PR reviews' document of Kubernetes](https://github.com/kubernetes/community/blob/master/contributors/devel/faster_reviews.md) also has some great points regarding this.
481
+
482
+ For examples of feedback on merge requests please look at already
483
+ [closed merge requests][closed-merge-requests]. If you would like quick feedback
484
+ on your merge request feel free to mention someone from the [core team] or one
485
+ of the [Merge request coaches][team].
486
+ Please ensure that your merge request meets the contribution acceptance criteria.
487
+
488
+ When having your code reviewed and when reviewing merge requests please take the
489
+ [code review guidelines](doc/development/code_review.md) into account.
490
+
491
+ ### Contribution acceptance criteria
492
+
493
+ 1. The change is as small as possible
494
+ 1. Include proper tests and make all tests pass (unless it contains a test
495
+ exposing a bug in existing code). Every new class should have corresponding
496
+ unit tests, even if the class is exercised at a higher level, such as a feature test.
497
+ 1. If you suspect a failing CI build is unrelated to your contribution, you may
498
+ try and restart the failing CI job or ask a developer to fix the
499
+ aforementioned failing test
500
+ 1. Your MR initially contains a single commit (please use `git rebase -i` to
501
+ squash commits)
502
+ 1. Your changes can merge without problems (if not please rebase if you're the
503
+ only one working on your feature branch, otherwise, merge `master`)
504
+ 1. Does not break any existing functionality
505
+ 1. Fixes one specific issue or implements one specific feature (do not combine
506
+ things, send separate merge requests if needed)
507
+ 1. Migrations should do only one thing (e.g., either create a table, move data
508
+ to a new table or remove an old table) to aid retrying on failure
509
+ 1. Keeps the GitLab code base clean and well structured
510
+ 1. Contains functionality we think other users will benefit from too
511
+ 1. Doesn't add configuration options or settings options since they complicate
512
+ making and testing future changes
513
+ 1. Changes do not adversely degrade performance.
514
+ - Avoid repeated polling of endpoints that require a significant amount of overhead
515
+ - Check for N+1 queries via the SQL log or [`QueryRecorder`](https://docs.gitlab.com/ce/development/merge_request_performance_guidelines.html)
516
+ - Avoid repeated access of filesystem
517
+ 1. If you need polling to support real-time features, please use
518
+ [polling with ETag caching][polling-etag].
519
+ 1. Changes after submitting the merge request should be in separate commits
520
+ (no squashing).
521
+ 1. It conforms to the [style guides](#style-guides) and the following:
522
+ - If your change touches a line that does not follow the style, modify the
523
+ entire line to follow it. This prevents linting tools from generating warnings.
524
+ - Don't touch neighbouring lines. As an exception, automatic mass
525
+ refactoring modifications may leave style non-compliant.
526
+ 1. If the merge request adds any new libraries (gems, JavaScript libraries,
527
+ etc.), they should conform to our [Licensing guidelines][license-finder-doc].
528
+ See the instructions in that document for help if your MR fails the
529
+ "license-finder" test with a "Dependencies that need approval" error.
530
+
531
+ ## Definition of done
532
+
533
+ If you contribute to GitLab please know that changes involve more than just
534
+ code. We have the following [definition of done][definition-of-done]. Please ensure you support
535
+ the feature you contribute through all of these steps.
536
+
537
+ 1. Description explaining the relevancy (see following item)
538
+ 1. Working and clean code that is commented where needed
539
+ 1. [Unit and system tests][testing] that pass on the CI server
540
+ 1. Performance/scalability implications have been considered, addressed, and tested
541
+ 1. [Documented][doc-styleguide] in the `/doc` directory
542
+ 1. [Changelog entry added][changelog], if necessary
543
+ 1. Reviewed and any concerns are addressed
544
+ 1. Merged by a project maintainer
545
+ 1. Added to the release blog article, if relevant
546
+ 1. Added to [the website](https://gitlab.com/gitlab-com/www-gitlab-com/), if relevant
547
+ 1. Community questions answered
548
+ 1. Answers to questions radiated (in docs/wiki/support etc.)
549
+
550
+ If you add a dependency in GitLab (such as an operating system package) please
551
+ consider updating the following and note the applicability of each in your
552
+ merge request:
553
+
554
+ 1. Note the addition in the release blog post (create one if it doesn't exist yet) https://gitlab.com/gitlab-com/www-gitlab-com/merge_requests/
555
+ 1. Upgrade guide, for example https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/update/7.5-to-7.6.md
556
+ 1. Upgrader https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/update/upgrader.md#2-run-gitlab-upgrade-tool
557
+ 1. Installation guide https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/install/installation.md#1-packages-dependencies
558
+ 1. GitLab Development Kit https://gitlab.com/gitlab-org/gitlab-development-kit
559
+ 1. Test suite https://gitlab.com/gitlab-org/gitlab-ce/blob/master/scripts/prepare_build.sh
560
+ 1. Omnibus package creator https://gitlab.com/gitlab-org/omnibus-gitlab
561
+
562
+ ## Style guides
563
+
564
+ 1. [Ruby](https://github.com/bbatsov/ruby-style-guide).
565
+ Important sections include [Source Code Layout][rss-source] and
566
+ [Naming][rss-naming]. Use:
567
+ - multi-line method chaining style **Option A**: dot `.` on the second line
568
+ - string literal quoting style **Option A**: single quoted by default
569
+ 1. [Rails](https://github.com/bbatsov/rails-style-guide)
570
+ 1. [Newlines styleguide][newlines-styleguide]
571
+ 1. [Testing][testing]
572
+ 1. [JavaScript styleguide][js-styleguide]
573
+ 1. [SCSS styleguide][scss-styleguide]
574
+ 1. [Shell commands](doc/development/shell_commands.md) created by GitLab
575
+ contributors to enhance security
576
+ 1. [Database Migrations](doc/development/migration_style_guide.md)
577
+ 1. [Markdown](http://www.cirosantilli.com/markdown-styleguide)
578
+ 1. [Documentation styleguide][doc-styleguide]
579
+ 1. Interface text should be written subjectively instead of objectively. It
580
+ should be the GitLab core team addressing a person. It should be written in
581
+ present time and never use past tense (has been/was). For example instead
582
+ of _prohibited this user from being saved due to the following errors:_ the
583
+ text should be _sorry, we could not create your account because:_
584
+
585
+ This is also the style used by linting tools such as
586
+ [RuboCop](https://github.com/bbatsov/rubocop),
587
+ [PullReview](https://www.pullreview.com/) and [Hound CI](https://houndci.com).
588
+
589
+ ## Code of conduct
590
+
591
+ As contributors and maintainers of this project, we pledge to respect all
592
+ people who contribute through reporting issues, posting feature requests,
593
+ updating documentation, submitting pull requests or patches, and other
594
+ activities.
595
+
596
+ We are committed to making participation in this project a harassment-free
597
+ experience for everyone, regardless of level of experience, gender, gender
598
+ identity and expression, sexual orientation, disability, personal appearance,
599
+ body size, race, ethnicity, age, or religion.
600
+
601
+ Examples of unacceptable behavior by participants include the use of sexual
602
+ language or imagery, derogatory comments or personal attacks, trolling, public
603
+ or private harassment, insults, or other unprofessional conduct.
604
+
605
+ Project maintainers have the right and responsibility to remove, edit, or
606
+ reject comments, commits, code, wiki edits, issues, and other contributions
607
+ that are not aligned to this Code of Conduct. Project maintainers who do not
608
+ follow the Code of Conduct may be removed from the project team.
609
+
610
+ This code of conduct applies both within project spaces and in public spaces
611
+ when an individual is representing the project or its community.
612
+
613
+ Instances of abusive, harassing, or otherwise unacceptable behavior can be
614
+ reported by emailing `contact@gitlab.com`.
615
+
616
+ This Code of Conduct is adapted from the [Contributor Covenant][contributor-covenant], version 1.1.0,
617
+ available at [http://contributor-covenant.org/version/1/1/0/](http://contributor-covenant.org/version/1/1/0/).
618
+
619
+ [core team]: https://about.gitlab.com/core-team/
620
+ [team]: https://about.gitlab.com/team/
621
+ [getting-help]: https://about.gitlab.com/getting-help/
622
+ [codetriage]: http://www.codetriage.com/gitlabhq/gitlabhq
623
+ [accepting-mrs-weight]: https://gitlab.com/gitlab-org/gitlab-ce/issues?assignee_id=0&label_name[]=Accepting%20Merge%20Requests&sort=weight_asc
624
+ [ce-tracker]: https://gitlab.com/gitlab-org/gitlab-ce/issues
625
+ [ee-tracker]: https://gitlab.com/gitlab-org/gitlab-ee/issues
626
+ [google-group]: https://groups.google.com/forum/#!forum/gitlabhq
627
+ [stackoverflow]: https://stackoverflow.com/questions/tagged/gitlab
628
+ [fpl]: https://gitlab.com/gitlab-org/gitlab-ce/issues?label_name=feature+proposal
629
+ [accepting-mrs-ce]: https://gitlab.com/gitlab-org/gitlab-ce/issues?label_name=Accepting+Merge+Requests
630
+ [accepting-mrs-ee]: https://gitlab.com/gitlab-org/gitlab-ee/issues?label_name=Accepting+Merge+Requests
631
+ [gitlab-mr-tracker]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests
632
+ [gdk]: https://gitlab.com/gitlab-org/gitlab-development-kit
633
+ [git-squash]: https://git-scm.com/book/en/Git-Tools-Rewriting-History#Squashing-Commits
634
+ [closed-merge-requests]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests?assignee_id=&label_name=&milestone_id=&scope=&sort=&state=closed
635
+ [definition-of-done]: http://guide.agilealliance.org/guide/definition-of-done.html
636
+ [contributor-covenant]: http://contributor-covenant.org
637
+ [rss-source]: https://github.com/bbatsov/ruby-style-guide/blob/master/README.md#source-code-layout
638
+ [rss-naming]: https://github.com/bbatsov/ruby-style-guide/blob/master/README.md#naming
639
+ [changelog]: doc/development/changelog.md "Generate a changelog entry"
640
+ [doc-styleguide]: doc/development/doc_styleguide.md "Documentation styleguide"
641
+ [js-styleguide]: doc/development/fe_guide/style_guide_js.md "JavaScript styleguide"
642
+ [scss-styleguide]: doc/development/fe_guide/style_guide_scss.md "SCSS styleguide"
643
+ [newlines-styleguide]: doc/development/newlines_styleguide.md "Newlines styleguide"
644
+ [UX Guide for GitLab]: http://docs.gitlab.com/ce/development/ux_guide/
645
+ [license-finder-doc]: doc/development/licensing.md
646
+ [GitLab Inc engineering workflow]: https://about.gitlab.com/handbook/engineering/workflow/#labelling-issues
647
+ [polling-etag]: https://docs.gitlab.com/ce/development/polling.html
648
+ [testing]: doc/development/testing.md
649
+
650
+ [^1]: Please note that specs other than JavaScript specs are considered backend
651
+ code.