diff options
Diffstat (limited to 'doc/development')
24 files changed, 315 insertions, 71 deletions
diff --git a/doc/development/architecture.md b/doc/development/architecture.md index 54029e00507..d1ba7d3dfc3 100644 --- a/doc/development/architecture.md +++ b/doc/development/architecture.md @@ -133,8 +133,6 @@ Usage: /etc/init.d/postgresql {start|stop|restart|reload|force-reload|status} [v ### Log locations of the services -Note: `/home/git/` is shorthand for `/home/git`. - gitlabhq (includes Unicorn and Sidekiq logs) - `/home/git/gitlab/log/` contains `application.log`, `production.log`, `sidekiq.log`, `unicorn.stdout.log`, `githost.log` and `unicorn.stderr.log` normally. diff --git a/doc/development/automatic_ce_ee_merge.md b/doc/development/automatic_ce_ee_merge.md index 4b9791c95bc..5a784b6de06 100644 --- a/doc/development/automatic_ce_ee_merge.md +++ b/doc/development/automatic_ce_ee_merge.md @@ -61,7 +61,7 @@ against EE. 1. Tries to apply it to current EE `master` 1. If it applies cleanly, the job succeeds -In the case where the job fails, it means you should create a `ee-<ce_branch>` +In the case where the job fails, it means you should create an `ee-<ce_branch>` or `<ce_branch>-ee` branch, push it to EE and open a merge request against EE `master`. At this point if you retry the failing job in your CE merge request, it should diff --git a/doc/development/background_migrations.md b/doc/development/background_migrations.md index fd2b9d0e908..af2026c483e 100644 --- a/doc/development/background_migrations.md +++ b/doc/development/background_migrations.md @@ -123,7 +123,7 @@ roughly be as follows: scheduling jobs for newly created data. 1. In a post-deployment migration you'll need to ensure no jobs remain. To do so you can use `Gitlab::BackgroundMigration.steal` to process any remaining - jobs before continueing. + jobs before continuing. 1. Remove the old column. ## Example diff --git a/doc/development/changelog.md b/doc/development/changelog.md index 48cffc0dd18..c1f783ce877 100644 --- a/doc/development/changelog.md +++ b/doc/development/changelog.md @@ -12,9 +12,9 @@ following format: ```yaml --- -title: "Going through change[log]s" +title: "Change[log]s" merge_request: 1972 -author: Ozzy Osbourne +author: Black Sabbath type: added ``` @@ -127,7 +127,7 @@ type: If you're working on the GitLab EE repository, the entry will be added to `changelogs/unreleased-ee/` instead. -#### Arguments +### Arguments | Argument | Shorthand | Purpose | | ----------------- | --------- | ---------------------------------------------------------------------------------------------------------- | diff --git a/doc/development/doc_styleguide.md b/doc/development/doc_styleguide.md index 9cb1f708a6a..cfeeed2506d 100644 --- a/doc/development/doc_styleguide.md +++ b/doc/development/doc_styleguide.md @@ -34,7 +34,6 @@ The table below shows what kind of documentation goes where. | `doc/install/`| Probably the most visited directory, since `installation.md` is there. Ideally this should go under `doc/administration/`, but it's best to leave it as-is in order to avoid confusion (still debated though). | | `doc/update/` | Same with `doc/install/`. Should be under `administration/`, but this is a well known location, better leave as-is, at least for now. | | `doc/topics/` | Indexes per Topic (`doc/topics/topic-name/index.md`): all resources for that topic (user and admin documentation, articles, and third-party docs) | -| `doc/articles/` | [Technical Articles](writing_documentation.md#technical-articles): user guides, admin guides, technical overviews, tutorials (`doc/articles/article-title/index.md`). | --- @@ -67,11 +66,10 @@ The table below shows what kind of documentation goes where. 1. The `doc/topics/` directory holds topic-related technical content. Create `doc/topics/topic-name/subtopic-name/index.md` when subtopics become necessary. General user- and admin- related documentation, should be placed accordingly. -1. For technical articles, place their images under `doc/articles/article-title/img/`. --- -If you are unsure where a document should live, you can ping `@axil` in your +If you are unsure where a document should live, you can ping `@axil` or `@marcia` in your merge request. ## Text @@ -108,8 +106,8 @@ merge request. - Avoid adding things that show ephemeral statuses. For example, if a feature is considered beta or experimental, put this info in a note, not in the heading. - When introducing a new document, be careful for the headings to be - grammatically and syntactically correct. It is advised to mention one or all - of the following GitLab members for a review: `@axil`, `@rspeicher`, `@marcia`. + grammatically and syntactically correct. Mention one or all + of the following GitLab members for a review: `@axil` or `@marcia`. This is to ensure that no document with wrong heading is going live without an audit, thus preventing dead links and redirection issues when corrected @@ -203,7 +201,7 @@ You can combine one or more of the following: - Keep all file names in lower case. - Consider using PNG images instead of JPEG. - Compress all images with <https://tinypng.com/> or similar tool. -- Compress gifs with <https://ezgif.com/optimize> or similar toll. +- Compress gifs with <https://ezgif.com/optimize> or similar tool. - Images should be used (only when necessary) to _illustrate_ the description of a process, not to _replace_ it. @@ -330,6 +328,10 @@ For example, if you were to move `doc/workflow/lfs/lfs_administration.md` to git grep -n "lfs/lfs_administration" ``` +NOTE: **Note:** +If the document being moved has any Disqus comments on it, there are extra steps +to follow documented just [below](#redirections-for-pages-with-disqus-comments). + Things to note: - Since we also use inline documentation, except for the documentation itself, @@ -342,6 +344,32 @@ Things to note: documentation, sometimes it might be useful to search a path deeper. - The `*.md` extension is not used when a document is linked to GitLab's built-in help page, that's why we omit it in `git grep`. +- Use the checklist on the documentation MR description template. + +### Redirections for pages with Disqus comments + +If the documentation page being relocated already has any Disqus comments, +we need to preserve the Disqus thread. + +Disqus uses an identifier per page, and for docs.gitlab.com, the page identifier +is configured to be the page URL. Therefore, when we change the document location, +we need to preserve the old URL as the same Disqus identifier. + +To do that, add to the frontmatter the variable `redirect_from`, +using the old URL as value. For example, let's say I moved the document +available under `https://docs.gitlab.com/my-old-location/README.html` to a new location, +`https://docs.gitlab.com/my-new-location/index.html`. + +Into the **new document** frontmatter add the following: + +```yaml +--- +redirect_from: 'https://docs.gitlab.com/my-old-location/README.html' +--- +``` + +Note: it is necessary to include the file name in the `redirect_from` URL, +even if it's `index.html` or `README.html`. ## Configuration documentation for source and Omnibus installations @@ -392,7 +420,7 @@ the style below as a guide: In this case: - before each step list the installation method is declared in bold -- three dashes (`---`) are used to create an horizontal line and separate the +- three dashes (`---`) are used to create a horizontal line and separate the two methods - the code blocks are indented one or more spaces under the list item to render correctly diff --git a/doc/development/ee_features.md b/doc/development/ee_features.md index 1af839a27e1..f8cee89e650 100644 --- a/doc/development/ee_features.md +++ b/doc/development/ee_features.md @@ -87,9 +87,9 @@ still having access the class's implementation with `super`. There are a few gotchas with it: -- you should always add a `raise NotImplementedError unless defined?(super)` - guard clause in the "overrider" method to ensure that if the method gets - renamed in CE, the EE override won't be silently forgotten. +- you should always [`extend ::Gitlab::Utils::Override`] and use `override` to + guard the "overrider" method to ensure that if the method gets renamed in + CE, the EE override won't be silently forgotten. - when the "overrider" would add a line in the middle of the CE implementation, you should refactor the CE method and split it in smaller methods. Or create a "hook" method that is empty in CE, @@ -134,6 +134,9 @@ There are a few gotchas with it: guards: ``` ruby module EE::Base + extend ::Gitlab::Utils::Override + + override :do_something def do_something # Follow the above pattern to call super and extend it end @@ -174,10 +177,11 @@ implementation: ```ruby module EE - class ApplicationController - def after_sign_out_path_for(resource) - raise NotImplementedError unless defined?(super) + module ApplicationController + extend ::Gitlab::Utils::Override + override :after_sign_out_path_for + def after_sign_out_path_for(resource) if Gitlab::Geo.secondary? Gitlab::Geo.primary_node.oauth_logout_url(@geo_logout_state) else @@ -188,6 +192,8 @@ module EE end ``` +[`extend ::Gitlab::Utils::Override`]: utilities.md#override + #### Use self-descriptive wrapper methods When it's not possible/logical to modify the implementation of a @@ -208,8 +214,8 @@ end In EE, the implementation `ee/app/models/ee/users.rb` would be: ```ruby +override :full_private_access? def full_private_access? - raise NotImplementedError unless defined?(super) super || auditor? end ``` diff --git a/doc/development/fe_guide/axios.md b/doc/development/fe_guide/axios.md index 1daa6758171..0d9397c3bd5 100644 --- a/doc/development/fe_guide/axios.md +++ b/doc/development/fe_guide/axios.md @@ -27,10 +27,23 @@ This exported module should be used instead of directly using `axios` to ensure }); ``` -## Mock axios response on tests +## Mock axios response in tests -To help us mock the responses we need we use [axios-mock-adapter][axios-mock-adapter] +To help us mock the responses we are using [axios-mock-adapter][axios-mock-adapter]. +Advantages over [`spyOn()`]: + +- no need to create response objects +- does not allow call through (which we want to avoid) +- simple API to test error cases +- provides `replyOnce()` to allow for different responses + +We have also decided against using [axios interceptors] because they are not suitable for mocking. + +[axios interceptors]: https://github.com/axios/axios#interceptors +[`spyOn()`]: https://jasmine.github.io/api/edge/global.html#spyOn + +### Example ```javascript import axios from '~/lib/utils/axios_utils'; @@ -50,13 +63,13 @@ To help us mock the responses we need we use [axios-mock-adapter][axios-mock-ada }); afterEach(() => { - mock.reset(); + mock.restore(); }); ``` -### Mock poll requests on tests with axios +### Mock poll requests in tests with axios -Because polling function requires an header object, we need to always include an object as the third argument: +Because polling function requires a header object, we need to always include an object as the third argument: ```javascript mock.onGet('/users').reply(200, { foo: 'bar' }, {}); diff --git a/doc/development/fe_guide/style_guide_js.md b/doc/development/fe_guide/style_guide_js.md index 1cd66f27492..02773162801 100644 --- a/doc/development/fe_guide/style_guide_js.md +++ b/doc/development/fe_guide/style_guide_js.md @@ -101,16 +101,16 @@ followed by any global declarations, then a blank newline prior to any imports o ``` Import statements are following usual naming guidelines, for example object literals use camel case: - + ```javascript // some_object file export default { key: 'value', }; - + // bad import ObjectLiteral from 'some_object'; - + // good import objectLiteral from 'some_object'; ``` @@ -255,6 +255,10 @@ A forEach will cause side effects, it will be mutating the array being iterated. ### Vue.js +#### `eslint-vue-plugin` +We default to [eslint-vue-plugin][eslint-plugin-vue], with the `plugin:vue/recommended`. +Please check this [rules][eslint-plugin-vue-rules] for more documentation. + #### Basic Rules 1. The service has it's own file 1. The store has it's own file @@ -360,6 +364,10 @@ A forEach will cause side effects, it will be mutating the array being iterated. <component bar="bar" /> + + // bad + <component + bar="bar" /> ``` #### Quotes @@ -509,25 +517,7 @@ On those a default key should not be provided. ``` 1. Properties in a Vue Component: - 1. `name` - 1. `props` - 1. `mixins` - 1. `directives` - 1. `data` - 1. `components` - 1. `computedProps` - 1. `methods` - 1. `beforeCreate` - 1. `created` - 1. `beforeMount` - 1. `mounted` - 1. `beforeUpdate` - 1. `updated` - 1. `activated` - 1. `deactivated` - 1. `beforeDestroy` - 1. `destroyed` - + Check [order of properties in components rule][vue-order]. #### Vue and Bootstrap @@ -582,3 +572,6 @@ The goal of this accord is to make sure we are all on the same page. [eslintrc]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/.eslintrc [eslint-this]: http://eslint.org/docs/rules/class-methods-use-this [eslint-new]: http://eslint.org/docs/rules/no-new +[eslint-plugin-vue]: https://github.com/vuejs/eslint-plugin-vue +[eslint-plugin-vue-rules]: https://github.com/vuejs/eslint-plugin-vue#bulb-rules +[vue-order]: https://github.com/vuejs/eslint-plugin-vue/blob/master/docs/rules/order-in-components.md diff --git a/doc/development/fe_guide/style_guide_scss.md b/doc/development/fe_guide/style_guide_scss.md index 77b308c4a43..86a8b4135af 100644 --- a/doc/development/fe_guide/style_guide_scss.md +++ b/doc/development/fe_guide/style_guide_scss.md @@ -216,7 +216,7 @@ If you want a line or set of lines to be ignored by the linter, you can use ```scss // This lint rule is disabled because the class name comes from a gem. // scss-lint:disable SelectorFormat -.ui_charcoal { +.ui_indigo { background-color: #333; } // scss-lint:enable SelectorFormat diff --git a/doc/development/fe_guide/vue.md b/doc/development/fe_guide/vue.md index 6e9f18dd1c3..6c93c29124d 100644 --- a/doc/development/fe_guide/vue.md +++ b/doc/development/fe_guide/vue.md @@ -456,7 +456,7 @@ describe('Todos App', () => { }); ``` #### `mountComponent` helper -There is an helper in `spec/javascripts/helpers/vue_mount_component_helper.js` that allows you to mount a component with the given props: +There is a helper in `spec/javascripts/helpers/vue_mount_component_helper.js` that allows you to mount a component with the given props: ```javascript import Vue from 'vue'; diff --git a/doc/development/gitaly.md b/doc/development/gitaly.md index ca2048c7019..26abf967dcf 100644 --- a/doc/development/gitaly.md +++ b/doc/development/gitaly.md @@ -97,6 +97,29 @@ describe 'Gitaly Request count tests' do end ``` +## Running tests with a locally modified version of Gitaly + +Normally, gitlab-ce/ee tests use a local clone of Gitaly in `tmp/tests/gitaly` +pinned at the version specified in GITALY_SERVER_VERSION. If you want +to run tests locally against a modified version of Gitaly you can +replace `tmp/tests/gitaly` with a symlink. + +```shell +rm -rf tmp/tests/gitaly +ln -s /path/to/gitaly tmp/tests/gitaly +``` + +Make sure you run `make` in your local Gitaly directory before running +tests. Otherwise, Gitaly will fail to boot. + +If you make changes to your local Gitaly in between test runs you need +to manually run `make` again. + +Note that CI tests will not use your locally modified version of +Gitaly. To use a custom Gitaly version in CI you need to update +GITALY_SERVER_VERSION. You can use the format `=revision` to use a +non-tagged commit from https://gitlab.com/gitlab-org/gitaly in CI. + --- [Return to Development documentation](README.md) diff --git a/doc/development/migration_style_guide.md b/doc/development/migration_style_guide.md index a235dd74909..243ac7f0c98 100644 --- a/doc/development/migration_style_guide.md +++ b/doc/development/migration_style_guide.md @@ -4,7 +4,7 @@ When writing migrations for GitLab, you have to take into account that these will be ran by hundreds of thousands of organizations of all sizes, some with many years of data in their database. -In addition, having to take a server offline for a a upgrade small or big is a +In addition, having to take a server offline for an upgrade small or big is a big burden for most organizations. For this reason it is important that your migrations are written carefully, can be applied online and adhere to the style guide below. diff --git a/doc/development/performance.md b/doc/development/performance.md index e7c5a6ca07a..c4162a05b77 100644 --- a/doc/development/performance.md +++ b/doc/development/performance.md @@ -36,7 +36,8 @@ graphs/dashboards. GitLab provides built-in tools to aid the process of improving performance: -* [Sherlock](profiling.md#sherlock) +* [Profiling](profiling.md) + * [Sherlock](profiling.md#sherlock) * [GitLab Performance Monitoring](../administration/monitoring/performance/index.md) * [Request Profiling](../administration/monitoring/performance/request_profiling.md) * [QueryRecoder](query_recorder.md) for preventing `N+1` regressions diff --git a/doc/development/profiling.md b/doc/development/profiling.md index af79353b721..97c997e0568 100644 --- a/doc/development/profiling.md +++ b/doc/development/profiling.md @@ -4,6 +4,41 @@ To make it easier to track down performance problems GitLab comes with a set of profiling tools, some of these are available by default while others need to be explicitly enabled. +## Profiling a URL + +There is a `Gitlab::Profiler.profile` method, and corresponding +`bin/profile-url` script, that enable profiling a GET or POST request to a +specific URL, either as an anonymous user (the default) or as a specific user. + +When using the script, command-line documentation is available by passing no +arguments. + +When using the method in an interactive console session, any changes to the +application code within that console session will be reflected in the profiler +output. + +For example: + +```ruby +Gitlab::Profiler.profile('/my-user') +# Returns a RubyProf::Profile for the regular operation of this request +class UsersController; def show; sleep 100; end; end +Gitlab::Profiler.profile('/my-user') +# Returns a RubyProf::Profile where 100 seconds is spent in UsersController#show +``` + +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. + +[GitLab-Profiler](https://gitlab.com/gitlab-com/gitlab-profiler) is a project +that builds on this to add some additional niceties, such as allowing +configuration with a single Yaml file for multiple URLs, and uploading of the +profile and log output to S3. + +For GitLab.com, you can find the latest results here: +<http://redash.gitlab.com/dashboard/gitlab-profiler-statistics> + ## Sherlock Sherlock is a custom profiling tool built into GitLab. Sherlock is _only_ @@ -27,13 +62,3 @@ Bullet will log query problems to both the Rails log as well as the Chrome console. As a follow up to finding `N+1` queries with Bullet, consider writing a [QueryRecoder test](query_recorder.md) to prevent a regression. - -## GitLab Profiler - - -[Gitlab-Profiler](https://gitlab.com/gitlab-com/gitlab-profiler) was built to -help developers understand why specific URLs of their application may be slow -and to provide hard data that can help reduce load times. - -For GitLab.com, you can find the latest results here: -<http://redash.gitlab.com/dashboard/gitlab-profiler-statistics> diff --git a/doc/development/rake_tasks.md b/doc/development/rake_tasks.md index ceff57276d2..dc88ce1522c 100644 --- a/doc/development/rake_tasks.md +++ b/doc/development/rake_tasks.md @@ -8,7 +8,7 @@ Note that if your db user does not have advanced privileges you must create the bundle exec rake setup ``` -The `setup` task is a alias for `gitlab:setup`. +The `setup` task is an alias for `gitlab:setup`. This tasks calls `db:reset` to create the database, calls `add_limits_mysql` that adds limits to the database schema in case of a MySQL database and finally it calls `db:seed_fu` to seed the database. Note: `db:setup` calls `db:seed` but this does nothing. diff --git a/doc/development/testing_guide/best_practices.md b/doc/development/testing_guide/best_practices.md index edb8f372ea3..df80cd9f584 100644 --- a/doc/development/testing_guide/best_practices.md +++ b/doc/development/testing_guide/best_practices.md @@ -26,7 +26,6 @@ Here are some things to keep in mind regarding test performance: - Use `.method` to describe class methods and `#method` to describe instance methods. - Use `context` to test branching logic. -- Don't assert against the absolute value of a sequence-generated attribute (see [Gotchas](../gotchas.md#dont-assert-against-the-absolute-value-of-a-sequence-generated-attribute)). - Try to match the ordering of tests to the ordering within the class. - Try to follow the [Four-Phase Test][four-phase-test] pattern, using newlines to separate phases. @@ -89,6 +88,8 @@ Finished in 34.51 seconds (files took 0.76702 seconds to load) 1 example, 0 failures ``` +Note: `live_debug` only works on javascript enabled specs. + ### `let` variables GitLab's RSpec suite has made extensive use of `let` variables to reduce diff --git a/doc/development/testing_guide/end_to_end_tests.md b/doc/development/testing_guide/end_to_end_tests.md new file mode 100644 index 00000000000..5b4f6511f04 --- /dev/null +++ b/doc/development/testing_guide/end_to_end_tests.md @@ -0,0 +1,80 @@ +# End-to-End Testing + +## What is End-to-End testing? + +End-to-End testing is a strategy used to check whether your application works +as expected across entire software stack and architecture, including +integration of all microservices and components that are supposed to work +together. + +## How do we test GitLab? + +We use [Omnibus GitLab][omnibus-gitlab] to build GitLab packages and then we +test these packages using [GitLab QA][gitlab-qa] project, which is entirely +black-box, click-driven testing framework. + +### Testing nightly builds + +We run scheduled pipeline each night to test nightly builds created by Omnibus. +You can find these nightly pipelines at [GitLab QA pipelines page][gitlab-qa-pipelines]. + +### Testing code in merge requests + +It is possible to run end-to-end tests (eventually being run within a +[GitLab QA pipeline][gitlab-qa-pipelines]) for a merge request by triggering +the `package-qa` manual action, that should be present in a merge request +widget. + +Manual action that starts end-to-end tests is also available in merge requests +in Omnibus GitLab project. + +Below you can read more about how to use it and how does it work. + +#### How does it work? + +Currently, we are using _multi-project pipeline_-like approach to run QA +pipelines. + +1. Developer triggers a manual action, that can be found in CE and EE merge +requests. This starts a chain of pipelines in multiple projects. + +1. The script being executed triggers a pipeline in GitLab Omnibus and waits +for the resulting status. We call this a _status attribution_. + +1. GitLab packages are being built in Omnibus pipeline. Packages are going to be +pushed to Container Registry. + +1. When packages are ready, and available in the registry, a final step in the +pipeline, that is now running in Omnibus, triggers a new pipeline in the GitLab +QA project. It also waits for a resulting status. + +1. GitLab QA pulls images from the registry, spins-up containers and runs tests +against a test environment that has been just orchestrated by the `gitlab-qa` +tool. + +1. The result of the GitLab QA pipeline is being propagated upstream, through +Omnibus, back to CE / EE merge request. + +#### How do I write tests? + +In order to write new tests, you first need to learn more about GitLab QA +architecture. See the [documentation about it][gitlab-qa-architecture] in +GitLab QA project. + +Once you decided where to put test environment orchestration scenarios and +instance specs, take a look at the [relevant documentation][instance-qa-readme] +and examples in [the `qa/` directory][instance-qa-examples]. + +## Where can I ask for help? + +You can ask question in the `#qa` channel on Slack (GitLab internal) or you can +find an issue you would like to work on in [the issue tracker][gitlab-qa-issues] +and start a new discussion there. + +[omnibus-gitlab]: https://gitlab.com/gitlab-org/omnibus-gitlab +[gitlab-qa]: https://gitlab.com/gitlab-org/gitlab-qa +[gitlab-qa-pipelines]: https://gitlab.com/gitlab-org/gitlab-qa/pipelines +[gitlab-qa-architecture]: https://gitlab.com/gitlab-org/gitlab-qa/blob/master/docs/architecture.md +[gitlab-qa-issues]: https://gitlab.com/gitlab-org/gitlab-qa/issues +[instance-qa-readme]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/qa/README.md +[instance-qa-examples]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/qa/qa diff --git a/doc/development/testing_guide/index.md b/doc/development/testing_guide/index.md index 65386f231a0..74d09eb91ff 100644 --- a/doc/development/testing_guide/index.md +++ b/doc/development/testing_guide/index.md @@ -65,6 +65,13 @@ Everything you should know about how to test Rake tasks. --- +## [End-to-end tests](end_to_end_tests.md) + +Everything you should know about how to run end-to-end tests using +[GitLab QA][gitlab-qa] testing framework. + +--- + ## Spinach (feature) tests GitLab [moved from Cucumber to Spinach](https://github.com/gitlabhq/gitlabhq/pull/1426) @@ -89,3 +96,4 @@ test should be re-implemented using RSpec instead. [Capybara]: https://github.com/teamcapybara/capybara [Karma]: http://karma-runner.github.io/ [Jasmine]: https://jasmine.github.io/ +[gitlab-qa]: https://gitlab.com/gitlab-org/gitlab-qa diff --git a/doc/development/testing_guide/testing_levels.md b/doc/development/testing_guide/testing_levels.md index 1cbd4350284..4adf0dc7c7a 100644 --- a/doc/development/testing_guide/testing_levels.md +++ b/doc/development/testing_guide/testing_levels.md @@ -121,6 +121,9 @@ running feature tests (i.e. using Capybara) against it. The actual test scenarios and steps are [part of GitLab Rails] so that they're always in-sync with the codebase. +Read a separate document about [end-to-end tests](end_to_end_tests.md) to +learn more. + [multiple pieces]: ../architecture.md#components [GitLab Shell]: https://gitlab.com/gitlab-org/gitlab-shell [GitLab Workhorse]: https://gitlab.com/gitlab-org/gitlab-workhorse diff --git a/doc/development/utilities.md b/doc/development/utilities.md index 951c3ef85ce..8f9aff1a35f 100644 --- a/doc/development/utilities.md +++ b/doc/development/utilities.md @@ -45,6 +45,51 @@ We developed a number of utilities to ease development. [:hello, "world", :this, :crushes, "an entire", "hash"] ``` +## [`Override`](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/lib/gitlab/utils/override.rb) + +* This utility could help us check if a particular method would override + another method or not. It has the same idea of Java's `@Override` annotation + or Scala's `override` keyword. However we only do this check when + `ENV['STATIC_VERIFICATION']` is set to avoid production runtime overhead. + This is useful to check: + + * If we have typos in overriding methods. + * If we renamed the overridden methods, making original overriding methods + overrides nothing. + + Here's a simple example: + + ``` ruby + class Base + def execute + end + end + + class Derived < Base + extend ::Gitlab::Utils::Override + + override :execute # Override check happens here + def execute + end + end + ``` + + This also works on modules: + + ``` ruby + module Extension + extend ::Gitlab::Utils::Override + + override :execute # Modules do not check this immediately + def execute + end + end + + class Derived < Base + prepend Extension # Override check happens here, not in the module + end + ``` + ## [`StrongMemoize`](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/lib/gitlab/utils/strong_memoize.rb) * Memoize the value even if it is `nil` or `false`. diff --git a/doc/development/ux_guide/animation.md b/doc/development/ux_guide/animation.md index d190ee1b0ff..797390a6845 100644 --- a/doc/development/ux_guide/animation.md +++ b/doc/development/ux_guide/animation.md @@ -27,7 +27,7 @@ View the [interactive example](http://codepen.io/awhildy/full/GNyEvM/) here. ### Dropdowns -The dropdown menu should feel like it is appearing from the triggering element. Combining a position shift `400ms cubic-bezier(0.23, 1, 0.32, 1)` with a opacity animation `200ms linear` on the second half of the motion achieves this affect. +The dropdown menu should feel like it is appearing from the triggering element. Combining a position shift `400ms cubic-bezier(0.23, 1, 0.32, 1)` with an opacity animation `200ms linear` on the second half of the motion achieves this affect. View the [interactive example](http://codepen.io/awhildy/full/jVLJpb/) here. diff --git a/doc/development/ux_guide/components.md b/doc/development/ux_guide/components.md index d396964e7c1..012c64be79f 100644 --- a/doc/development/ux_guide/components.md +++ b/doc/development/ux_guide/components.md @@ -108,7 +108,7 @@ Primary buttons communicate the main call to action. There should only be one ca  #### Secondary -Secondary buttons are for alternative commands. They should be conveyed by a button with an stroke, and no background fill. +Secondary buttons are for alternative commands. They should be conveyed by a button with a stroke, and no background fill.  @@ -181,7 +181,7 @@ A count element is used in navigation contexts where it is helpful to indicate t ## Lists -Lists are used where ever there is a single column of information to display. Ths [issues list](https://gitlab.com/gitlab-org/gitlab-ce/issues) is an example of a important list in the GitLab UI. +Lists are used where ever there is a single column of information to display. Ths [issues list](https://gitlab.com/gitlab-org/gitlab-ce/issues) is an example of an important list in the GitLab UI. ### Types @@ -269,7 +269,7 @@ Modals are only used for having a conversation and confirmation with the user. T * Modals contain the header, body, and actions. * **Header(1):** The header title is a question instead of a descriptive phrase. * **Body(2):** The content in body should never be ambiguous and unclear. It provides specific information. - * **Actions(3):** Contains a affirmative action, a dismissive action, and an extra action. The order of actions from left to right: Dismissive action → Extra action → Affirmative action + * **Actions(3):** Contains an affirmative action, a dismissive action, and an extra action. The order of actions from left to right: Dismissive action → Extra action → Affirmative action * Confirmations regarding labels should keep labeling styling. * References to commits, branches, and tags should be **monospaced**. diff --git a/doc/development/ux_guide/copy.md b/doc/development/ux_guide/copy.md index af842da7f62..070efdc15b5 100644 --- a/doc/development/ux_guide/copy.md +++ b/doc/development/ux_guide/copy.md @@ -27,7 +27,7 @@ This means that, as a rule, copy should be very short. A long message or label i >**Example:**
Use `Add` instead of `Add issue` as a button label.
-Preferrably use context and placement of controls to make it obvious what clicking on them will do.
+Preferably use context and placement of controls to make it obvious what clicking on them will do.
---
diff --git a/doc/development/writing_documentation.md b/doc/development/writing_documentation.md index 43a79ffcaa5..2a1d744668b 100644 --- a/doc/development/writing_documentation.md +++ b/doc/development/writing_documentation.md @@ -15,7 +15,7 @@ request introducing these changes must be accompanied by the documentation (either updating existing ones or creating new ones). This is also valid when changes are introduced to the UI. -The one resposible for writing the first piece of documentation is the developer who +The one responsible for writing the first piece of documentation is the developer who wrote the code. It's the job of the Product Manager to ensure all features are shipped with its docs, whether is a small or big change. At the pace GitLab evolves, this is the only way to keep the docs up-to-date. If you have any questions about it, @@ -25,13 +25,33 @@ them to review it for you. We use the [monthly release blog post](https://about.gitlab.com/handbook/marketing/blog/release-posts/#monthly-releases) as a changelog checklist to ensure everything is documented. +Whenever you submit a merge request for the documentation, use the documentation MR description template. + +### Documentation directory structure + +The documentation is structured based on the GitLab UI structure itself, +separated by [`user`](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/user), +[`administrator`](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/administration), and [`contributor`](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/development). + +To learn where to place a new document, check the [documentation style guide](doc_styleguide.md#location-and-naming-of-documents). + +In order to have a [solid site structure](https://searchengineland.com/seo-benefits-developing-solid-site-structure-277456) for our documentation, +all docs should be linked. Every new document should be cross-linked to its related documentation, and linked from its topic-related index, when existent. + +The directories `/workflow/`, `/gitlab-basics/`, `/university/`, and `/articles/` have +been deprecated and the majority their docs have been moved to their correct location +in small iterations. Please don't create new docs in these folders. + +To move a document from its location to another directory, read the section +[changing document location](doc_styleguide.md#changing-document-location) of the doc style guide. + ### Feature overview and use cases Every major feature (regardless if present in GitLab Community or Enterprise editions) should present, at the beginning of the document, two main sections: **overview** and **use cases**. Every GitLab EE-only feature should also contain these sections. -**Overview**: at the name suggests, the goal here is to provide an overview of the feature. +**Overview**: as the name suggests, the goal here is to provide an overview of the feature. Describe what is it, what it does, why it is important/cool/nice-to-have, what problem it solves, and what you can do with this feature that you couldn't do before. |