diff options
Diffstat (limited to 'doc/development')
| -rw-r--r-- | doc/development/background_migrations.md | 12 | ||||
| -rw-r--r-- | doc/development/ee_features.md | 7 | ||||
| -rw-r--r-- | doc/development/fe_guide/components.md | 61 | ||||
| -rw-r--r-- | doc/development/fe_guide/dropdowns.md | 33 | ||||
| -rw-r--r-- | doc/development/fe_guide/img/gl-modal.png | bin | 0 -> 25893 bytes | |||
| -rw-r--r-- | doc/development/fe_guide/index.md | 9 | ||||
| -rw-r--r-- | doc/development/fe_guide/style_guide_js.md | 43 | ||||
| -rw-r--r-- | doc/development/fe_guide/style_guide_scss.md | 2 | ||||
| -rw-r--r-- | doc/development/feature_flags.md | 7 | ||||
| -rw-r--r-- | doc/development/i18n/externalization.md | 5 | ||||
| -rw-r--r-- | doc/development/i18n/index.md | 37 | ||||
| -rw-r--r-- | doc/development/i18n/proofreader.md | 48 | ||||
| -rw-r--r-- | doc/development/profiling.md | 11 | ||||
| -rw-r--r-- | doc/development/query_count_limits.md | 5 | ||||
| -rw-r--r-- | doc/development/sidekiq_style_guide.md | 3 | ||||
| -rw-r--r-- | doc/development/testing_guide/testing_levels.md | 4 |
16 files changed, 207 insertions, 80 deletions
diff --git a/doc/development/background_migrations.md b/doc/development/background_migrations.md index af2026c483e..fc1b202b5eb 100644 --- a/doc/development/background_migrations.md +++ b/doc/development/background_migrations.md @@ -94,6 +94,18 @@ jobs = [['BackgroundMigrationClassName', [1]], BackgroundMigrationWorker.bulk_perform_in(5.minutes, jobs) ``` +### Rescheduling background migrations + +If one of the background migrations contains a bug that is fixed in a patch +release, the background migration needs to be rescheduled so the migration would +be repeated on systems that already performed the initial migration. + +When you reschedule the background migration, make sure to turn the original +scheduling into a no-op by clearing up the `#up` and `#down` methods of the +migration performing the scheduling. Otherwise the background migration would be +scheduled multiple times on systems that are upgrading multiple patch releases at +once. + ## Cleaning Up >**Note:** diff --git a/doc/development/ee_features.md b/doc/development/ee_features.md index f8cee89e650..f6a14de96b2 100644 --- a/doc/development/ee_features.md +++ b/doc/development/ee_features.md @@ -28,9 +28,8 @@ we still need to merge changes from GitLab CE to EE. To help us get there, we should make sure that we no longer edit CE files in place in order to implement EE features. -Instead, all EE codes should be put inside the `ee/` top-level directory, and -tests should be put inside `spec/ee/`. We don't use `ee/spec` for now due to -technical limitation. The rest of codes should be as close as to the CE files. +Instead, all EE code should be put inside the `ee/` top-level directory. The +rest of the code should be as close to the CE files as possible. [single code base]: https://gitlab.com/gitlab-org/gitlab-ee/issues/2952#note_41016454 @@ -318,7 +317,7 @@ When you're testing EE-only features, avoid adding examples to the existing CE specs. Also do no change existing CE examples, since they should remain working as-is when EE is running without a license. -Instead place EE specs in the `spec/ee/spec` folder. +Instead place EE specs in the `ee/spec` folder. ## JavaScript code in `assets/javascripts/` diff --git a/doc/development/fe_guide/components.md b/doc/development/fe_guide/components.md new file mode 100644 index 00000000000..66a8abe42f7 --- /dev/null +++ b/doc/development/fe_guide/components.md @@ -0,0 +1,61 @@ +# Components + +## Contents +* [Dropdowns](#dropdowns) +* [Modals](#modals) + +## Dropdowns + +See also the [corresponding UX guide](../ux_guide/components.md#dropdowns). + +### How to style a bootstrap dropdown +1. Use the HTML structure provided by the [docs][bootstrap-dropdowns] +1. Add a specific class to the top level `.dropdown` element + + + ```Haml + .dropdown.my-dropdown + %button{ type: 'button', data: { toggle: 'dropdown' }, 'aria-haspopup': true, 'aria-expanded': false } + %span.dropdown-toggle-text + Toggle Dropdown + = icon('chevron-down') + + %ul.dropdown-menu + %li + %a + item! + ``` + + Or use the helpers + ```Haml + .dropdown.my-dropdown + = dropdown_toggle('Toogle!', { toggle: 'dropdown' }) + = dropdown_content + %li + %a + item! + ``` + +[bootstrap-dropdowns]: https://getbootstrap.com/docs/3.3/javascript/#dropdowns + +## Modals + +See also the [corresponding UX guide](../ux_guide/components.md#modals). + +We have a reusable Vue component for modals: [vue_shared/components/gl-modal.vue](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/app/assets/javascripts/vue_shared/components/gl-modal.vue) + +Here is an example of how to use it: + +```html + <gl-modal + id="dogs-out-modal" + :header-title-text="s__('ModalExample|Let the dogs out?')" + footer-primary-button-variant="danger" + :footer-primary-button-text="s__('ModalExample|Let them out')" + @submit="letOut(theDogs)" + > + {{ s__('ModalExample|You’re about to let the dogs out.') }} + </gl-modal> +``` + + diff --git a/doc/development/fe_guide/dropdowns.md b/doc/development/fe_guide/dropdowns.md index 6314f8f38d2..e9d6244355c 100644 --- a/doc/development/fe_guide/dropdowns.md +++ b/doc/development/fe_guide/dropdowns.md @@ -1,32 +1 @@ -# Dropdowns - - -## How to style a bootstrap dropdown -1. Use the HTML structure provided by the [docs][bootstrap-dropdowns] -1. Add a specific class to the top level `.dropdown` element - - - ```Haml - .dropdown.my-dropdown - %button{ type: 'button', data: { toggle: 'dropdown' }, 'aria-haspopup': true, 'aria-expanded': false } - %span.dropdown-toggle-text - Toggle Dropdown - = icon('chevron-down') - - %ul.dropdown-menu - %li - %a - item! - ``` - - Or use the helpers - ```Haml - .dropdown.my-dropdown - = dropdown_toggle('Toogle!', { toggle: 'dropdown' }) - = dropdown_content - %li - %a - item! - ``` - -[bootstrap-dropdowns]: https://getbootstrap.com/docs/3.3/javascript/#dropdowns +This page has moved [here](components.md#dropdowns). diff --git a/doc/development/fe_guide/img/gl-modal.png b/doc/development/fe_guide/img/gl-modal.png Binary files differnew file mode 100644 index 00000000000..47302e857bc --- /dev/null +++ b/doc/development/fe_guide/img/gl-modal.png diff --git a/doc/development/fe_guide/index.md b/doc/development/fe_guide/index.md index 72cb557d054..12dfc10812b 100644 --- a/doc/development/fe_guide/index.md +++ b/doc/development/fe_guide/index.md @@ -21,6 +21,8 @@ Working with our frontend assets requires Node (v4.3 or greater) and Yarn [jQuery][jquery] is used throughout the application's JavaScript, with [Vue.js][vue] for particularly advanced, dynamic elements. +We also use [Axios][axios] to handle all of our network requests. + ### Browser Support For our currently-supported browsers, see our [requirements][requirements]. @@ -77,8 +79,10 @@ Axios specific practices and gotchas. ## [Icons](icons.md) How we use SVG for our Icons. -## [Dropdowns](dropdowns.md) -How we use dropdowns. +## [Components](components.md) + +How we use UI components. + --- ## Style Guides @@ -122,6 +126,7 @@ The [externalization part of the guide](../i18n/externalization.md) explains the [webpack]: https://webpack.js.org/ [jquery]: https://jquery.com/ [vue]: http://vuejs.org/ +[axios]: https://github.com/axios/axios [airbnb-js-style-guide]: https://github.com/airbnb/javascript [scss-lint]: https://github.com/brigade/scss-lint [install]: ../../install/installation.md#4-node diff --git a/doc/development/fe_guide/style_guide_js.md b/doc/development/fe_guide/style_guide_js.md index 02773162801..917d28b48ee 100644 --- a/doc/development/fe_guide/style_guide_js.md +++ b/doc/development/fe_guide/style_guide_js.md @@ -207,10 +207,39 @@ Do not use them anymore and feel free to remove them when refactoring legacy cod var c = pureFunction(values.foo); ``` -1. Avoid constructors with side-effects +1. Avoid constructors with side-effects. +Although we aim for code without side-effects we need some side-effects for our code to run. + +If the class won't do anything if we only instantiate it, it's ok to add side effects into the constructor (_Note:_ The following is just an example. If the only purpose of the class is to add an event listener and handle the callback a function will be more suitable.) + +```javascript +// Bad +export class Foo { + constructor() { + this.init(); + } + init() { + document.addEventListener('click', this.handleCallback) + }, + handleCallback() { + + } +} + +// Good +export class Foo { + constructor() { + document.addEventListener() + } + handleCallback() { + } +} +``` + +On the other hand, if a class only needs to extend a third party/add event listeners in some specific cases, they should be initialized oustside of the constructor. 1. Prefer `.map`, `.reduce` or `.filter` over `.forEach` -A forEach will cause side effects, it will be mutating the array being iterated. Prefer using `.map`, +A forEach will most likely cause side effects, it will be mutating the array being iterated. Prefer using `.map`, `.reduce` or `.filter` ```javascript const users = [ { name: 'Foo' }, { name: 'Bar' } ]; @@ -302,20 +331,20 @@ Please check this [rules][eslint-plugin-vue-rules] for more documentation. #### Naming 1. **Extensions**: Use `.vue` extension for Vue components. -1. **Reference Naming**: Use camelCase for their instances: +1. **Reference Naming**: Use PascalCase for their instances: ```javascript // bad - import CardBoard from 'cardBoard' + import cardBoard from 'cardBoard.vue' components: { - CardBoard: + cardBoard, }; // good - import cardBoard from 'cardBoard' + import CardBoard from 'cardBoard.vue' components: { - cardBoard: + CardBoard, }; ``` diff --git a/doc/development/fe_guide/style_guide_scss.md b/doc/development/fe_guide/style_guide_scss.md index 86a8b4135af..655d94793dd 100644 --- a/doc/development/fe_guide/style_guide_scss.md +++ b/doc/development/fe_guide/style_guide_scss.md @@ -7,6 +7,8 @@ easy to maintain, and performant for the end-user. ### Naming +Filenames should use `snake_case`. + CSS classes should use the `lowercase-hyphenated` format rather than `snake_case` or `camelCase`. diff --git a/doc/development/feature_flags.md b/doc/development/feature_flags.md index 59e8a087e02..5d1f657015c 100644 --- a/doc/development/feature_flags.md +++ b/doc/development/feature_flags.md @@ -1,6 +1,6 @@ # Manage feature flags -Starting from GitLab 9.3 we support feature flags via +Starting from GitLab 9.3 we support feature flags for features in GitLab via [Flipper](https://github.com/jnunemaker/flipper/). You should use the `Feature` class (defined in `lib/feature.rb`) in your code to get, set and list feature flags. @@ -19,3 +19,8 @@ dynamic (querying the DB etc.). Once defined in `lib/feature.rb`, you will be able to activate a feature for a given feature group via the [`feature_group` param of the features API](../api/features.md#set-or-create-a-feature) + +## Feature flags for user applications + +GitLab does not yet support the use of feature flags in deployed user applications. +You can follow the progress on that [in the issue on our issue tracker](https://gitlab.com/gitlab-org/gitlab-ee/issues/779).
\ No newline at end of file diff --git a/doc/development/i18n/externalization.md b/doc/development/i18n/externalization.md index f493ad4ae66..c0a325a83e9 100644 --- a/doc/development/i18n/externalization.md +++ b/doc/development/i18n/externalization.md @@ -110,6 +110,8 @@ You can mark that content for translation with: In JavaScript we added the `__()` (double underscore parenthesis) function for translations. +In order to test JavaScript translations you have to change the GitLab localization to other language than English and you have to generate JSON files using `bundle exec rake gettext:po_to_json` or `bundle exec rake gettext:compile`. + ## Updating the PO files with the new content Now that the new content is marked for translation, we need to update the PO @@ -124,6 +126,9 @@ strings and remove any strings that aren't used anymore. You should check this file in. Once the changes are on master, they will be picked up by [Crowdin](http://translate.gitlab.com) and be presented for translation. +If there are merge conflicts in the `gitlab.pot` file, you can delete the file +and regenerate it using the same command. Confirm that you are not deleting any strings accidentally by looking over the diff. + The command also updates the translation files for each language: `locale/*/gitlab.po` These changes can be discarded, the languange files will be updated by Crowdin automatically. diff --git a/doc/development/i18n/index.md b/doc/development/i18n/index.md index 8aa0462d213..7290a175501 100644 --- a/doc/development/i18n/index.md +++ b/doc/development/i18n/index.md @@ -40,37 +40,12 @@ See [Translation guidelines](translation.md). ### Proof reading -Proof reading helps ensure the accuracy and consistency of translations. -All translations are proof read before being accepted. -If a translations requires changes, you will be notified with a comment explaining why. - -Community assistance proof reading translations is encouraged and appreciated. -Requests to become a proof reader will be considered on the merits of previous translations. - -- Bulgarian -- Chinese Simplified - - [Huang Tao](https://crowdin.com/profile/htve) -- Chinese Traditional - - [Huang Tao](https://crowdin.com/profile/htve) -- Chinese Traditional, Hong Kong - - [Huang Tao](https://crowdin.com/profile/htve) -- Dutch -- Esperanto -- French -- German -- Italian - - [Paolo Falomo](https://crowdin.com/profile/paolo.falomo) -- Japanese -- Korean - - [Huang Tao](https://crowdin.com/profile/htve) -- Portuguese, Brazilian -- Russian - - [Alexy Lustin](https://crowdin.com/profile/lustin) - - [Nikita Grylov](https://crowdin.com/profile/nixel2007) -- Spanish -- Ukrainian - -If you would like to be added as a proof reader, please [open an issue](https://gitlab.com/gitlab-org/gitlab-ce/issues). +Proof reading helps ensure the accuracy and consistency of translations. All +translations are proof read before being accepted. If a translations requires +changes, you will be notified with a comment explaining why. + +See [Proofreading Translations](proofreader.md) for more information on who's +able to proofread and instructions on becoming a proofreader yourself. ## Release diff --git a/doc/development/i18n/proofreader.md b/doc/development/i18n/proofreader.md new file mode 100644 index 00000000000..795e1e83105 --- /dev/null +++ b/doc/development/i18n/proofreader.md @@ -0,0 +1,48 @@ +# Proofread Translations + +Most translations are contributed, reviewed, and accepted by the community. We +are very appreciative of the work done by translators and proofreaders! + +## Proofreaders + +- Bulgarian +- Chinese Simplified + - Huang Tao - [GitLab](https://gitlab.com/htve), [Crowdin](https://crowdin.com/profile/htve) +- Chinese Traditional + - Huang Tao - [GitLab](https://gitlab.com/htve), [Crowdin](https://crowdin.com/profile/htve) +- Chinese Traditional, Hong Kong + - Huang Tao - [GitLab](https://gitlab.com/htve), [Crowdin](https://crowdin.com/profile/htve) +- Dutch +- Esperanto +- French +- German +- Italian + - Paolo Falomo - [GitLab](https://gitlab.com/paolofalomo), [Crowdin](https://crowdin.com/profile/paolo.falomo) +- Japanese +- Korean + - Huang Tao - [GitLab](https://gitlab.com/htve), [Crowdin](https://crowdin.com/profile/htve) +- Portuguese, Brazilian + - Paulo George Gomes Bezerra - [GitLab](https://gitlab.com/paulobezerra), [Crowdin](https://crowdin.com/profile/paulogomes.rep) +- Russian + - Nikita Grylov - [GitLab](https://gitlab.com/nixel2007), [Crowdin](https://crowdin.com/profile/nixel2007) + - Alexy Lustin - [GitLab](https://gitlab.com/allustin), [Crowdin](https://crowdin.com/profile/lustin) +- Spanish +- Ukrainian + - Volodymyr Sobotovych - [GitLab](https://gitlab.com/wheleph), [Crowdin](https://crowdin.com/profile/wheleph) + - Andrew Vityuk - [GitLab](https://gitlab.com/3_1_3_u), [Crowdin](https://crowdin.com/profile/andruwa13) + +## Become a proofreader + +> **Note:** Before requesting Proofreader permissions in Crowdin please make +> sure that you have a history of contributing translations to the GitLab +> project. + +1. Once your translations have been accepted, + [open a merge request](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/new) + to request Proofreader permissions and add yourself to the list above. + + In the merge request description, please include links to any projects you + have previously translated. + +1. Your request to become a proofreader will be considered on the merits of + your previous translations. diff --git a/doc/development/profiling.md b/doc/development/profiling.md index 97c997e0568..11878b4009b 100644 --- a/doc/development/profiling.md +++ b/doc/development/profiling.md @@ -27,6 +27,17 @@ Gitlab::Profiler.profile('/my-user') # Returns a RubyProf::Profile where 100 seconds is spent in UsersController#show ``` +For routes that require authorization you will need to provide a user to +`Gitlab::Profiler`. You can do this like so: + +```ruby +Gitlab::Profiler.profile('/gitlab-org/gitlab-test', user: User.first) +``` + +The user you provide will need to have a [personal access +token](https://docs.gitlab.com/ce/user/profile/personal_access_tokens.html) in +the GitLab instance. + Passing a `logger:` keyword argument to `Gitlab::Profiler.profile` will send ActiveRecord and ActionController log output to that logger. Further options are documented with the method source. diff --git a/doc/development/query_count_limits.md b/doc/development/query_count_limits.md index ebb6e0c2dac..310e3faf61b 100644 --- a/doc/development/query_count_limits.md +++ b/doc/development/query_count_limits.md @@ -1,8 +1,7 @@ # Query Count Limits -Each controller or API endpoint is allowed to execute up to 100 SQL queries. In -a production environment we'll only log an error in case this threshold is -exceeded, but in a test environment we'll raise an error instead. +Each controller or API endpoint is allowed to execute up to 100 SQL queries and +in test environments we'll raise an error when this threshold is exceeded. ## Solving Failing Tests diff --git a/doc/development/sidekiq_style_guide.md b/doc/development/sidekiq_style_guide.md index 59ebf41e09f..76ff51446ba 100644 --- a/doc/development/sidekiq_style_guide.md +++ b/doc/development/sidekiq_style_guide.md @@ -17,6 +17,9 @@ would be `process_something`. If you're not sure what queue a worker uses, you can find it using `SomeWorker.queue`. There is almost never a reason to manually override the queue name using `sidekiq_options queue: :some_queue`. +You must always add any new queues to `app/workers/all_queues.yml` otherwise +your worker will not run. + ## Queue Namespaces While different workers cannot share a queue, they can share a queue namespace. diff --git a/doc/development/testing_guide/testing_levels.md b/doc/development/testing_guide/testing_levels.md index 4adf0dc7c7a..e86c1f5232a 100644 --- a/doc/development/testing_guide/testing_levels.md +++ b/doc/development/testing_guide/testing_levels.md @@ -134,6 +134,10 @@ learn more. [GitLab QA]: https://gitlab.com/gitlab-org/gitlab-qa [part of GitLab Rails]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/qa +## EE-specific tests + +EE-specific tests follows the same organization, but under the `ee/spec` folder. + ## How to test at the correct level? As many things in life, deciding what to test at each level of testing is a |
