diff options
Diffstat (limited to 'doc/development')
32 files changed, 567 insertions, 154 deletions
diff --git a/doc/development/README.md b/doc/development/README.md index 45e9565f9a7..3c77e99b8cf 100644 --- a/doc/development/README.md +++ b/doc/development/README.md @@ -39,9 +39,9 @@ comments: false - [Sidekiq debugging](sidekiq_debugging.md) - [Gotchas](gotchas.md) to avoid - [Avoid modules with instance variables](module_with_instance_variables.md) if possible -- [Issue and merge requests state models](object_state_models.md) - [How to dump production data to staging](db_dump.md) - [Working with the GitHub importer](github_importer.md) +- [Working with Merge Request diffs](diffs.md) ## Performance guides diff --git a/doc/development/background_migrations.md b/doc/development/background_migrations.md index fc1b202b5eb..46c5baddb9c 100644 --- a/doc/development/background_migrations.md +++ b/doc/development/background_migrations.md @@ -24,7 +24,7 @@ Some examples where background migrations can be useful: * Migrating events from one table to multiple separate tables. * Populating one column based on JSON stored in another column. -* Migrating data that depends on the output of exernal services (e.g. an API). +* Migrating data that depends on the output of external services (e.g. an API). ## Isolation @@ -46,7 +46,7 @@ See [Sidekiq best practices guidelines](https://github.com/mperham/sidekiq/wiki/ for more details. Make sure that in case that your migration job is going to be retried data -integrity is guarateed. +integrity is guaranteed. ## How It Works @@ -133,11 +133,19 @@ roughly be as follows: 1. Release B: 1. Deploy code so that the application starts using the new column and stops 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 continuing. + 1. In a post-deployment migration you'll need to ensure no jobs remain. + 1. Use `Gitlab::BackgroundMigration.steal` to process any remaining + jobs in Sidekiq. + 1. Reschedule the migration to be run directly (i.e. not through Sidekiq) + on any rows that weren't migrated by Sidekiq. This can happen if, for + instance, Sidekiq received a SIGKILL, or if a particular batch failed + enough times to be marked as dead. 1. Remove the old column. +This may also require a bump to the [import/export version][import-export], if +importing a project from a prior version of GitLab requires the data to be in +the new format. + ## Example To explain all this, let's use the following example: the table `services` has a @@ -296,3 +304,4 @@ for more details. [migrations-readme]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/spec/migrations/README.md [issue-rspec-hooks]: https://gitlab.com/gitlab-org/gitlab-ce/issues/35351 [reliable-sidekiq]: https://gitlab.com/gitlab-org/gitlab-ce/issues/36791 +[import-export]: ../user/project/settings/import_export.md diff --git a/doc/development/changelog.md b/doc/development/changelog.md index 1962392a9eb..a9fa5ae834f 100644 --- a/doc/development/changelog.md +++ b/doc/development/changelog.md @@ -22,7 +22,7 @@ The `merge_request` value is a reference to a merge request that adds this entry, and the `author` key is used to give attribution to community contributors. **Both are optional**. The `type` field maps the category of the change, -valid options are: added, fixed, changed, deprecated, removed, security, other. **Type field is mandatory**. +valid options are: added, fixed, changed, deprecated, removed, security, performance, other. **Type field is mandatory**. Community contributors and core team members are encouraged to add their name to the `author` field. GitLab team members **should not**. @@ -44,6 +44,7 @@ the `author` field. GitLab team members **should not**. - _Any_ contribution from a community member, no matter how small, **may** have a changelog entry regardless of these guidelines if the contributor wants one. Example: "Fixed a typo on the search results page. (Jane Smith)" +- Performance improvements **should** have a changelog entry. ## Writing good changelog entries diff --git a/doc/development/diffs.md b/doc/development/diffs.md new file mode 100644 index 00000000000..55fc16e0b33 --- /dev/null +++ b/doc/development/diffs.md @@ -0,0 +1,115 @@ +# Working with Merge Request diffs + +Currently we rely on different sources to present merge request diffs, these include: + +- Rugged gem +- Gitaly service +- Database (through `merge_request_diff_files`) +- Redis (cached highlighted diffs) + +We're constantly moving Rugged calls to Gitaly and the progress can be followed through [Gitaly repo](https://gitlab.com/gitlab-org/gitaly). + +## Architecture overview + +When refreshing a Merge Request (pushing to a source branch, force-pushing to target branch, or if the target branch now contains any commits from the MR) +we fetch the comparison information using `Gitlab::Git::Compare`, which fetches `base` and `head` data using Gitaly and diff between them through +`Gitlab::Git::Diff.between` (which uses _Gitaly_ if it's enabled, otherwise _Rugged_). +The diffs fetching process _limits_ single file diff sizes and the overall size of the whole diff through a series of constant values. Raw diff files are +then persisted on `merge_request_diff_files` table. + +Even though diffs higher than 10kb are collapsed (`Gitlab::Git::Diff::COLLAPSE_LIMIT`), we still keep them on Postgres. However, diff files over _safety limits_ +(see the [Diff limits section](#diff-limits)) are _not_ persisted. + +In order to present diffs information on the Merge Request diffs page, we: + +1. Fetch all diff files from database `merge_request_diff_files` +2. Fetch the _old_ and _new_ file blobs in batch to: + 1. Highlight old and new file content + 2. Know which viewer it should use for each file (text, image, deleted, etc) + 3. Know if the file content changed + 4. Know if it was stored externally + 5. Know if it had storage errors +3. If the diff file is cacheable (text-based), it's cached on Redis +using `Gitlab::Diff::FileCollection::MergeRequestDiff` + +## Diff limits + +As explained above, we limit single diff files and the size of the whole diff. There are scenarios where we collapse the diff file, +and cases where the diff file is not presented at all, and the user is guided to the Blob view. Here we'll go into details about +these limits. + +### Diff collection limits + +Limits that act onto all diff files collection. Files number, lines number and files size are considered. + +```ruby +Gitlab::Git::DiffCollection.collection_limits[:safe_max_files] = Gitlab::Git::DiffCollection::DEFAULT_LIMITS[:max_files] = 100 +``` + +File diffs will be collapsed (but be expandable) if 100 files have already been rendered. + + +```ruby +Gitlab::Git::DiffCollection.collection_limits[:safe_max_lines] = Gitlab::Git::DiffCollection::DEFAULT_LIMITS[:max_lines] = 5000 +``` + +File diffs will be collapsed (but be expandable) if 5000 lines have already been rendered. + + +```ruby +Gitlab::Git::DiffCollection.collection_limits[:safe_max_bytes] = Gitlab::Git::DiffCollection.collection_limits[:safe_max_files] * 5.kilobytes = 500.kilobytes +``` + +File diffs will be collapsed (but be expandable) if 500 kilobytes have already been rendered. + + +```ruby +Gitlab::Git::DiffCollection.collection_limits[:max_files] = Commit::DIFF_HARD_LIMIT_FILES = 1000 +``` + +No more files will be rendered at all if 1000 files have already been rendered. + + +```ruby +Gitlab::Git::DiffCollection.collection_limits[:max_lines] = Commit::DIFF_HARD_LIMIT_LINES = 50000 +``` + +No more files will be rendered at all if 50,000 lines have already been rendered. + +```ruby +Gitlab::Git::DiffCollection.collection_limits[:max_bytes] = Gitlab::Git::DiffCollection.collection_limits[:max_files] * 5.kilobytes = 5000.kilobytes +``` + +No more files will be rendered at all if 5 megabytes have already been rendered. + + +### Individual diff file limits + +Limits that act onto each diff file of a collection. Files number, lines number and files size are considered. + +```ruby +Gitlab::Git::Diff::COLLAPSE_LIMIT = 10.kilobytes +``` + +File diff will be collapsed (but be expandable) if it is larger than 10 kilobytes. + +```ruby +Gitlab::Git::Diff::SIZE_LIMIT = 100.kilobytes +``` + +File diff will not be rendered if it's larger than 100 kilobytes. + + +```ruby +Commit::DIFF_SAFE_LINES = Gitlab::Git::DiffCollection::DEFAULT_LIMITS[:max_lines] = 5000 +``` + +File diff will be suppressed (technically different from collapsed, but behaves the same, and is expandable) if it has more than 5000 lines. + +## Viewers + +Diff Viewers, which can be found on `models/diff_viewer/*` are classes used to map metadata about each type of Diff File. It has information +whether it's a binary, which partial should be used to render it or which File extensions this class accounts for. + +`DiffViewer::Base` validates _blobs_ (old and new versions) content, extension and file type in order to check if it can be rendered. + diff --git a/doc/development/doc_styleguide.md b/doc/development/doc_styleguide.md index 41e3412c7ff..5da015ca557 100644 --- a/doc/development/doc_styleguide.md +++ b/doc/development/doc_styleguide.md @@ -4,7 +4,7 @@ The documentation style guide defines the markup structure used in GitLab documentation. Check the [documentation guidelines](writing_documentation.md) for general development instructions. -Check the GitLab hanbook for the [writing styles guidelines](https://about.gitlab.com/handbook/communication/#writing-style-guidelines). +Check the GitLab handbook for the [writing styles guidelines](https://about.gitlab.com/handbook/communication/#writing-style-guidelines). ## Text @@ -19,7 +19,7 @@ Check the GitLab hanbook for the [writing styles guidelines](https://about.gitla - Unless there's a logical reason not to, add documents in alphabetical order - Write in US English - Use [single spaces][] instead of double spaces -- Jump a line between different markups (e.g., after every paragraph, hearder, list, etc) +- Jump a line between different markups (e.g., after every paragraph, header, list, etc) - Capitalize "G" and "L" in GitLab - Capitalize feature, products, and methods names. E.g.: GitLab Runner, Geo, Issue Boards, Git, Prometheus, Continuous Integration. @@ -157,6 +157,39 @@ below. Otherwise, leave this mention out. +### Product badges + +When a feature is available in EE-only tiers, add the corresponding tier according to the +feature availability: + +- For GitLab Starter and GitLab.com Bronze: `**[STARTER]**` +- For GitLab Premium and GitLab.com Silver: `**[PREMIUM]**` +- For GitLab Ultimate and GitLab.com Gold: `**[ULTIMATE]**` +- For GitLab Core and GitLab.com Free: `**[CORE]**` + +To exclude GitLab.com tiers (when the feature is not available in GitLab.com), add the +keyword "only": + +- For GitLab Starter: `**[STARTER ONLY]**` +- For GitLab Premium: `**[PREMIUM ONLY]**` +- For GitLab Ultimate: `**[ULTIMATE ONLY]**` +- For GitLab Core: `**[CORE ONLY]**` + +The tier should be ideally added to headers, so that the full badge will be displayed. +But it can be also mentioned from paragraphs, list items, and table cells. For these cases, +the tier mention will be represented by an orange question mark. +E.g., `**[STARTER]**` renders **[STARTER]**, `**[STARTER ONLY]**` renders **[STARTER ONLY]**. + +The absence of tiers' mentions mean that the feature is available in GitLab Core, +GitLab.com Free, and higher tiers. + +#### How it works + +Introduced by [!244](https://gitlab.com/gitlab-com/gitlab-docs/merge_requests/244), +the special markup `**[STARTER]**` will generate a `span` element to trigger the +badges and tooltips (`<span class="badge-trigger starter">`). When the keyword +"only" is added, the corresponding GitLab.com badge will not be displayed. + ### GitLab Restart There are many cases that a restart/reconfigure of GitLab is required. To diff --git a/doc/development/ee_features.md b/doc/development/ee_features.md index 287143d6255..4873090a2d4 100644 --- a/doc/development/ee_features.md +++ b/doc/development/ee_features.md @@ -279,7 +279,7 @@ end ``` In `lib/gitlab/visibility_level.rb` this method is used to return the -allowed visibilty levels: +allowed visibility levels: ```ruby def levels_for_user(user = nil) diff --git a/doc/development/emails.md b/doc/development/emails.md index 4dbf064fd75..73cac82caf0 100644 --- a/doc/development/emails.md +++ b/doc/development/emails.md @@ -74,6 +74,24 @@ See the [Rails guides] for more info. 1. Reply by email should now be working. +## Email namespace + +If you need to implement a new feature which requires a new email handler, follow these rules: + + - You must choose a namespace. The namespace cannot contain `/` or `+`, and cannot match `\h{16}`. + - If your feature is related to a project, you will append the namespace **after** the project path, separated by a `+` + - If you have different actions in the namespace, you add the actions **after** the namespace separated by a `+`. The action name cannot contain `/` or `+`, , and cannot match `\h{16}`. + - You will register your handlers in `lib/gitlab/email/handler.rb` + +Therefore, these are the only valid formats for an email handler: + + - `path/to/project+namespace` + - `path/to/project+namespace+action` + - `namespace` + - `namespace+action` + +Please note that `path/to/project` is used in GitLab Premium as handler for the Service Desk feature. + --- [Return to Development documentation](README.md) diff --git a/doc/development/fe_guide/development_process.md b/doc/development/fe_guide/development_process.md new file mode 100644 index 00000000000..5504a6421d5 --- /dev/null +++ b/doc/development/fe_guide/development_process.md @@ -0,0 +1,77 @@ +# Frontend Development Process + +You can find more about the organization of the frontend team in the [handbook](https://about.gitlab.com/handbook/frontend/). + +## Development Checklist + +The idea is to remind us about specific topics during the time we build a new feature or start something. This is a common practice in other industries (like pilots) that also use standardised checklists to reduce problems early on. + +Copy the content over to your issue or merge request and if something doesn't apply simply remove it from your current list. + +This checklist is intended to help us during development of bigger features/refactorings, it's not a "use it always and every point always matches" list. + +Please use your best judgement when to use it and please contribute new points through merge requests if something comes to your mind. + +--- + +### Frontend development + +#### Planning development + +- [ ] Check the current set weight of the issue, does it fit your estimate? +- [ ] Are all [departments](https://about.gitlab.com/handbook/engineering/#engineering-teams) that are needed from your perspective already involved in the issue? (For example is UX missing?) +- [ ] Is the specification complete? Are you missing decisions? How about error handling/defaults/edge cases? Take your time to understand the needed implementation and go through its flow. +- [ ] Are all necessary UX specifications available that you will need in order to implement? Are there new UX components/patterns in the designs? Then contact the UI component team early on. How should error messages or validation be handled? +- [ ] **Library usage** Use Vuex as soon as you have even a medium state to manage, use Vue router if you need to have different views internally and want to link from the outside. Check what libraries we already have for which occassions. +- [ ] **Plan your implementation:** + - [ ] **Architecture plan:** Create a plan aligned with GitLab's architecture, how you are going to do the implementation, for example Vue application setup and its components (through [onion skinning](https://gitlab.com/gitlab-org/gitlab-ce/issues/35873#note_39994091)), Store structure and data flow, which existing Vue components can you reuse. Its a good idea to go through your plan with another engineer to refine it. + - [ ] **Backend:** The best way is to kickoff the implementation in a call and discuss with the assigned Backend engineer what you will need from the backend and also when. Can you reuse existing API's? How is the performance with the planned architecture? Maybe create together a JSON mock object to already start with development. + - [ ] **Communication:** It also makes sense to have for bigger features an own slack channel (normally called #f_{feature_name}) and even weekly demo calls with all people involved. + - [ ] **Dependency Plan:** Are there big dependencies in the plan between you and others, then maybe create an execution diagram to show what is blocking which part and the order of the different parts. + - [ ] **Task list:** Create a simple checklist of the subtasks that are needed for the implementation, also consider creating even sub issues. (for example show a comment, delete a comment, update a comment, etc.). This helps you and also everyone else following the implementation +- [ ] **Keep it small** To make it easier for you and also all reviewers try to keep merge requests small and merge into a feature branch if needed. To accomplish that you need to plan that from the start. Different methods are: + - [ ] **Skeleton based plan** Start with an MR that has the skeleton of the components with placeholder content. In following MRs you can fill the components with interactivity. This also makes it easier to spread out development on multiple people. + - [ ] **Cookie Mode** Think about hiding the feature behind a cookie flag if the implementation is on top of existing features + - [ ] **New route** Are you refactoring something big then you might consider adding a new route where you implement the new feature and when finished delete the current route and rename the new one. (for example 'merge_request' and 'new_merge_request') +- [ ] **Setup** Is there any specific setup needed for your implementation (for example a kubernetes cluster)? Then let everyone know if it is not already mentioned where they can find documentation (if it doesn't exist - create it) +- [ ] **Security** Are there any new security relevant implementations? Then please contact the security team for an app security review. If you are not sure ask our [domain expert](https://about.gitlab.com/handbook/frontend/#frontend-domain-experts) + +#### During development + +- [ ] Check off tasks on your created task list to keep everyone updated on the progress +- [ ] [Share your work early with reviewers/maintainers](#share-your-work-early) +- [ ] Share your work with UXer and Product Manager with Screenshots and/or [GIF's](https://about.gitlab.com/handbook/product/making-gifs/). They are easy to create for you and keep them up to date. +- [ ] If you are blocked on something let everyone on the issue know through a comment. +- [ ] Are you unable to work on this issue for a longer period of time, also let everyone know. +- [ ] **Documentation** Update/add docs for the new feature, see `docs/`. Ping one of the documentation experts/reviewers + +#### Finishing development + Review + +- [ ] **Keep it in the scope** Try to focus on the actual scope and avoid a scope creep during review and keep new things to new issues. +- [ ] **Performance** Have you checked performance? For example do the same thing with 500 comments instead of 1. Document the tests and possible findings in the MR so a reviewer can directly see it. +- [ ] Have you tested with a variety of our [supported browsers](../../install/requirements.md#supported-web-browsers)? You can use [browserstack](https://www.browserstack.com/) to be able to access a wide variety of browsers and operating systems. +- [ ] Did you check the mobile view? +- [ ] Check the built webpack bundle (For the report run `WEBPACK_REPORT=true gdk run`, then open `webpack-report/index.html`) if we have unnecessary bloat due to wrong references, including libraries multiple times, etc.. If you need help contact the webpack [domain expert](https://about.gitlab.com/handbook/frontend/#frontend-domain-experts) +- [ ] **Tests** Not only greenfield tests - Test also all bad cases that come to your mind. +- [ ] If you have multiple MR's then also smoke test against the final merge. +- [ ] Are there any big changes on how and especially how frequently we use the API then let production know about it +- [ ] Smoke test of the RC on dev., staging., canary deployments and .com +- [ ] Follow up on issues that came out of the review. Create isssues for discovered edge cases that should be covered in future iterations. + +--- + +### Share your work early +1. Before writing code, ensure your vision of the architecture is aligned with +GitLab's architecture. +1. Add a diagram to the issue and ask a frontend architect in the slack channel `#fe_architectural` about it. + +  + +1. Don't take more than one week between starting work on a feature and +sharing a Merge Request with a reviewer or a maintainer. + +### Vue features +1. Follow the steps in [Vue.js Best Practices](vue.md) +1. Follow the style guide. +1. Only a handful of people are allowed to merge Vue related features. +Reach out to one of Vue experts early in this process. diff --git a/doc/development/fe_guide/icons.md b/doc/development/fe_guide/icons.md index b288ee95722..b469a9c6aef 100644 --- a/doc/development/fe_guide/icons.md +++ b/doc/development/fe_guide/icons.md @@ -49,7 +49,7 @@ Please use the following function inside JS to render an icon : All Icons and Illustrations are managed in the [gitlab-svgs](https://gitlab.com/gitlab-org/gitlab-svgs) repository which is added as a dev-dependency. -To upgrade to a new SVG Sprite version run `yarn upgrade @gitlab-org/gitlab-svgs` and then run `yarn run svg`. This task will copy the svg sprite and all illustrations in the correct folders. The updated files should be tracked in Git as those are referenced. +To upgrade to a new SVG Sprite version run `yarn upgrade @gitlab-org/gitlab-svgs`. # SVG Illustrations diff --git a/doc/development/fe_guide/index.md b/doc/development/fe_guide/index.md index 73084d667d4..5a67414e835 100644 --- a/doc/development/fe_guide/index.md +++ b/doc/development/fe_guide/index.md @@ -5,11 +5,15 @@ across GitLab's frontend team. ## Overview -GitLab is built on top of [Ruby on Rails][rails] using [Haml][haml] with -[Hamlit][hamlit]. Be wary of [the limitations that come with using -Hamlit][hamlit-limits]. We also use [SCSS][scss] and plain JavaScript with -modern ECMAScript standards supported through [Babel][babel] and ES module -support through [webpack][webpack]. +GitLab is built on top of [Ruby on Rails][rails] using [Haml][haml] and also a JavaScript based Frontend with [Vue.js][vue]. +Be wary of [the limitations that come with using Hamlit][hamlit-limits]. We also use [SCSS][scss] and plain JavaScript with +modern ECMAScript standards supported through [Babel][babel] and ES module support through [webpack][webpack]. + +### Javascript development + +[Vue.js][vue] is used for particularly advanced, dynamic elements and based on previous iterations [jQuery][jquery] is used in lot of places through the application's JavaScript. + +We also use [Axios][axios] to handle all of our network requests. We also utilize [webpack][webpack] to handle the bundling, minification, and compression of our assets. @@ -18,66 +22,32 @@ Working with our frontend assets requires Node (v6.0 or greater) and Yarn (v1.2 or greater). You can find information on how to install these on our [installation guide][install]. -[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]. --- -## Development Process - -### Share your work early -1. Before writing code guarantee your vision of the architecture is aligned with -GitLab's architecture. -1. Add a diagram to the issue and ask a Frontend Architecture about it. - -  - -1. Don't take more than one week between starting work on a feature and -sharing a Merge Request with a reviewer or a maintainer. - -### Vue features -1. Follow the steps in [Vue.js Best Practices](vue.md) -1. Follow the style guide. -1. Only a handful of people are allowed to merge Vue related features. -Reach out to one of Vue experts early in this process. - - ---- +## [Development Process](development_process.md) +How we plan and execute the work on the frontend. ## [Architecture](architecture.md) How we go about making fundamental design decisions in GitLab's frontend team or make changes to our frontend development guidelines. ---- - ## [Testing](../testing_guide/frontend_testing.md) - How we write frontend tests, run the GitLab test suite, and debug test related issues. ---- - ## [Design Patterns](design_patterns.md) Common JavaScript design patterns in GitLab's codebase. ---- - ## [Vue.js Best Practices](vue.md) Vue specific design patterns and practices. ---- - ## [Vuex](vuex.md) Vuex specific design patterns and practices. ---- - ## [Axios](axios.md) Axios specific practices and gotchas. diff --git a/doc/development/fe_guide/style_guide_js.md b/doc/development/fe_guide/style_guide_js.md index 7b5fa6ca42f..04dfe418dbe 100644 --- a/doc/development/fe_guide/style_guide_js.md +++ b/doc/development/fe_guide/style_guide_js.md @@ -236,7 +236,7 @@ export class Foo { } ``` -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. +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 outside of the constructor. 1. Prefer `.map`, `.reduce` or `.filter` over `.forEach` A forEach will most likely cause side effects, it will be mutating the array being iterated. Prefer using `.map`, @@ -310,7 +310,7 @@ Please check this [rules][eslint-plugin-vue-rules] for more documentation. })); ``` -1. Don not use a singleton for the service or the store +1. Do not use a singleton for the service or the store ```javascript // bad class Store { @@ -328,9 +328,11 @@ Please check this [rules][eslint-plugin-vue-rules] for more documentation. } } ``` +1. Use `.vue` for Vue templates. Do not use `%template` in HAML. #### Naming -1. **Extensions**: Use `.vue` extension for Vue components. + +1. **Extensions**: Use `.vue` extension for Vue components. Do not use `.js` as file extension ([#34371]). 1. **Reference Naming**: Use PascalCase for their instances: ```javascript // bad @@ -364,6 +366,8 @@ Please check this [rules][eslint-plugin-vue-rules] for more documentation. <component my-prop="prop" /> ``` +[#34371]: https://gitlab.com/gitlab-org/gitlab-ce/issues/34371 + #### Alignment 1. Follow these alignment styles for the template method: 1. With more than one attribute, all attributes should be on a new line: diff --git a/doc/development/fe_guide/vue.md b/doc/development/fe_guide/vue.md index 3b68fd858cc..62c3a05eb3b 100644 --- a/doc/development/fe_guide/vue.md +++ b/doc/development/fe_guide/vue.md @@ -440,7 +440,6 @@ need to test the rendered output. [Vue][vue-test] guide's to unit test show us e Refer to [mock axios](axios.md#mock-axios-response-on-tests) - [vue-docs]: http://vuejs.org/guide/index.html [issue-boards]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/app/assets/javascripts/boards [environments-table]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/app/assets/javascripts/environments diff --git a/doc/development/fe_guide/vuex.md b/doc/development/fe_guide/vuex.md index 7298ffcd54a..d0d74afe7bb 100644 --- a/doc/development/fe_guide/vuex.md +++ b/doc/development/fe_guide/vuex.md @@ -1,5 +1,5 @@ # Vuex -To manage the state of an application you may use [Vuex][vuex-docs]. +To manage the state of an application you should use [Vuex][vuex-docs]. _Note:_ All of the below is explained in more detail in the official [Vuex documentation][vuex-docs]. @@ -115,8 +115,8 @@ create: 1. An action `requestSomething`, to toggle the loading state 1. An action `receiveSomethingSuccess`, to handle the success callback 1. An action `receiveSomethingError`, to handle the error callback -1. An action `fetchSomething` to make the request. - 1. In case your application does more than a `GET` request you can use these as examples: +1. An action `fetchSomething` to make the request. + 1. In case your application does more than a `GET` request you can use these as examples: 1. `PUT`: `createSomething` 2. `POST`: `updateSomething` 3. `DELETE`: `deleteSomething` diff --git a/doc/development/file_storage.md b/doc/development/file_storage.md index 34a02bd2c3c..fdbd7f1fa37 100644 --- a/doc/development/file_storage.md +++ b/doc/development/file_storage.md @@ -84,7 +84,7 @@ The `RecordsUploads::Concern` concern will create an `Upload` entry for every fi By including the `ObjectStorage::Concern` in the `GitlabUploader` derived class, you may enable the object storage for this uploader. To enable the object storage in your uploader, you need to either 1) include `RecordsUpload::Concern` and prepend `ObjectStorage::Extension::RecordsUploads` or 2) mount the uploader and create a new field named `<mount>_store`. -The `CarrierWave::Uploader#store_dir` is overriden to +The `CarrierWave::Uploader#store_dir` is overridden to - `GitlabUploader.base_dir` + `GitlabUploader.dynamic_segment` when the store is LOCAL - `GitlabUploader.dynamic_segment` when the store is REMOTE (the bucket name is used to namespace) diff --git a/doc/development/gitaly.md b/doc/development/gitaly.md index 26abf967dcf..4f9ca1920a5 100644 --- a/doc/development/gitaly.md +++ b/doc/development/gitaly.md @@ -7,6 +7,67 @@ be replaced by Gitaly API calls. Visit the [Gitaly Migration Board](https://gitlab.com/gitlab-org/gitaly/boards/331341) for current status of the migration. +## Developing new Git features + +Starting with Gitlab 10.8, all new Git features should be developed in +Gitaly. + +> This is a new process that is not clearly defined yet. If you want +to contribute a Git feature and you're getting stuck, reach out to the +Gitaly team or `@jacobvosmaer-gitlab`. + +By 'new feature' we mean any method or class in `lib/gitlab/git` that is +called from outside `lib/gitlab/git`. For new methods that are called +from inside `lib/gitlab/git`, see 'Modifying existing Git features' +below. + +There should be no new code that touches Git repositories via +disk access (e.g. Rugged, `git`, `rm -rf`) anywhere outside +`lib/gitlab/git`. + +The process for adding new Gitaly features is: + +- exploration / prototyping +- design and create a new Gitaly RPC [in gitaly-proto](https://gitlab.com/gitlab-org/gitaly-proto) +- release a new version of gitaly-proto +- write implementation and tests for the RPC [in Gitaly](https://gitlab.com/gitlab-org/gitaly), in Go or Ruby +- release a new version of Gitaly +- write client code in gitlab-ce/ee, gitlab-workhorse or gitlab-shell that calls the new Gitaly RPC + +These steps often overlap. It is possible to use an unreleased version +of Gitaly and gitaly-proto during testing and development. + +- See the [Gitaly repo](https://gitlab.com/gitlab-org/gitaly/blob/master/CONTRIBUTING.md#development-and-testing-with-a-custom-gitaly-proto) for instructions on writing server side code with an unreleased protocol. +- See [below](#running-tests-with-a-locally-modified-version-of-gitaly) for instructions on running gitlab-ce tests with a modified version of Gitaly. +- In GDK run `gdk install` and restart `gdk run` (or `gdk run app`) to use a locally modified Gitaly version for development + +### Gitaly-ruby + +It is possible to implement and test RPC's in Gitaly using Ruby code, +in +[gitaly-ruby](https://gitlab.com/gitlab-org/gitaly/tree/master/ruby). +This should make it easier to contribute for developers who are less +comfortable writing Go code. + +There is documentation for this approach in [the Gitaly +repo](https://gitlab.com/gitlab-org/gitaly/blob/master/doc/ruby_endpoint.md). + +## Modifying existing Git features + +If you modify existing Git features in `lib/gitlab/git` you need to make +sure the changes also work in Gitaly. Because we are still in the +migration process there are a number of subtle pitfalls. Features that +have been migrated have dual implementations (Gitaly and local). The +Gitaly implementation may or may not use a vendored (and therefore +possibly outdated) copy of the local implementation in `lib/gitlab/git`. + +To avoid unexpected problems and conflicts, all changes to +`lib/gitlab/git` need to be approved by a member of the Gitaly team. + +For the time being, while the Gitaly migration is still in progress, +there should be no Enterprise Edition-only Git code in +`lib/gitlab/git`. Also no mixins. + ## Feature Flags Gitaly makes heavy use of [feature flags](feature_flags.md). @@ -99,10 +160,14 @@ 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. +Normally, gitlab-ce/ee tests use a local clone of Gitaly in +`tmp/tests/gitaly` pinned at the version specified in +`GITALY_SERVER_VERSION`. The `GITALY_SERVER_VERSION` file supports +`=my-branch` syntax to use a custom branch in gitlab-org/gitaly. If +you want to run tests locally against a modified version of Gitaly you +can replace `tmp/tests/gitaly` with a symlink. This is much faster +because the `=my-branch` syntax forces a Gitaly re-install each time +you run `rspec`. ```shell rm -rf tmp/tests/gitaly diff --git a/doc/development/i18n/externalization.md b/doc/development/i18n/externalization.md index 856ef882453..0edcb23c7c5 100644 --- a/doc/development/i18n/externalization.md +++ b/doc/development/i18n/externalization.md @@ -131,6 +131,9 @@ There is also and alternative method to [translate messages from validation erro ### Interpolation +Placeholders in translated text should match the code style of the respective source file. +For example use `%{created_at}` in Ruby but `%{createdAt}` in JavaScript. + - In Ruby/HAML: ```ruby @@ -141,11 +144,19 @@ There is also and alternative method to [translate messages from validation erro ```js import { __, sprintf } from '~/locale'; - sprintf(__('Hello %{username}'), { username: 'Joe' }) => 'Hello Joe' + + sprintf(__('Hello %{username}'), { username: 'Joe' }); // => 'Hello Joe' ``` -The placeholders should match the code style of the respective source file. -For example use `%{created_at}` in Ruby but `%{createdAt}` in JavaScript. + By default, `sprintf` escapes the placeholder values. + If you want to take care of that yourself, you can pass `false` as third argument. + + ```js + import { __, sprintf } from '~/locale'; + + sprintf(__('This is %{value}'), { value: '<strong>bold</strong>' }); // => 'This is <strong>bold</strong>' + sprintf(__('This is %{value}'), { value: '<strong>bold</strong>' }, false); // => 'This is <strong>bold</strong>' + ``` ### Plurals @@ -259,7 +270,7 @@ 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 +These changes can be discarded, the language files will be updated by Crowdin automatically. Discard all of them at once like this: diff --git a/doc/development/i18n/proofreader.md b/doc/development/i18n/proofreader.md index cf62314bc29..5185d843ccb 100644 --- a/doc/development/i18n/proofreader.md +++ b/doc/development/i18n/proofreader.md @@ -23,6 +23,7 @@ are very appreciative of the work done by translators and proofreaders! - Italian - Paolo Falomo - [GitLab](https://gitlab.com/paolofalomo), [Crowdin](https://crowdin.com/profile/paolo.falomo) - Japanese + - Yamana Tokiuji - [GitLab](https://gitlab.com/tokiuji), [Crowdin](https://crowdin.com/profile/yamana) - Korean - Chang-Ho Cha - [GitLab](https://gitlab.com/changho-cha), [Crowdin](https://crowdin.com/profile/zzazang) - Huang Tao - [GitLab](https://gitlab.com/htve), [Crowdin](https://crowdin.com/profile/htve) diff --git a/doc/development/img/state-model-issue.png b/doc/development/img/state-model-issue.png Binary files differdeleted file mode 100644 index ee33b6886c6..00000000000 --- a/doc/development/img/state-model-issue.png +++ /dev/null diff --git a/doc/development/img/state-model-legend.png b/doc/development/img/state-model-legend.png Binary files differdeleted file mode 100644 index 1c121f2588c..00000000000 --- a/doc/development/img/state-model-legend.png +++ /dev/null diff --git a/doc/development/img/state-model-merge-request.png b/doc/development/img/state-model-merge-request.png Binary files differdeleted file mode 100644 index e00da10cac2..00000000000 --- a/doc/development/img/state-model-merge-request.png +++ /dev/null diff --git a/doc/development/merge_request_performance_guidelines.md b/doc/development/merge_request_performance_guidelines.md index 2b4126b43ef..12badbe39b2 100644 --- a/doc/development/merge_request_performance_guidelines.md +++ b/doc/development/merge_request_performance_guidelines.md @@ -162,7 +162,7 @@ need for running complex operations to fetch the data. You should use Redis if data should be cached for a certain time period instead of the duration of the transaction. -For example, say you process multiple snippets of text containiner username +For example, say you process multiple snippets of text containing username mentions (e.g. `Hello @alice` and `How are you doing @alice?`). By caching the user objects for every username we can remove the need for running the same query for every mention of `@alice`. diff --git a/doc/development/new_fe_guide/development/components.md b/doc/development/new_fe_guide/development/components.md index 637099d1e83..899efb398cd 100644 --- a/doc/development/new_fe_guide/development/components.md +++ b/doc/development/new_fe_guide/development/components.md @@ -1,3 +1,21 @@ # Components -> TODO: Add content +## Graphs + +We have a lot of graphing libraries in our codebase to render graphs. In an effort to improve maintainability, new graphs should use [D3.js](https://d3js.org/). If a new graph is fairly simple, consider implementing it in SVGs or HTML5 canvas. + +We chose D3 as our library going forward because of the following features: + +* [Tree shaking webpack capabilities.](https://github.com/d3/d3/blob/master/CHANGES.md#changes-in-d3-40) +* [Compatible with vue.js as well as vanilla javascript.](https://github.com/d3/d3/blob/master/CHANGES.md#changes-in-d3-40) + +D3 is very popular across many projects outside of GitLab: + +* [The New York Times](https://archive.nytimes.com/www.nytimes.com/interactive/2012/02/13/us/politics/2013-budget-proposal-graphic.html) +* [plot.ly](https://plot.ly/) +* [Droptask](https://www.droptask.com/) + +Within GitLab, D3 has been used for the following notable features + +* [Prometheus graphs](https://docs.gitlab.com/ee/user/project/integrations/prometheus.html) +* Contribution calendars diff --git a/doc/development/object_state_models.md b/doc/development/object_state_models.md deleted file mode 100644 index 623bbf143ef..00000000000 --- a/doc/development/object_state_models.md +++ /dev/null @@ -1,25 +0,0 @@ -# Object state models - -## Diagrams - -[GitLab object state models](https://drive.google.com/drive/u/3/folders/0B5tDlHAM4iZINmpvYlJXcDVqMGc) - ---- - -## Legend - - - ---- - -## Issue - -[`app/models/issue.rb`](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/app/models/issue.rb) - - ---- - -## Merge request - -[`app/models/merge_request.rb`](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/app/models/merge_request.rb) -
\ No newline at end of file diff --git a/doc/development/ordering_table_columns.md b/doc/development/ordering_table_columns.md index 249e70c7b0e..5d00e1f7a0c 100644 --- a/doc/development/ordering_table_columns.md +++ b/doc/development/ordering_table_columns.md @@ -30,7 +30,7 @@ example) at the end. ## Type Sizes -While the PostgreSQL docuemntation +While the PostgreSQL documentation (https://www.postgresql.org/docs/current/static/datatype.html) contains plenty of information we will list the sizes of common types here so it's easier to look them up. Here "word" refers to the word size, which is 4 bytes for a 32 diff --git a/doc/development/testing_guide/best_practices.md b/doc/development/testing_guide/best_practices.md index df80cd9f584..7b32e0a47e1 100644 --- a/doc/development/testing_guide/best_practices.md +++ b/doc/development/testing_guide/best_practices.md @@ -63,6 +63,8 @@ writing one](testing_levels.md#consider-not-writing-a-system-test)! Sometimes you may need to debug Capybara tests by observing browser behavior. +#### Live debug + You can pause Capybara and view the website on the browser by using the `live_debug` method in your spec. The current page will be automatically opened in your default browser. @@ -90,6 +92,54 @@ Finished in 34.51 seconds (files took 0.76702 seconds to load) Note: `live_debug` only works on javascript enabled specs. +#### Run `:js` spec in a visible browser + +Run the spec with `CHROME_HEADLESS=0`, e.g.: + +``` +CHROME_HEADLESS=0 bundle exec rspec some_spec.rb +``` + +The test will go by quickly, but this will give you an idea of what's happening. + +You can also add `byebug` or `binding.pry` to pause execution and step through +the test. + +#### Screenshots + +We use the `capybara-screenshot` gem to automatically take a screenshot on +failure. In CI you can download these files as job artifacts. + +Also, you can manually take screenshots at any point in a test by adding the +methods below. Be sure to remove them when they are no longer needed! See +https://github.com/mattheworiordan/capybara-screenshot#manual-screenshots for +more. + +Add `screenshot_and_save_page` in a `:js` spec to screenshot what Capybara +"sees", and save the page source. + +Add `screenshot_and_open_image` in a `:js` spec to screenshot what Capybara +"sees", and automatically open the image. + +### Fast unit tests + +Some classes are well-isolated from Rails and you should be able to test them +without the overhead added by the Rails environment and Bundler's `:default` +group's gem loading. In these cases, you can `require 'fast_spec_helper'` +instead of `require 'spec_helper'` in your test file, and your test should run +really fast since: + +- Gems loading is skipped +- Rails app boot is skipped +- gitlab-shell and Gitaly setup are skipped +- Test repositories setup are skipped + +Note that in some cases, you might have to add some `require_dependency 'foo'` +in your file under test since Rails autoloading is not available in these cases. + +This shouldn't be a problem since explicitely listing dependencies should be +considered a good practice anyway. + ### `let` variables GitLab's RSpec suite has made extensive use of `let` variables to reduce @@ -281,14 +331,13 @@ All fixtures should be be placed under `spec/fixtures/`. RSpec config files are files that change the RSpec config (i.e. `RSpec.configure do |config|` blocks). They should be placed under -`spec/support/config/`. +`spec/support/`. Each file should be related to a specific domain, e.g. -`spec/support/config/capybara.rb`, `spec/support/config/carrierwave.rb`, etc. +`spec/support/capybara.rb`, `spec/support/carrierwave.rb`, etc. -Helpers can be included in the `spec/support/config/rspec.rb` file. If a -helpers module applies only to a certain kind of specs, it should add modifiers -to the `config.include` call. For instance if +If a helpers module applies only to a certain kind of specs, it should add +modifiers to the `config.include` call. For instance if `spec/support/helpers/cycle_analytics_helpers.rb` applies to `:lib` and `type: :model` specs only, you would write the following: @@ -299,6 +348,14 @@ RSpec.configure do |config| end ``` +If a config file only consists of `config.include`, you can add these +`config.include` directly in `spec/spec_helper.rb`. + +For very generic helpers, consider including them in the `spec/support/rspec.rb` +file which is used by the `spec/fast_spec_helper.rb` file. See +[Fast unit tests](#fast-unit-tests) for more details about the +`spec/fast_spec_helper.rb` file. + --- [Return to Testing documentation](index.md) diff --git a/doc/development/testing_guide/end_to_end_tests.md b/doc/development/testing_guide/end_to_end_tests.md index d10a797a142..21ec926414d 100644 --- a/doc/development/testing_guide/end_to_end_tests.md +++ b/doc/development/testing_guide/end_to_end_tests.md @@ -67,9 +67,9 @@ 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. +You can ask question in the `#quality` 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 diff --git a/doc/development/testing_guide/frontend_testing.md b/doc/development/testing_guide/frontend_testing.md index 0c63f51cb45..0d0d511582b 100644 --- a/doc/development/testing_guide/frontend_testing.md +++ b/doc/development/testing_guide/frontend_testing.md @@ -62,6 +62,7 @@ describe('.methodName', () => { }); }); ``` + #### Testing promises When testing Promises you should always make sure that the test is asynchronous and rejections are handled. @@ -69,9 +70,9 @@ Your Promise chain should therefore end with a call of the `done` callback and ` ```javascript // Good -it('tests a promise', (done) => { +it('tests a promise', done => { promise - .then((data) => { + .then(data => { expect(data).toBe(asExpected); }) .then(done) @@ -79,10 +80,10 @@ it('tests a promise', (done) => { }); // Good -it('tests a promise rejection', (done) => { +it('tests a promise rejection', done => { promise .then(done.fail) - .catch((error) => { + .catch(error => { expect(error).toBe(expectedError); }) .then(done) @@ -91,48 +92,85 @@ it('tests a promise rejection', (done) => { // Bad (missing done callback) it('tests a promise', () => { - promise - .then((data) => { - expect(data).toBe(asExpected); - }) + promise.then(data => { + expect(data).toBe(asExpected); + }); }); // Bad (missing catch) -it('tests a promise', (done) => { +it('tests a promise', done => { promise - .then((data) => { + .then(data => { expect(data).toBe(asExpected); }) - .then(done) + .then(done); }); // Bad (use done.fail in asynchronous tests) -it('tests a promise', (done) => { +it('tests a promise', done => { promise - .then((data) => { + .then(data => { expect(data).toBe(asExpected); }) .then(done) - .catch(fail) + .catch(fail); }); // Bad (missing catch) -it('tests a promise rejection', (done) => { +it('tests a promise rejection', done => { promise - .catch((error) => { + .catch(error => { expect(error).toBe(expectedError); }) - .then(done) + .then(done); }); ``` -#### Stubbing +#### Stubbing and Mocking + +Jasmine provides useful helpers `spyOn`, `spyOnProperty`, `jasmine.createSpy`, +and `jasmine.createSpyObject` to facilitate replacing methods with dummy +placeholders, and recalling when they are called and the arguments that are +passed to them. These tools should be used liberally, to test for expected +behavior, to mock responses, and to block unwanted side effects (such as a +method that would generate a network request or alter `window.location`). The +documentation for these methods can be found in the [jasmine introduction page](https://jasmine.github.io/2.0/introduction.html#section-Spies). + +Sometimes you may need to spy on a method that is directly imported by another +module. GitLab has a custom `spyOnDependency` method which utilizes +[babel-plugin-rewire](https://github.com/speedskater/babel-plugin-rewire) to +achieve this. It can be used like so: + +```javascript +// my_module.js +import { visitUrl } from '~/lib/utils/url_utility'; + +export default function doSomething() { + visitUrl('/foo/bar'); +} -For unit tests, you should stub methods that are unrelated to the current unit you are testing. -If you need to use a prototype method, instantiate an instance of the class and call it there instead of mocking the instance completely. +// my_module_spec.js +import doSomething from '~/my_module'; -For integration tests, you should stub methods that will effect the stability of the test if they -execute their original behaviour. i.e. Network requests. +describe('my_module', () => { + it('does something', () => { + const visitUrl = spyOnDependency(doSomething, 'visitUrl'); + + doSomething(); + expect(visitUrl).toHaveBeenCalledWith('/foo/bar'); + }); +}); +``` + +Unlike `spyOn`, `spyOnDependency` expects its first parameter to be the default +export of a module who's import you want to stub, rather than an object which +contains a method you wish to stub (if the module does not have a default +export, one is be generated by the babel plugin). The second parameter is the +name of the import you wish to change. The result of the function is a Spy +object which can be treated like any other jasmine spy object. + +Further documentation on the babel rewire pluign API can be found on +[its repository Readme doc](https://github.com/speedskater/babel-plugin-rewire#babel-plugin-rewire). ### Vue.js unit tests @@ -143,8 +181,8 @@ See this [section][vue-test]. `rake karma` runs the frontend-only (JavaScript) tests. It consists of two subtasks: -- `rake karma:fixtures` (re-)generates fixtures -- `rake karma:tests` actually executes the tests +* `rake karma:fixtures` (re-)generates fixtures +* `rake karma:tests` actually executes the tests As long as the fixtures don't change, `rake karma:tests` (or `yarn karma`) is sufficient (and saves you some time). @@ -152,19 +190,41 @@ is sufficient (and saves you some time). ### Live testing and focused testing While developing locally, it may be helpful to keep karma running so that you -can get instant feedback on as you write tests and modify code. To do this -you can start karma with `npm run karma-start`. It will compile the javascript +can get instant feedback on as you write tests and modify code. To do this +you can start karma with `yarn run karma-start`. It will compile the javascript assets and run a server at `http://localhost:9876/` where it will automatically -run the tests on any browser which connects to it. You can enter that url on +run the tests on any browser which connects to it. You can enter that url on multiple browsers at once to have it run the tests on each in parallel. While karma is running, any changes you make will instantly trigger a recompile and retest of the entire test suite, so you can see instantly if you've broken -a test with your changes. You can use [jasmine focused][jasmine-focus] or +a test with your changes. You can use [jasmine focused][jasmine-focus] or excluded tests (with `fdescribe` or `xdescribe`) to get karma to run only the tests you want while you're working on a specific feature, but make sure to remove these directives when you commit your code. +It is also possible to only run karma on specific folders or files by filtering +the run tests via the argument `--filter-spec` or short `-f`: + +```bash +# Run all files +yarn karma-start +# Run specific spec files +yarn karma-start --filter-spec profile/account/components/update_username_spec.js +# Run specific spec folder +yarn karma-start --filter-spec profile/account/components/ +# Run all specs which path contain vue_shared or vie +yarn karma-start -f vue_shared -f vue_mr_widget +``` + +You can also use glob syntax to match files. Remember to put quotes around the +glob otherwise your shell may split it into multiple arguments: + +```bash +# Run all specs named `file_spec` within the IDE subdirectory +yarn karma -f 'spec/javascripts/ide/**/file_spec.js' +``` + ## RSpec feature integration tests Information on setting up and running RSpec integration tests with @@ -176,19 +236,19 @@ Information on setting up and running RSpec integration tests with Similar errors will be thrown if you're using JavaScript features not yet supported by the PhantomJS test runner which is used for both Karma and RSpec -tests. We polyfill some JavaScript objects for older browsers, but some +tests. We polyfill some JavaScript objects for older browsers, but some features are still unavailable: -- Array.from -- Array.first -- Async functions -- Generators -- Array destructuring -- For..Of -- Symbol/Symbol.iterator -- Spread +* Array.from +* Array.first +* Async functions +* Generators +* Array destructuring +* For..Of +* Symbol/Symbol.iterator +* Spread -Until these are polyfilled appropriately, they should not be used. Please +Until these are polyfilled appropriately, they should not be used. Please update this list with additional unsupported features. ### RSpec errors due to JavaScript @@ -223,7 +283,7 @@ end ### Spinach errors due to missing JavaScript NOTE: **Note:** Since we are discouraging the use of Spinach when writing new -feature tests, you shouldn't ever need to use this. This information is kept +feature tests, you shouldn't ever need to use this. This information is kept available for legacy purposes only. In Spinach, the JavaScript driver is enabled differently. In the `*.feature` @@ -243,11 +303,11 @@ Scenario: Developer can approve merge request [jasmine-focus]: https://jasmine.github.io/2.5/focused_specs.html [jasmine-jquery]: https://github.com/velesin/jasmine-jquery [karma]: http://karma-runner.github.io/ -[vue-test]:https://docs.gitlab.com/ce/development/fe_guide/vue.html#testing-vue-components -[RSpec]: https://github.com/rspec/rspec-rails#feature-specs -[Capybara]: https://github.com/teamcapybara/capybara -[Karma]: http://karma-runner.github.io/ -[Jasmine]: https://jasmine.github.io/ +[vue-test]: https://docs.gitlab.com/ce/development/fe_guide/vue.html#testing-vue-components +[rspec]: https://github.com/rspec/rspec-rails#feature-specs +[capybara]: https://github.com/teamcapybara/capybara +[karma]: http://karma-runner.github.io/ +[jasmine]: https://jasmine.github.io/ --- diff --git a/doc/development/testing_guide/testing_levels.md b/doc/development/testing_guide/testing_levels.md index e86c1f5232a..51794f7f4df 100644 --- a/doc/development/testing_guide/testing_levels.md +++ b/doc/development/testing_guide/testing_levels.md @@ -28,7 +28,7 @@ records should use stubs/doubles as much as possible. | `app/uploaders/` | `spec/uploaders/` | RSpec | | | `app/views/` | `spec/views/` | RSpec | | | `app/workers/` | `spec/workers/` | RSpec | | -| `app/assets/javascripts/` | `spec/javascripts/` | Karma | More details in the [Frontent Testing guide](frontend_testing.md) section. | +| `app/assets/javascripts/` | `spec/javascripts/` | Karma | More details in the [Frontend Testing guide](frontend_testing.md) section. | ## Integration tests diff --git a/doc/development/testing_guide/testing_rake_tasks.md b/doc/development/testing_guide/testing_rake_tasks.md index 60163f1a230..db8ca87e9f8 100644 --- a/doc/development/testing_guide/testing_rake_tasks.md +++ b/doc/development/testing_guide/testing_rake_tasks.md @@ -9,7 +9,7 @@ At a minimum, requiring the Rake helper will redirect `stdout`, include the runtime task helpers, and include the `RakeHelpers` Spec support module. The `RakeHelpers` module exposes a `run_rake_task(<task>)` method to make -executing tasks simple. See `spec/support/rake_helpers.rb` for all available +executing tasks simple. See `spec/support/helpers/rake_helpers.rb` for all available methods. Example: diff --git a/doc/development/ux_guide/components.md b/doc/development/ux_guide/components.md index 012c64be79f..b57520a00e0 100644 --- a/doc/development/ux_guide/components.md +++ b/doc/development/ux_guide/components.md @@ -219,7 +219,7 @@ Blocks are a way to group related information. #### Content blocks -Content blocks (`.content-block`) are the basic grouping of content. They are commonly used in [lists](#lists), and are separated by a botton border. +Content blocks (`.content-block`) are the basic grouping of content. They are commonly used in [lists](#lists), and are separated by a button border.  @@ -281,7 +281,7 @@ Modals are only used for having a conversation and confirmation with the user. T | Modal with 2 actions | Modal with 3 actions | Special confirmation | | --------------------- | --------------------- | -------------------- | -|  |  |  | +|  |  |  | > TODO: Special case for modal. diff --git a/doc/development/what_requires_downtime.md b/doc/development/what_requires_downtime.md index 9d0c62ecc35..b8be8daa157 100644 --- a/doc/development/what_requires_downtime.md +++ b/doc/development/what_requires_downtime.md @@ -255,7 +255,7 @@ otherwise it will raise a `TypeError`. ## Adding Indexes Adding indexes is an expensive process that blocks INSERT and UPDATE queries for -the duration. When using PostgreSQL one can work arounds this by using the +the duration. When using PostgreSQL one can work around this by using the `CONCURRENTLY` option: ```sql diff --git a/doc/development/writing_documentation.md b/doc/development/writing_documentation.md index d6a13e7483a..9bca4637830 100644 --- a/doc/development/writing_documentation.md +++ b/doc/development/writing_documentation.md @@ -49,7 +49,7 @@ do before. **Use cases**: provide at least two, ideally three, use cases for every major feature. You should answer this question: what can you do with this feature/change? Use cases -are examples of how this feauture or change can be used in real life. +are examples of how this feature or change can be used in real life. Examples: - CE and EE: [Issues](../user/project/issues/index.md#use-cases) |
