diff options
Diffstat (limited to 'doc/development')
22 files changed, 91 insertions, 58 deletions
diff --git a/doc/development/README.md b/doc/development/README.md index 6f197ed4099..01dff0c2017 100644 --- a/doc/development/README.md +++ b/doc/development/README.md @@ -9,8 +9,20 @@ description: 'Learn how to contribute to GitLab.' - Set up GitLab's development environment with [GitLab Development Kit (GDK)](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/master/doc/howto/README.md) - [GitLab contributing guide](contributing/index.md) - - [Issues workflow](contributing/issue_workflow.md) (issue tracker guidelines, triaging, labels, feature proposals, issue weight, regression issues, technical and UX debt) - - [Merge requests workflow](contributing/merge_request_workflow.md) (merge request guidelines, contribution acceptance criteria, definition of done, dependencies) + - [Issues workflow](contributing/issue_workflow.md). For information on: + - Issue tracker guidelines. + - Triaging. + - Labels. + - Feature proposals. + - Issue weight. + - Regression issues. + - Technical or UX debt. + - [Merge requests workflow](contributing/merge_request_workflow.md). For + information on: + - Merge request guidelines. + - Contribution acceptance criteria. + - Definition of done. + - Dependencies. - [Style guides](contributing/style_guides.md) - [Implement design & UI elements](contributing/design.md) - [GitLab Architecture Overview](architecture.md) diff --git a/doc/development/architecture.md b/doc/development/architecture.md index c5ac8c040f8..5a1b53bc2fb 100644 --- a/doc/development/architecture.md +++ b/doc/development/architecture.md @@ -288,7 +288,7 @@ GitLab CI is the open-source continuous integration service included with GitLab - Configuration: [Omnibus][grafana-omnibus], [Charts][grafana-charts] - Layer: Monitoring -Grafana is an open source, feature rich metrics dashboard and graph editor for Graphite, Elasticsearch, OpenTSDB, Prometheus and InfluxDB. +Grafana is an open source, feature rich metrics dashboard and graph editor for Graphite, Elasticsearch, OpenTSDB, Prometheus, and InfluxDB. #### Jaeger @@ -321,7 +321,7 @@ Mattermost is an open source, private cloud, Slack-alternative from <https://mat - Configuration: [Omnibus][minio-omnibus], [Charts][minio-charts], [GDK][minio-gdk] - Layer: Core Service (Data) -MinIO is an object storage server released under Apache License v2.0. It is compatible with Amazon S3 cloud storage service. It is best suited for storing unstructured data such as photos, videos, log files, backups and container / VM images. Size of an object can range from a few KBs to a maximum of 5TB. +MinIO is an object storage server released under Apache License v2.0. It is compatible with Amazon S3 cloud storage service. It is best suited for storing unstructured data such as photos, videos, log files, backups, and container / VM images. Size of an object can range from a few KBs to a maximum of 5TB. #### NGINX diff --git a/doc/development/code_review.md b/doc/development/code_review.md index d5394e30d6a..7b00e3cea0d 100644 --- a/doc/development/code_review.md +++ b/doc/development/code_review.md @@ -17,7 +17,7 @@ uncovered edge cases. The reviewer can be from a different team, but it is recommended to pick someone who knows the domain well. You can read more about the importance of involving reviewer(s) in the section on the responsibility of the author below. -If you need some guidance (e.g. it's your first merge request), feel free to ask +If you need some guidance (for example, it's your first merge request), feel free to ask one of the [Merge request coaches](https://about.gitlab.com/company/team/). If you need assistance with security scans or comments, feel free to include the @@ -148,7 +148,7 @@ architecture, code organization, separation of concerns, tests, DRYness, consistency, and readability. Since a maintainer's job only depends on their knowledge of the overall GitLab -codebase, and not that of any specific domain, they can review, approve and merge +codebase, and not that of any specific domain, they can review, approve, and merge merge requests from any team and in any product area. In fact, authors are encouraged to get their merge requests merged by maintainers @@ -334,7 +334,7 @@ reviewee. reviewer before doing it, but have the courage to do it when you believe it is important. - In the interest of [Iteration](https://about.gitlab.com/handbook/values/#iteration), - if, as a reviewer, your suggestions are non-blocking changes or personal preference + if your review suggestions are non-blocking changes, or personal preference (not a documented or agreed requirement), consider approving the merge request before passing it back to the author. This allows them to implement your suggestions if they agree, or allows them to pass it onto the diff --git a/doc/development/contributing/design.md b/doc/development/contributing/design.md index 8426db84aa4..352392931c0 100644 --- a/doc/development/contributing/design.md +++ b/doc/development/contributing/design.md @@ -9,7 +9,11 @@ To better understand the priority by which UX tackles issues, see the [UX sectio Once an issue has been worked on and is ready for development, a UXer removes the ~"UX" label and applies the ~"UX ready" label to that issue. -There is a special type label called ~"product discovery". It represents a discovery issue intended for UX, PM, FE, and BE to discuss the problem and potential solutions. The final output for this issue could be a doc of requirements, a design artifact, or even a prototype. The solution will be developed in a subsequent milestone. +There is a special type label called ~"product discovery" intended for UX, +PM, FE, and BE. It represents a discovery issue to discuss the problem and +potential solutions. The final output for this issue could be a doc of +requirements, a design artifact, or even a prototype. The solution will be +developed in a subsequent milestone. ~"product discovery" issues are like any other issue and should contain a milestone label, ~"Deliverable" or ~"Stretch", when scheduled in the current milestone. @@ -17,7 +21,7 @@ The initial issue should be about the problem we are solving. If a separate [pro is needed for additional research and design work, it will be created by a PM or UX person. Assign the ~UX, ~"product discovery" and ~"Deliverable" labels, add a milestone and use a title that makes it clear that the scheduled issue is product discovery -(e.g. `Product discovery for XYZ`). +(for example, `Product discovery for XYZ`). In order to complete a product discovery issue in a release, you must complete the following: diff --git a/doc/development/database_review.md b/doc/development/database_review.md index 113314884d5..77e5060720b 100644 --- a/doc/development/database_review.md +++ b/doc/development/database_review.md @@ -12,7 +12,7 @@ A database review is required for: including files in: - `db/` - `lib/gitlab/background_migration/` -- Changes to the database tooling, e.g.: +- Changes to the database tooling. For example: - migration or ActiveRecord helpers in `lib/gitlab/database/` - load balancing - Changes that produce SQL queries that are beyond the obvious. It is @@ -50,7 +50,7 @@ A database **reviewer**'s role is to: Currently we have a [critical shortage of database maintainers](https://gitlab.com/gitlab-org/gitlab/issues/29717). Until we are able to increase the number of database maintainers to support the volume of reviews, we have implemented this temporary solution. If the database **reviewer** cannot find an available database **maintainer** then: 1. Assign the MR for a second review by a **database trainee maintainer** for further review. -1. Once satisfied with the review process, and if the database **maintainer** is still not available, skip the database maintainer approval step and assign the merge request to a backend maintainer for final review and approval. +1. Once satisfied with the review process and if the database **maintainer** is still not available, skip the database maintainer approval step and assign the merge request to a backend maintainer for final review and approval. A database **maintainer**'s role is to: @@ -119,10 +119,10 @@ the following preparations into account. - Add foreign keys to any columns pointing to data in other tables, including [an index](migration_style_guide.md#adding-foreign-key-constraints). - Add indexes for fields that are used in statements such as `WHERE`, `ORDER BY`, `GROUP BY`, and `JOIN`s. -#### Preparation when removing columns, tables, indexes or other structures +#### Preparation when removing columns, tables, indexes, or other structures - Follow the [guidelines on dropping columns](what_requires_downtime.md#dropping-columns). -- Generally it's best practice, but not a hard rule, to remove indexes and foreign keys in a post-deployment migration. +- Generally it's best practice (but not a hard rule) to remove indexes and foreign keys in a post-deployment migration. - Exceptions include removing indexes and foreign keys for small tables. ### How to review for database @@ -156,14 +156,14 @@ the following preparations into account. - Check migrations are reversible and implement a `#down` method - Check data migrations: - Establish a time estimate for execution on GitLab.com. - - Depending on timing, data migrations can be placed on regular, post-deploy or background migrations. + - Depending on timing, data migrations can be placed on regular, post-deploy, or background migrations. - Data migrations should be reversible too or come with a description of how to reverse, when possible. This applies to all types of migrations (regular, post-deploy, background). - Query performance - Check for any obviously complex queries and queries the author specifically points out for review (if any) - If not present yet, ask the author to provide SQL queries and query plans - (e.g. by using [chatops](understanding_explain_plans.md#chatops) or direct + (for example, by using [chatops](understanding_explain_plans.md#chatops) or direct database access) - For given queries, review parameters regarding data distribution - [Check query plans](understanding_explain_plans.md) and suggest improvements diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md index 68495178511..4fcdd8a1fb0 100644 --- a/doc/development/documentation/index.md +++ b/doc/development/documentation/index.md @@ -16,7 +16,7 @@ In addition to this page, the following resources can help you craft and contrib ## Source files and rendered web locations -Documentation for GitLab, GitLab Runner, Omnibus GitLab and Charts is published to <https://docs.gitlab.com>. Documentation for GitLab is also published within the application at `/help` on the domain of the GitLab instance. +Documentation for GitLab, GitLab Runner, Omnibus GitLab, and Charts is published to <https://docs.gitlab.com>. Documentation for GitLab is also published within the application at `/help` on the domain of the GitLab instance. At `/help`, only help for your current edition and version is included. Help for other versions is available at <https://docs.gitlab.com/archives/>. The source of the documentation exists within the codebase of each GitLab application in the following repository locations: diff --git a/doc/development/documentation/site_architecture/index.md b/doc/development/documentation/site_architecture/index.md index 232bca30e0f..c91a9882bb0 100644 --- a/doc/development/documentation/site_architecture/index.md +++ b/doc/development/documentation/site_architecture/index.md @@ -107,7 +107,7 @@ The pipeline in the `gitlab-docs` project: ### Rebuild the docs site Docker images -Once a week, on Mondays, a scheduled pipeline runs and rebuilds the Docker images +Once a week on Mondays, a scheduled pipeline runs and rebuilds the Docker images used in various pipeline jobs, like `docs-lint`. The Docker image configuration files are located at <https://gitlab.com/gitlab-org/gitlab-docs/-/tree/master/dockerfiles>. @@ -230,7 +230,7 @@ for its search function. This is how it works: NOTE: **For GitLab employees:** The credentials to access the Algolia dashboard are stored in 1Password. If you want to receive weekly reports of the search usage, search the Google doc with -title "Email, Slack, and GitLab Groups and Aliases", search for `docsearch`, +title `Email, Slack, and GitLab Groups and Aliases`, search for `docsearch`, and add a comment with your email to be added to the alias that gets the weekly reports. diff --git a/doc/development/documentation/styleguide.md b/doc/development/documentation/styleguide.md index b456887bd08..f769560d67f 100644 --- a/doc/development/documentation/styleguide.md +++ b/doc/development/documentation/styleguide.md @@ -17,14 +17,12 @@ that apply to all GitLab content, not just documentation. ### Why a single source of truth -The documentation is the SSOT for all information related to the implementation, usage, and troubleshooting of GitLab products and features. It evolves continually, in keeping with new products and features, and with improvements for clarity, accuracy, and completeness. +The documentation of GitLab products and features is the SSOT for all information related to implementation, usage, and troubleshooting. It evolves continually, in keeping with new products and features, and with improvements for clarity, accuracy, and completeness. This policy prevents information silos, ensuring that it remains easy to find information about GitLab products. It also informs decisions about the kinds of content we include in our documentation. -The documentation is a continually evolving SSOT for all information related to the implementation, usage, and troubleshooting of GitLab products and features. - ### All information Include problem-solving actions that may address rare cases or be considered 'risky', so long as proper context is provided in the form of fully detailed warnings and caveats. This kind of content should be included as it could be helpful to others and, when properly explained, its benefits outweigh the risks. If you think you have found an exception to this rule, contact the Technical Writing team. @@ -34,7 +32,7 @@ For the Troubleshooting sections, people in GitLab Support can merge additions t ### All media types -Include any media types/sources if the content is relevant to readers. You can freely include or link presentations, diagrams, videos, etc.; no matter who it was originally composed for, if it is helpful to any of our audiences, we can include it. +Include any media types/sources if the content is relevant to readers. You can freely include or link presentations, diagrams, videos, and so on; no matter who it was originally composed for, if it is helpful to any of our audiences, we can include it. - If you use an image that has a separate source file (for example, a vector or diagram format), link the image to the source file so that it may be reused or updated by anyone. - Do not copy and paste content from other sources unless it is a limited quotation with the source cited. Typically it is better to either rephrase relevant information in your own words or link out to the other source. @@ -63,13 +61,17 @@ Instead, link to the SSOT and explain why it is important to consume the informa ### Organize by topic, not by type -Beyond top-level audience-type folders (e.g. `administration`), we organize content by topic, not by type, so that it can be located as easily as possible within the single-source-of-truth (SSOT) section for the subject matter. +Beyond top-level audience-type folders (for example, `administration`), we organize content by topic, not by type, so that it can be located as easily as possible within the single-source-of-truth (SSOT) section for the subject matter. + +For example, do not create groupings of similar media types. For example: -For example, do not create groupings of similar media types (e.g. glossaries, FAQs, or sets of all articles or videos). +- Glossaries. +- FAQs. +- Sets of all articles or videos. Such grouping of content by type makes it difficult to browse for the information you need and difficult to maintain up-to-date content. -Instead, organize content by its subject (e.g. everything related to CI goes together) +Instead, organize content by its subject (for example, everything related to CI goes together) and cross-link between any related content. ### Docs-first methodology @@ -79,7 +81,10 @@ We employ a **docs-first methodology** to help ensure that the docs remain a com - If the answer to a question exists in documentation, share the link to the docs instead of rephrasing the information. - When you encounter new information not available in GitLab’s documentation (for example, when working on a support case or testing a feature), your first step should be to create a merge request (MR) to add this information to the docs. You can then share the MR in order to communicate this information. -New information that would be useful toward the future usage or troubleshooting of GitLab should not be written directly in a forum or other messaging system, but added to a docs MR and then referenced, as described above. Note that among any other doc changes, you can always add a Troubleshooting section to a doc if none exists, or un-comment and use the placeholder Troubleshooting section included as part of our [doc template](structure.md#template-for-new-docs), if present. +New information that would be useful toward the future usage or troubleshooting of GitLab should not be written directly in a forum or other messaging system, but added to a docs MR and then referenced, as described above. Note that among any other doc changes, you can either: + +- Add a Troubleshooting section to a doc if none exists. +- Un-comment and use the placeholder Troubleshooting section included as part of our [doc template](structure.md#template-for-new-docs), if present. The more we reflexively add useful information to the docs, the more (and more successfully) the docs will be used to efficiently accomplish tasks and solve problems. @@ -98,7 +103,7 @@ Ruby gem will support all [GFM markup](../../user/markdown.md) in the future. Th all markup that is supported for display in the GitLab application itself. For now, use regular Markdown markup, following the rules in the linked style guide. -Note that Kramdown-specific markup (e.g., `{:.class}`) will not render properly on GitLab instances under [`/help`](index.md#gitlab-help). +Note that Kramdown-specific markup (for example, `{:.class}`) will not render properly on GitLab instances under [`/help`](index.md#gitlab-help). Hard-coded HTML is valid, although it's discouraged to be used while we have `/help`. HTML is permitted as long as: @@ -1149,7 +1154,7 @@ keyword "only": - For GitLab Premium: `**(PREMIUM ONLY)**`. - For GitLab Ultimate: `**(ULTIMATE ONLY)**`. -For GitLab.com only tiers (when the feature is not available for self-hosted instances): +For GitLab.com only tiers (when the feature is not available for self-managed instances): - For GitLab Free and higher tiers: `**(FREE ONLY)**`. - For GitLab Bronze and higher tiers: `**(BRONZE ONLY)**`. diff --git a/doc/development/documentation/workflow.md b/doc/development/documentation/workflow.md index 7c97f6628c9..1b8d2ee434a 100644 --- a/doc/development/documentation/workflow.md +++ b/doc/development/documentation/workflow.md @@ -118,7 +118,7 @@ Reviewers help ensure: Prior to merging, documentation changes committed by the developer must be reviewed by: - The code reviewer for the merge request. This is known as a technical review. -- Optionally, others involved in the work, such as other developers or the Product Manager. +- Optionally, others involved in the work such as other developers or the Product Manager. - The Technical Writer for the DevOps stage group, except in exceptional circumstances where a [post-merge review](#post-merge-reviews) can be requested. - A maintainer of the project. @@ -137,11 +137,11 @@ For issues requiring any new or updated documentation, the Product Manager must: - Confirm or add the [documentation requirements](#documentation-requirements). - Ensure the issue contains: - Any new or updated feature name. - - Overview, description, and use cases, as required by the - [documentation structure and template](structure.md), when applicable. + - Overview, description, and use cases when applicable (as required by the + [documentation structure and template](structure.md)). -Everyone is encouraged to draft the documentation requirements in the issue, but a Product Manager -will do the following: +Everyone is encouraged to draft the documentation requirements in the issue. However, a Product +Manager will: - When the issue is assigned a release milestone, review and update the Documentation details. - By the kickoff, finalize the documentation details. @@ -238,7 +238,7 @@ The following details should be included: - What concepts and procedures should the documentation guide and enable the user to understand or accomplish? - To this end, what new page(s) are needed, if any? What pages or subsections need updates? - Consider user, admin, and API documentation changes and additions. + Consider changes and additions to user, admin, and API documentation. - For any guide or instruction set, should it help address a single use case, or be flexible to address a certain range of use cases? - Do we need to update a previously recommended workflow? Should we link the new feature from diff --git a/doc/development/event_tracking/index.md b/doc/development/event_tracking/index.md index 10e99e845d6..8c00930a781 100644 --- a/doc/development/event_tracking/index.md +++ b/doc/development/event_tracking/index.md @@ -13,7 +13,7 @@ As developers, we should attempt to add tracking and instrumentation where possi - Usage patterns. - Other metrics that can potentially be improved on. -To maintain consistency, and not adversely effect performance, we have some basic tracking functionality exposed at both the frontend and backend layers that can be utilized while building new features or updating existing features. +To maintain consistency and not adversely effect performance, we have some basic tracking functionality exposed at both the frontend and backend layers that can be utilized while building new features or updating existing features. We also encourage users to enable tracking, and we embrace full transparency with our tracking approach so it can be easily understood and trusted. By enabling tracking, users can: diff --git a/doc/development/fe_guide/development_process.md b/doc/development/fe_guide/development_process.md index 5b02098f020..64bc01c181c 100644 --- a/doc/development/fe_guide/development_process.md +++ b/doc/development/fe_guide/development_process.md @@ -71,7 +71,7 @@ With the purpose of being [respectful of others' time](https://about.gitlab.com/ - includes tests - includes a changelog entry (when necessary) - Before assigning to a maintainer, assign to a reviewer. -- If you assigned a merge request, or pinged someone directly, keep in mind that we work in different timezones and asynchronously, so be patient. Unless the merge request is urgent (like fixing a broken master), please don't DM or reassign the merge request before waiting for a 24-hour window. +- If you assigned a merge request or pinged someone directly, be patient because we work in different timezones and asynchronously. Unless the merge request is urgent (like fixing a broken master), please don't DM or reassign the merge request before waiting for a 24-hour window. - If you have a question regarding your merge request/issue, make it on the merge request/issue. When we DM each other, we no longer have a SSOT and [no one else is able to contribute](https://about.gitlab.com/handbook/values/#public-by-default). - When you have a big WIP merge request with many changes, you're advised to get the review started before adding/removing significant code. Make sure it is assigned well before the release cut-off, as the reviewer(s)/maintainer(s) would always prioritize reviewing finished MRs before WIP ones. - Make sure to remove the WIP title before the last round of review. diff --git a/doc/development/fe_guide/graphql.md b/doc/development/fe_guide/graphql.md index a9821edff0b..d21c937bfe4 100644 --- a/doc/development/fe_guide/graphql.md +++ b/doc/development/fe_guide/graphql.md @@ -53,7 +53,7 @@ fragment DesignListItem on Design { } ``` -Fragments can be stored in separate files, imported and used in queries, mutations or other fragments. +Fragments can be stored in separate files, imported and used in queries, mutations, or other fragments. ```javascript #import "./designList.fragment.graphql" diff --git a/doc/development/fe_guide/vuex.md b/doc/development/fe_guide/vuex.md index 0bb9e3b7d50..cd18091abdf 100644 --- a/doc/development/fe_guide/vuex.md +++ b/doc/development/fe_guide/vuex.md @@ -6,7 +6,7 @@ _Note:_ All of the below is explained in more detail in the official [Vuex docum ## Separation of concerns -Vuex is composed of State, Getters, Mutations, Actions and Modules. +Vuex is composed of State, Getters, Mutations, Actions, and Modules. When a user clicks on an action, we need to `dispatch` it. This action will `commit` a mutation that will change the state. _Note:_ The action itself will not update the state, only a mutation should update the state. diff --git a/doc/development/feature_flags/process.md b/doc/development/feature_flags/process.md index 4b44c8dadca..0cca4117f1f 100644 --- a/doc/development/feature_flags/process.md +++ b/doc/development/feature_flags/process.md @@ -53,7 +53,7 @@ absolutely no way to use the feature until it is enabled. ### Including a feature behind feature flag in the final release -In order to build a final release and present the feature for self-hosted +In order to build a final release and present the feature for self-managed users, the feature flag should be at least defaulted to **on**. If the feature is deemed stable and there is confidence that removing the feature flag is safe, consider removing the feature flag altogether. @@ -126,8 +126,11 @@ need to revert a release, and because feature flags are disabled by default we don't need to revert and pick any Git commits. In fact, all we have to do is disable the feature, and in the worst case, perform cleanup. Let's say that the cost of this is 2. In this case, our best case cost is 11: 10 to build the -feature, and 1 to add the feature flag. The worst case cost is now 13: 10 to -build the feature, 1 to add the feature flag, and 2 to disable and clean up. +feature, and 1 to add the feature flag. The worst case cost is now 13: + +- 10 to build the feature. +- 1 to add the feature flag. +- 2 to disable and clean up. Here we can see that in the best case scenario the work necessary is only a tiny bit more compared to not using a feature flag. Meanwhile, the process of diff --git a/doc/development/new_fe_guide/development/accessibility.md b/doc/development/new_fe_guide/development/accessibility.md index ae5c4c6a6cc..7a15e9eb6be 100644 --- a/doc/development/new_fe_guide/development/accessibility.md +++ b/doc/development/new_fe_guide/development/accessibility.md @@ -4,7 +4,7 @@ Using semantic HTML plays a key role when it comes to accessibility. ## Accessible Rich Internet Applications - ARIA -WAI-ARIA, the Accessible Rich Internet Applications specification, defines a way to make Web content and Web applications more accessible to people with disabilities. +WAI-ARIA (the Accessible Rich Internet Applications specification) defines a way to make Web content and Web applications more accessible to people with disabilities. > Note: It is [recommended][using-aria] to use semantic elements as the primary method to achieve accessibility rather than adding aria attributes. Adding aria attributes should be seen as a secondary method for creating accessible elements. diff --git a/doc/development/new_fe_guide/index.md b/doc/development/new_fe_guide/index.md index 152ddcdae64..9e9c367807f 100644 --- a/doc/development/new_fe_guide/index.md +++ b/doc/development/new_fe_guide/index.md @@ -1,7 +1,7 @@ # Frontend Development Guidelines This guide contains all the information to successfully contribute to GitLab's frontend. -This is a living document, and we welcome contributions, feedback and suggestions. +This is a living document, and we welcome contributions, feedback, and suggestions. ## [Development](development/index.md) diff --git a/doc/development/packages.md b/doc/development/packages.md index 487d1243c97..848693d368a 100644 --- a/doc/development/packages.md +++ b/doc/development/packages.md @@ -75,8 +75,8 @@ that gives a way to identify the project that the package belongs to. This gener id or full project path in the package name. See [Conan's naming convention](../user/packages/conan_repository/index.md#package-recipe-naming-convention) as an example. -For group and project-level endpoints, naming can be less constrained, and it will be up to the group and project -members to be certain that there is no conflict between two package names, however the system should prevent +For group and project-level endpoints, naming can be less constrained and it will be up to the group and project +members to be certain that there is no conflict between two package names. However, the system should prevent a user from reusing an existing name within a given scope. Otherwise, naming should follow the package manager's naming conventions and include a validation in the `package.md` diff --git a/doc/development/performance.md b/doc/development/performance.md index 1b3c4aedf1f..5697f41c3dc 100644 --- a/doc/development/performance.md +++ b/doc/development/performance.md @@ -259,10 +259,10 @@ One of the reasons of the increased memory footprint could be Ruby memory fragme To diagnose it, you can visualize Ruby heap as described in [this post by Aaron Patterson](https://tenderlovemaking.com/2017/09/27/visualizing-your-ruby-heap.html). -To start, you want to dump the heap of the process you're investigating to a JSON file. +To start, you want to dump the heap of the process you're investigating to a JSON file. -You need to run the command inside the process you're exploring, you may do that with `rbtrace`. -`rbtrace` is already present in GitLab `Gemfile`, you just need to require it. +You need to run the command inside the process you're exploring, you may do that with `rbtrace`. +`rbtrace` is already present in GitLab `Gemfile`, you just need to require it. It could be achieved running webserver or Sidekiq with the environment variable set to `ENABLE_RBTRACE=1`. To get the heap dump: @@ -281,7 +281,7 @@ Fragmented Ruby heap snapshot could look like this: ![Ruby heap fragmentation](img/memory_ruby_heap_fragmentation.png) -Memory fragmentation could be reduced by tuning GC parameters as described in [this post by Nate Berkopec](https://www.speedshop.co/2017/12/04/malloc-doubles-ruby-memory.html), which should be considered as a tradeoff, as it may affect overall performance of memory allocation and GC cycles. +Memory fragmentation could be reduced by tuning GC parameters as described in [this post by Nate Berkopec](https://www.speedshop.co/2017/12/04/malloc-doubles-ruby-memory.html). This should be considered as a tradeoff, as it may affect overall performance of memory allocation and GC cycles. ## Importance of Changes diff --git a/doc/development/redis.md b/doc/development/redis.md index a4a87155f5a..a8b7b84bb65 100644 --- a/doc/development/redis.md +++ b/doc/development/redis.md @@ -8,7 +8,7 @@ GitLab uses [Redis](https://redis.io) for three distinct purposes: Every application process is configured to use the same Redis servers, so they can be used for inter-process communication in cases where [PostgreSQL](sql.md) -is less appropriate, for example, transient state or data that is written much +is less appropriate. For example, transient state or data that is written much more often than it is read. If [Geo](geo.md) is enabled, each Geo node gets its own, independent Redis diff --git a/doc/development/sidekiq_style_guide.md b/doc/development/sidekiq_style_guide.md index 4445efa823a..e15daab0fdb 100644 --- a/doc/development/sidekiq_style_guide.md +++ b/doc/development/sidekiq_style_guide.md @@ -66,7 +66,7 @@ are not adjusted appropriately. ## Idempotent Jobs -It's known that a job can fail for multiple reasons, for example, network outages or bugs. +It's known that a job can fail for multiple reasons. For example, network outages or bugs. In order to address this, Sidekiq has a built-in retry mechanism that is used by default by most workers within GitLab. @@ -178,7 +178,7 @@ end ## Jobs with External Dependencies Most background jobs in the GitLab application communicate with other GitLab -services, eg Postgres, Redis, Gitaly and Object Storage. These are considered +services. For example, Postgres, Redis, Gitaly, and Object Storage. These are considered to be "internal" dependencies for a job. However, some jobs will be dependent on external services in order to complete @@ -388,7 +388,7 @@ requests. We do this to avoid incorrect metadata when other jobs are scheduled from the cron-worker. Cron-Workers themselves run instance wide, so they aren't scoped to -users, namespaces, projects or other resources that should be added to +users, namespaces, projects, or other resources that should be added to the context. However, they often schedule other jobs that _do_ require context. diff --git a/doc/development/testing_guide/end_to_end/quick_start_guide.md b/doc/development/testing_guide/end_to_end/quick_start_guide.md index be00129a2bc..5d5715df372 100644 --- a/doc/development/testing_guide/end_to_end/quick_start_guide.md +++ b/doc/development/testing_guide/end_to_end/quick_start_guide.md @@ -2,7 +2,12 @@ In this tutorial, you will find different examples, and the steps involved, in the creation of end-to-end (_e2e_) tests for GitLab CE and GitLab EE, using GitLab QA. -> When referring to end-to-end tests in this document, this means testing a specific feature end-to-end, such as a user logging in, the creation of a project, the management of labels, breaking down epics into sub-epics and issues, etc. +When referring to end-to-end tests in this document, this means testing a specific feature end-to-end such as: + +- A user logging in. +- The creation of a project. +- The management of labels. +- Breaking down epics into sub-epics and issues. ## Important information before we start writing tests @@ -209,7 +214,11 @@ First, we remove the duplication of strings by defining the global variables `@i Then, by creating a reusable `select_label_and_refresh` method, we remove the code duplication of this action, and later we can move this method to a Page Object class that will be created for easier maintenance purposes. -> Notice that the reusable method is created at the bottom of the file. The reason for that is that reading the code should be similar to reading a newspaper, where high-level information is at the top, like the title and summary of the news, while low level, or more specific information, is at the bottom (this helps readability). +Notice that the reusable method is created at the bottom of the file. This helps readability, +where reading the code should be similar to reading a newspaper: + +- High-level information is at the top, like the title and summary of the news. +- Low level, or more specific information, is at the bottom. ### 5. Tests' pre-conditions using resources and Page Objects @@ -353,7 +362,7 @@ You can think of [Resources] as anything that can be created on GitLab CE or EE, With that in mind, resources can be a project, an epic, an issue, a label, a commit, etc. -As you saw in the tests' pre-conditions and the optimization sections, we're already creating some of these resources, and we are doing that by calling the `fabricate_via_api!` method. +As you saw in the tests' pre-conditions and the optimization sections, we're already creating some of these resources. We are doing that by calling the `fabricate_via_api!` method. > We could be using the `fabricate!` method instead, which would use the `fabricate_via_api!` method if it exists, and fallback to GUI fabrication otherwise, but we recommend being explicit to make it clear what the test does. Also, we always recommend fabricating resources via API since this makes tests faster and more reliable. diff --git a/doc/development/testing_guide/testing_levels.md b/doc/development/testing_guide/testing_levels.md index f7dec82724f..58f00829b80 100644 --- a/doc/development/testing_guide/testing_levels.md +++ b/doc/development/testing_guide/testing_levels.md @@ -103,7 +103,7 @@ graph RL For complex Vuex mutations, you should separate the tests from other parts of the Vuex store to simplify problem-solving. #### When *not* to use unit tests - + - **Non-exported functions or classes**: Anything not exported from a module can be considered private or an implementation detail, and doesn't need to be tested. - **Constants**: @@ -200,7 +200,7 @@ graph RL - **All server requests**: Similar to unit tests, when running component tests, the backend may not be reachable, so all outgoing requests need to be mocked. - **Asynchronous background operations**: - Similar to unit tests, background operations cannot be stopped or waited on, so they will continue running in the following tests and cause side effects. + Similar to unit tests, background operations cannot be stopped or waited on. This means they will continue running in the following tests and cause side effects. - **Child components**: Every component is tested individually, so child components are mocked. See also [`shallowMount()`](https://vue-test-utils.vuejs.org/api/#shallowmount) |