diff options
Diffstat (limited to 'doc/development')
19 files changed, 145 insertions, 120 deletions
diff --git a/doc/development/automatic_ce_ee_merge.md b/doc/development/automatic_ce_ee_merge.md index fed772b9240..3ca841353e6 100644 --- a/doc/development/automatic_ce_ee_merge.md +++ b/doc/development/automatic_ce_ee_merge.md @@ -115,16 +115,16 @@ Now, every time you create an MR for CE and EE: 1. Continue cherry-picking: `git cherry-pick --continue` 1. Push to EE: `git push origin branch-example-ee` 1. Create the EE-equivalent MR and link to the CE MR from the -description "Ports [CE-MR-LINK] to EE" + description "Ports [CE-MR-LINK] to EE" 1. Once all the jobs are passing in both CE and EE, you've addressed the -feedback from your own team, and got them approved, the merge requests can be merged. + feedback from your own team, and got them approved, the merge requests can be merged. 1. When both MRs are ready, the EE merge request will be merged first, and the -CE-equivalent will be merged next. + CE-equivalent will be merged next. **Important notes:** - The commit SHA can be easily found from the GitLab UI. From a merge request, -open the tab **Commits** and click the copy icon to copy the commit SHA. + open the tab **Commits** and click the copy icon to copy the commit SHA. - To cherry-pick a **commit range**, such as [A > B > C > D] use: ```shell @@ -140,7 +140,7 @@ open the tab **Commits** and click the copy icon to copy the commit SHA. ``` - To cherry-pick a **merge commit**, use the flag `-m 1`. For example, suppose that the -merge commit SHA is `138f5e2f20289bb376caffa0303adb0cac859ce1`: + merge commit SHA is `138f5e2f20289bb376caffa0303adb0cac859ce1`: ```shell git cherry-pick -m 1 138f5e2f20289bb376caffa0303adb0cac859ce1 @@ -163,12 +163,12 @@ merge commit SHA is `138f5e2f20289bb376caffa0303adb0cac859ce1`: commits and you want to cherry-pick all but the merge commit. - If you push more commits to the CE branch, you can safely repeat the procedure -to cherry-pick them to the EE-equivalent branch. You can do that as many times as -necessary, using the same CE and EE branches. + to cherry-pick them to the EE-equivalent branch. You can do that as many times as + necessary, using the same CE and EE branches. - If you submitted the merge request to the CE repo and the `ee-compat-check` job passed, -you are not required to submit the EE-equivalent MR, but it's still recommended. If the -job failed, you are required to submit the EE MR so that you can fix the conflicts in EE -before merging your changes into CE. + you are not required to submit the EE-equivalent MR, but it's still recommended. If the + job failed, you are required to submit the EE MR so that you can fix the conflicts in EE + before merging your changes into CE. ## FAQ diff --git a/doc/development/contributing/issue_workflow.md b/doc/development/contributing/issue_workflow.md index c5344139ab4..4c53643ed9c 100644 --- a/doc/development/contributing/issue_workflow.md +++ b/doc/development/contributing/issue_workflow.md @@ -199,7 +199,7 @@ different way. We add the ~"Accepting merge requests" label to: - Low priority ~bug issues (i.e. we do not add it to the bugs that we want to -solve in the ~"Next Patch Release") + solve in the ~"Next Patch Release") - Small ~feature - Small ~"technical debt" issues @@ -300,17 +300,17 @@ below will make it easy to manage this, without unnecessary overhead. 1. Set weight for any issue at the earliest possible convenience 1. If you don't agree with a set weight, discuss with other developers until -consensus is reached about the weight + consensus is reached about the weight 1. Issue weights are an abstract measurement of complexity of the issue. Do not -relate issue weight directly to time. This is called [anchoring](https://en.wikipedia.org/wiki/Anchoring) -and something you want to avoid. + relate issue weight directly to time. This is called [anchoring](https://en.wikipedia.org/wiki/Anchoring) + and something you want to avoid. 1. Something that has a weight of 1 (or no weight) is really small and simple. -Something that is 9 is rewriting a large fundamental part of GitLab, -which might lead to many hard problems to solve. Changing some text in GitLab -is probably 1, adding a new Git Hook maybe 4 or 5, big features 7-9. + Something that is 9 is rewriting a large fundamental part of GitLab, + which might lead to many hard problems to solve. Changing some text in GitLab + is probably 1, adding a new Git Hook maybe 4 or 5, big features 7-9. 1. If something is very large, it should probably be split up in multiple -issues or chunks. You can simply not set the weight of a parent issue and set -weights to children issues. + issues or chunks. You can simply not set the weight of a parent issue and set + weights to children issues. ## Regression issues diff --git a/doc/development/documentation/feature-change-workflow.md b/doc/development/documentation/feature-change-workflow.md index eb479b85083..3f31fe5ca19 100644 --- a/doc/development/documentation/feature-change-workflow.md +++ b/doc/development/documentation/feature-change-workflow.md @@ -7,16 +7,16 @@ description: How to add docs for new or enhanced GitLab features. At GitLab, developers contribute new or updated documentation along with their code, but product managers and technical writers also have essential roles in the process. - **Developers**: Author/update documentation in the same MR as their code, and -merge it by the feature freeze for the assigned milestone. Request technical writer -assistance if needed. Other developers typically act as reviewers. + merge it by the feature freeze for the assigned milestone. Request technical writer + assistance if needed. Other developers typically act as reviewers. - **Product Managers** (PMs): In the issue for all new and enhanced features, -confirm the documentation requirements, plus the mentioned feature description -and use cases, which can be reused in docs. They can bring in a technical -writer for discussion or collaboration, and can be called upon themselves as a doc reviewer. + confirm the documentation requirements, plus the mentioned feature description + and use cases, which can be reused in docs. They can bring in a technical + writer for discussion or collaboration, and can be called upon themselves as a doc reviewer. - **Technical Writers**: Review doc requirements in issues, track issues and MRs -that contain docs changes, help with any questions throughout the authoring/editing process, -work on special projects related to the documentation, and review all new and updated -docs content, whether before or after it is merged. + that contain docs changes, help with any questions throughout the authoring/editing process, + work on special projects related to the documentation, and review all new and updated + docs content, whether before or after it is merged. Beyond this process, any member of the GitLab community can also author or request documentation improvements that are not associated with a new or changed feature. See the [Documentation improvement workflow](improvement-workflow.md). @@ -35,7 +35,7 @@ documentation updates if screenshots are now needed, or need to be updated. Documentation is not required when a feature is changed on the backend only and does not directly affect the way that any user or administrator would -interact with GitLab. +interact with GitLab. NOTE: **Note:** When revamping documentation, if unrelated to the feature change, this should be submitted @@ -80,7 +80,7 @@ must: - Add the `Documentation` label. - 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 per the [documentation structure and template](structure.md), when applicable. + and use cases, as required per the [documentation structure and template](structure.md), when applicable. Everyone is encouraged to draft the requirements in the issue, but a product manager will do the following: @@ -100,20 +100,20 @@ Follow the process below unless otherwise agreed with the product manager and te - Include any new and edited docs in the MR introducing the code. - Use the Documentation requirements confirmed by the Product Manager in the -issue and discuss any further doc plans or ideas as needed. - - If the new or changed doc requires extensive collaboration or conversation, a separate, -linked issue can be used for the planning process. - - We are trying to avoid using a separate MR, so that the docs stay with the code, but the -Technical Writing team is interested in discussing any potential exceptions that may be suggested. + issue and discuss any further doc plans or ideas as needed. + - If the new or changed doc requires extensive collaboration or conversation, a separate, + linked issue can be used for the planning process. + - We are trying to avoid using a separate MR, so that the docs stay with the code, but the + Technical Writing team is interested in discussing any potential exceptions that may be suggested. - Use the [Documentation guidelines](index.md), as well as other resources linked from there, -including the Documentation [Structure and template](structure.md) page, [Style Guide](styleguide.md), and [Markdown Guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/). + including the Documentation [Structure and template](structure.md) page, [Style Guide](styleguide.md), and [Markdown Guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/). - If you need any help to choose the correct place for a doc, discuss a documentation -idea or outline, or request any other help, ping the Technical Writer for the relevant -[DevOps stage](https://about.gitlab.com/handbook/product/categories/#devops-stages) -in your issue or MR, or write within `#docs` on the GitLab Slack. + idea or outline, or request any other help, ping the Technical Writer for the relevant + [DevOps stage](https://about.gitlab.com/handbook/product/categories/#devops-stages) + in your issue or MR, or write within `#docs` on the GitLab Slack. - The docs must be merged with the code **by the feature freeze date**, otherwise -the feature cannot be included with the release. A policy for documenting feature-flagged -issues is forthcoming and you are welcome to join the [discussion](https://gitlab.com/gitlab-org/gitlab-ce/issues/56813). + the feature cannot be included with the release. A policy for documenting feature-flagged + issues is forthcoming and you are welcome to join the [discussion](https://gitlab.com/gitlab-org/gitlab-ce/issues/56813). #### Reviews and merging @@ -124,35 +124,35 @@ All reviewers can help ensure accuracy, clarity, completeness, and adherence to 1. **The code reviewer** for the MR, to confirm accuracy, clarity, and completeness. 1. Optionally: Others involved in the work, such as other devs or the PM. 1. Optionally: The technical writer for the DevOps stage. If not prior to merging, the technical writer will review after the merge. -This helps us ensure that the developer has time to merge good content by the freeze, and that it can be further refined by the release, if needed. + This helps us ensure that the developer has time to merge good content by the freeze, and that it can be further refined by the release, if needed. - To decide whether to request this review before the merge, consider the amount of time left before the code freeze, the size of the change, -and your degree of confidence in having users of an RC use your docs as written. + and your degree of confidence in having users of an RC use your docs as written. - Pre-merge tech writer reviews should be most common when the code is complete well in advance of the freeze and/or for larger documentation changes. - You can request a review and if there is not sufficient time to complete it prior to the freeze, -the maintainer can merge the current doc changes (if complete) and create a follow-up doc review issue. + the maintainer can merge the current doc changes (if complete) and create a follow-up doc review issue. - The technical writer can also help decide what docs to merge before the freeze and whether to work on further changes in a follow up MR. - **To request a pre-merge technical writer review**, assign the writer listed for the applicable [DevOps stage](https://about.gitlab.com/handbook/product/categories/#devops-stages). - **To request a post-merge technical writer review**, [create an issue for one using the Doc Review template](https://gitlab.com/gitlab-org/gitlab-ce/issues/new?issuable_template=Doc%20Review) and link it from the MR that makes the doc change. 1. **The maintainer** who is assigned to merge the MR, to verify clarity, completeness, and quality, to the best of their ability. - Upon merging, if a technical writer review has not been performed and there is not yet a linked issue for a follow-up review, the maintainer should [create an issue using the Doc Review template](https://gitlab.com/gitlab-org/gitlab-ce/issues/new?issuable_template=Doc%20Review), link it from the MR, and -mention the original MR author in the new issue. Alternatively, the mainitainer can ask the MR author to create and link this issue before the MR is merged. + mention the original MR author in the new issue. Alternatively, the mainitainer can ask the MR author to create and link this issue before the MR is merged. - After merging, documentation changes are reviewed by: 1. The technical writer--**if** their review was not performed prior to the merge. 2. Optionally: by the PM (for accuracy and to ensure it's consistent with the vision for how the product will be used). -Any party can raise the item to the PM for review at any point: the dev, the technical writer, or the PM, who can request/plan a review at the outset. + Any party can raise the item to the PM for review at any point: the dev, the technical writer, or the PM, who can request/plan a review at the outset. ### Technical Writer role #### Planning - The technical writer monitors the documentation needs of issues assigned to the current and next milestone -for their DevOps stage(s), and participates in any needed discussion on docs planning and requirements refinement -with the dev, PM, and others. + for their DevOps stage(s), and participates in any needed discussion on docs planning and requirements refinement + with the dev, PM, and others. - The technical writer will review these requirements again upon the kickoff and provide feedback, as needed. -This is not a blocking review and developers should not wait to work on docs. + This is not a blocking review and developers should not wait to work on docs. #### Collaboration @@ -165,12 +165,12 @@ Additionally, technical writers are available for questions at any time. #### Review - Techncial writers provide non-blocking reviews of all documentation changes, -before or after the change is merged. However, if the docs are ready in the MR while -there's time before the freeze, the technical writer's review can commence early, on request. + before or after the change is merged. However, if the docs are ready in the MR while + there's time before the freeze, the technical writer's review can commence early, on request. - The technical writer will confirm that the doc is clear, grammatically correct, -and discoverable, while avoiding redundancy, bad file locations, typos, broken links, -etc. The technical writer will review the documentation for the following, which -the developer and code reviewer should have already made a good-faith effort to ensure: + and discoverable, while avoiding redundancy, bad file locations, typos, broken links, + etc. The technical writer will review the documentation for the following, which + the developer and code reviewer should have already made a good-faith effort to ensure: - Clarity. - Adherence to the plans and goals in the issue. - Location (make sure the docs are in the correct directorkes and has the correct name). diff --git a/doc/development/documentation/improvement-workflow.md b/doc/development/documentation/improvement-workflow.md index c97d8966b8c..a12c3d5ea7b 100644 --- a/doc/development/documentation/improvement-workflow.md +++ b/doc/development/documentation/improvement-workflow.md @@ -21,10 +21,10 @@ to accomplish their work with GitLab. ## How to update the docs 1. Click "Edit this Page" at the bottom of any page on docs.gitlab.com, or navigate to -one of the repositories and doc paths listed on the [GitLab Documentation guidelines](index.md) page. -Work in a fork if you do not have developer access to the GitLab project. + one of the repositories and doc paths listed on the [GitLab Documentation guidelines](index.md) page. + Work in a fork if you do not have developer access to the GitLab project. 1. Follow the described standards and processes listed on that Guidelines page, -including the linked resources: the [Structure and template](structure.md) page, [Style Guide](styleguide.md), and [Markdown Guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/). + including the linked resources: the [Structure and template](structure.md) page, [Style Guide](styleguide.md), and [Markdown Guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/). 1. Follow GitLab's [Merge Request Guidelines](../contributing/merge_request_workflow.md#merge-request-guidelines). If you need any help to choose the correct place for a doc, discuss a documentation @@ -45,7 +45,7 @@ before merging, mention the writer who is assigned to the relevant [DevOps stage The process can involve the following parties/phases, and is replicated in the `Documentation` MR template for GitLab CE and EE, to help with following the process. **1. Primary Reviewer** - Review by a [code reviewer](https://about.gitlab.com/handbook/engineering/projects/) or other appropriate colleague to confirm accuracy, clarity, and completeness. This can be skipped for minor fixes without substantive content changes. - + **2. Technical Writer** - Optional - If not requested for this MR, must be scheduled post-merge. To request a pre-merge review, assign the writer listed for the applicable [DevOps stage](https://about.gitlab.com/handbook/product/categories/#devops-stages). To request a post-merge review, [create an issue for one using the Doc Review template](https://gitlab.com/gitlab-org/gitlab-ce/issues/new?issuable_template=Doc%20Review) and link it from the MR that makes the doc change. diff --git a/doc/development/documentation/structure.md b/doc/development/documentation/structure.md index ee3bd5606a5..95b5fcd99a1 100644 --- a/doc/development/documentation/structure.md +++ b/doc/development/documentation/structure.md @@ -20,7 +20,7 @@ Every feature or use case document should include the following content in the f with exceptions and details noted below and in the template included on this page. - **Title**: Top-level heading with the feature name, or a use case name, which would start with -a verb, like Configuring, Enabling, etc. + a verb, like Configuring, Enabling, etc. - **Introduction**: A couple sentences about the subject matter and what's to be found on this page. - **Overview** Describe what it is, what it does, and in what context it should be used. - **Use cases**: describes real use case scenarios for that feature/configuration. @@ -95,7 +95,7 @@ Link each one to an appropriate place for more information. "Instructions" is usually not the name of the heading. This is the part of the document where you can include one or more sets of instructions, each to accomplish a specific task. Headers should describe the task the reader will achieve by following the instructions within, typically starting with a verb. -Larger instruction sets may have subsections covering specific phases of the process. +Larger instruction sets may have subsections covering specific phases of the process. - Write a step-by-step guide, with no gaps between the steps. - Start with an h2 (`##`), break complex steps into small steps using diff --git a/doc/development/fe_guide/development_process.md b/doc/development/fe_guide/development_process.md index 905668eef58..f3fdaa3b883 100644 --- a/doc/development/fe_guide/development_process.md +++ b/doc/development/fe_guide/development_process.md @@ -61,17 +61,19 @@ Please use your best judgement when to use it and please contribute new points t --- ### Share your work early + 1. Before writing code, ensure your vision of the architecture is aligned with -GitLab's architecture. + 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. + 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. + Reach out to one of Vue experts early in this process. diff --git a/doc/development/fe_guide/droplab/plugins/filter.md b/doc/development/fe_guide/droplab/plugins/filter.md index ddc6a3386c7..1f188c64fe4 100644 --- a/doc/development/fe_guide/droplab/plugins/filter.md +++ b/doc/development/fe_guide/droplab/plugins/filter.md @@ -9,7 +9,7 @@ Add the `Filter` object to the plugins array of a `DropLab.prototype.init` or `D - `Filter` requires a config value for `template`. - `template` should be the key of the objects within your data array that you want to compare -to the user input string, for filtering. + to the user input string, for filtering. ```html <input href="#" id="trigger" data-dropdown-trigger="#list"> diff --git a/doc/development/fe_guide/droplab/plugins/input_setter.md b/doc/development/fe_guide/droplab/plugins/input_setter.md index e229103e462..e4050213869 100644 --- a/doc/development/fe_guide/droplab/plugins/input_setter.md +++ b/doc/development/fe_guide/droplab/plugins/input_setter.md @@ -9,7 +9,7 @@ Add the `InputSetter` object to the plugins array of a `DropLab.prototype.init` - `InputSetter` requires a config value for `input` and `valueAttribute`. - `input` should be the DOM element that you want to manipulate. - `valueAttribute` should be a string that is the name of an attribute on your list items that is used to get the value -to update the `input` element with. + to update the `input` element with. You can also set the `InputSetter` config to an array of objects, which will allow you to update multiple elements. diff --git a/doc/development/fe_guide/performance.md b/doc/development/fe_guide/performance.md index 0aba38aca8c..2628e95dbc1 100644 --- a/doc/development/fe_guide/performance.md +++ b/doc/development/fe_guide/performance.md @@ -5,6 +5,7 @@ ### Realtime Components When writing code for realtime features we have to keep a couple of things in mind: + 1. Do not overload the server with requests. 1. It should feel realtime. @@ -12,16 +13,16 @@ Thus, we must strike a balance between sending requests and the feeling of realt Use the following rules when creating realtime solutions. 1. The server will tell you how much to poll by sending `Poll-Interval` in the header. -Use that as your polling interval. This way it is [easy for system administrators to change the -polling rate](../../administration/polling.md). -A `Poll-Interval: -1` means you should disable polling, and this must be implemented. + Use that as your polling interval. This way it is [easy for system administrators to change the + polling rate](../../administration/polling.md). + A `Poll-Interval: -1` means you should disable polling, and this must be implemented. 1. A response with HTTP status different from 2XX should disable polling as well. 1. Use a common library for polling. 1. Poll on active tabs only. Please use [Visibility](https://github.com/ai/visibilityjs). 1. Use regular polling intervals, do not use backoff polling, or jitter, as the interval will be -controlled by the server. + controlled by the server. 1. The backend code will most likely be using etags. You do not and should not check for status -`304 Not Modified`. The browser will transform it for you. + `304 Not Modified`. The browser will transform it for you. ### Lazy Loading Images diff --git a/doc/development/fe_guide/style_guide_js.md b/doc/development/fe_guide/style_guide_js.md index 1e0529262ad..060cd8baf7f 100644 --- a/doc/development/fe_guide/style_guide_js.md +++ b/doc/development/fe_guide/style_guide_js.md @@ -14,9 +14,9 @@ See [our current .eslintrc](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/ #### ESlint 1. **Never** disable eslint rules unless you have a good reason. -You may see a lot of legacy files with `/* eslint-disable some-rule, some-other-rule */` -at the top, but legacy files are a special case. Any time you develop a new feature or -refactor an existing one, you should abide by the eslint rules. + You may see a lot of legacy files with `/* eslint-disable some-rule, some-other-rule */` + at the top, but legacy files are a special case. Any time you develop a new feature or + refactor an existing one, you should abide by the eslint rules. 1. **Never Ever EVER** disable eslint globally for a file @@ -53,7 +53,7 @@ refactor an existing one, you should abide by the eslint rules. 1. [class-methods-use-this][eslint-this] 1. When they are needed _always_ place ESlint directive comment blocks on the first line of a script, -followed by any global declarations, then a blank newline prior to any imports or code. + followed by any global declarations, then a blank newline prior to any imports or code. ```javascript // bad @@ -125,8 +125,8 @@ followed by any global declarations, then a blank newline prior to any imports o ``` 1. Relative paths: when importing a module in the same directory, a child -directory, or an immediate parent directory prefer relative paths. When -importing a module which is two or more levels up, prefer either `~/` or `ee/`. + directory, or an immediate parent directory prefer relative paths. When + importing a module which is two or more levels up, prefer either `~/` or `ee/`. In **app/assets/javascripts/my-feature/subdir**: @@ -163,9 +163,9 @@ importing a module which is two or more levels up, prefer either `~/` or `ee/`. ``` 1. Avoid using IIFE. Although we have a lot of examples of files which wrap their -contents in IIFEs (immediately-invoked function expressions), -this is no longer necessary after the transition from Sprockets to webpack. -Do not use them anymore and feel free to remove them when refactoring legacy code. + contents in IIFEs (immediately-invoked function expressions), + this is no longer necessary after the transition from Sprockets to webpack. + Do not use them anymore and feel free to remove them when refactoring legacy code. 1. Avoid adding to the global namespace. ```javascript @@ -484,8 +484,8 @@ Please check this [rules][eslint-plugin-vue-rules] for more documentation. ``` 1. Default key should be provided if the prop is not required. -_Note:_ There are some scenarios where we need to check for the existence of the property. -On those a default key should not be provided. + _Note:_ There are some scenarios where we need to check for the existence of the property. + On those a default key should not be provided. ```javascript // good diff --git a/doc/development/fe_guide/vue.md b/doc/development/fe_guide/vue.md index 60f322c6e75..3cd70bd63fa 100644 --- a/doc/development/fe_guide/vue.md +++ b/doc/development/fe_guide/vue.md @@ -223,6 +223,7 @@ need to test the rendered output. [Vue][vue-test] guide's to unit test show us e ## Vue.js Expert Role One should apply to be a Vue.js expert by opening an MR when the Merge Request's they create and review show: + - Deep understanding of Vue and Vuex reactivy - Vue and Vuex code are structured according to both official and our guidelines - Full understanding of testing a Vue and Vuex application diff --git a/doc/development/logging.md b/doc/development/logging.md index 5c1d96b9e0c..d61441813b2 100644 --- a/doc/development/logging.md +++ b/doc/development/logging.md @@ -32,8 +32,8 @@ These logs suffer from a number of problems: 1. They often lack timestamps or other contextual information (e.g. project ID, user) 2. They may span multiple lines, which make them hard to find via Elasticsearch. 3. They lack a common structure, which make them hard to parse by log -forwarders, such as Logstash or Fluentd. This also makes them hard to -search. + forwarders, such as Logstash or Fluentd. This also makes them hard to + search. Note that currently on GitLab.com, any messages in `production.log` will NOT get indexed by Elasticsearch due to the sheer volume and noise. They @@ -61,12 +61,12 @@ importer. You want to log issues created, merge requests, etc. as the importer progresses. Here's what to do: 1. Look at [the list of GitLab Logs](../administration/logs.md) to see -if your log message might belong with one of the existing log files. + if your log message might belong with one of the existing log files. 1. If there isn't a good place, consider creating a new filename, but -check with a maintainer if it makes sense to do so. A log file should -make it easy for people to search pertinent logs in one place. For -example, `geo.log` contains all logs pertaining to GitLab Geo. -To create a new file: + check with a maintainer if it makes sense to do so. A log file should + make it easy for people to search pertinent logs in one place. For + example, `geo.log` contains all logs pertaining to GitLab Geo. + To create a new file: 1. Choose a filename (e.g. `importer_json.log`). 1. Create a new subclass of `Gitlab::JsonLogger`: @@ -130,15 +130,15 @@ To create a new file: ## Additional steps with new log files 1. Consider log retention settings. By default, Omnibus will rotate any -logs in `/var/log/gitlab/gitlab-rails/*.log` every hour and [keep at -most 30 compressed files](https://docs.gitlab.com/omnibus/settings/logs.html#logrotate). -On GitLab.com, that setting is only 6 compressed files. These settings should suffice -for most users, but you may need to tweak them in [omnibus-gitlab](https://gitlab.com/gitlab-org/omnibus-gitlab). + logs in `/var/log/gitlab/gitlab-rails/*.log` every hour and [keep at + most 30 compressed files](https://docs.gitlab.com/omnibus/settings/logs.html#logrotate). + On GitLab.com, that setting is only 6 compressed files. These settings should suffice + for most users, but you may need to tweak them in [omnibus-gitlab](https://gitlab.com/gitlab-org/omnibus-gitlab). 1. If you add a new file, submit an issue to the [production -tracker](https://gitlab.com/gitlab-com/gl-infra/production/issues) or -a merge request to the [gitlab_fluentd](https://gitlab.com/gitlab-cookbooks/gitlab_fluentd) -project. See [this example](https://gitlab.com/gitlab-cookbooks/gitlab_fluentd/merge_requests/51/diffs). + tracker](https://gitlab.com/gitlab-com/gl-infra/production/issues) or + a merge request to the [gitlab_fluentd](https://gitlab.com/gitlab-cookbooks/gitlab_fluentd) + project. See [this example](https://gitlab.com/gitlab-cookbooks/gitlab_fluentd/merge_requests/51/diffs). 1. Be sure to update the [GitLab CE/EE documentation](../administration/logs.md) and the [GitLab.com -runbooks](https://gitlab.com/gitlab-com/runbooks/blob/master/howto/logging.md). + runbooks](https://gitlab.com/gitlab-com/runbooks/blob/master/howto/logging.md). diff --git a/doc/development/new_fe_guide/development/accessibility.md b/doc/development/new_fe_guide/development/accessibility.md index 2a3a126ca5c..8420a504ec4 100644 --- a/doc/development/new_fe_guide/development/accessibility.md +++ b/doc/development/new_fe_guide/development/accessibility.md @@ -2,7 +2,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. @@ -15,6 +15,7 @@ Check the list of WAI-ARIA roles [here][roles] When using icons or images that aren't absolutely needed to understand the context, we should use `aria-hidden="true"`. On the other hand, if an icon is crucial to understand the context we should do one of the following: + 1. Use `aria-label` in the element with a meaningful description 1. Use `aria-labelledby` to point to an element that contains the explanation for that icon diff --git a/doc/development/new_fe_guide/style/html.md b/doc/development/new_fe_guide/style/html.md index 2d5b7d048ab..035fcbb28df 100644 --- a/doc/development/new_fe_guide/style/html.md +++ b/doc/development/new_fe_guide/style/html.md @@ -3,6 +3,7 @@ ## Buttons <a name="button-type"></a><a name="1.1"></a> + - [1.1](#button-type) **Use button type** Button tags requires a `type` attribute according to the [W3C HTML specification][button-type-spec]. ``` @@ -14,6 +15,7 @@ ``` <a name="button-role"></a><a name="1.2"></a> + - [1.2](#button-role) **Use button role for non buttons** If an HTML element has an onClick handler but is not a button, it should have `role="button"`. This is more [accessible][button-role-accessible]. ``` @@ -27,6 +29,7 @@ ## Links <a name="blank-links"></a><a name="2.1"></a> + - [2.1](#blank-links) **Use rel for target blank** Use `rel="noopener noreferrer"` whenever your links open in a new window i.e. `target="_blank"`. This prevents [the following][jitbit-target-blank] security vulnerability documented by JitBit ``` @@ -38,6 +41,7 @@ ``` <a name="fake-links"></a><a name="2.2"></a> + - [2.2](#fake-links) **Do not use fake links** Use a button tag if a link only invokes JavaScript click event handlers. This is more semantic. ``` diff --git a/doc/development/new_fe_guide/style/javascript.md b/doc/development/new_fe_guide/style/javascript.md index 922fd1e4ea4..7985b893c9e 100644 --- a/doc/development/new_fe_guide/style/javascript.md +++ b/doc/development/new_fe_guide/style/javascript.md @@ -10,6 +10,7 @@ You can run eslint locally by running `yarn eslint` ## Arrays <a name="avoid-foreach"></a><a name="1.1"></a> + - [1.1](#avoid-foreach) **Avoid ForEach when mutating data** Use `map`, `reduce` or `filter` instead of `forEach` when mutating data. This will minimize mutations in functions ([which is aligned with Airbnb's style guide][airbnb-minimize-mutations]) ``` @@ -17,7 +18,7 @@ You can run eslint locally by running `yarn eslint` users.forEach((user, index) => { user.id = index; }); - + // good const usersWithId = users.map((user, index) => { return Object.assign({}, user, { id: index }); @@ -27,6 +28,7 @@ You can run eslint locally by running `yarn eslint` ## Functions <a name="limit-params"></a><a name="2.1"></a> + - [2.1](#limit-params) **Limit number of parameters** If your function or method has more than 3 parameters, use an object as a parameter instead. ``` @@ -34,7 +36,7 @@ You can run eslint locally by running `yarn eslint` function a(p1, p2, p3) { // ... }; - + // good function a(p) { // ... @@ -44,6 +46,7 @@ You can run eslint locally by running `yarn eslint` ## Classes & constructors <a name="avoid-constructor-side-effects"></a><a name="3.1"></a> + - [3.1](#avoid-constructor-side-effects) **Avoid side effects in constructors** Avoid making some operations in the `constructor`, such as asynchronous calls, API requests and DOM manipulations. Prefer moving them into separate functions. This will make tests easier to write and code easier to maintain. ```javascript @@ -54,23 +57,24 @@ You can run eslint locally by running `yarn eslint` axios.get(this.config.endpoint) } } - + // good class myClass { constructor(config) { this.config = config; } - + makeRequest() { axios.get(this.config.endpoint) } } const instance = new myClass(); instance.makeRequest(); - + ``` <a name="avoid-classes-to-handle-dom-events"></a><a name="3.2"></a> + - [3.2](#avoid-classes-to-handle-dom-events) **Avoid classes to handle DOM events** If the only purpose of the class is to bind a DOM event and handle the callback, prefer using a function. ``` @@ -79,14 +83,14 @@ You can run eslint locally by running `yarn eslint` constructor(config) { this.config = config; } - + init() { document.addEventListener('click', () => {}); } } - + // good - + const myFunction = () => { document.addEventListener('click', () => { // handle callback here @@ -95,8 +99,9 @@ You can run eslint locally by running `yarn eslint` ``` <a name="element-container"></a><a name="3.3"></a> + - [3.3](#element-container) **Pass element container to constructor** When your class manipulates the DOM, receive the element container as a parameter. -This is more maintainable and performant. + This is more maintainable and performant. ``` // bad @@ -105,7 +110,7 @@ This is more maintainable and performant. document.querySelector('.b'); } } - + // good class a { constructor(options) { @@ -117,12 +122,13 @@ This is more maintainable and performant. ## Type Casting & Coercion <a name="use-parseint"></a><a name="4.1"></a> + - [4.1](#use-parseint) **Use ParseInt** Use `ParseInt` when converting a numeric string into a number. ``` // bad Number('10') - + // good parseInt('10', 10); ``` @@ -130,12 +136,13 @@ This is more maintainable and performant. ## CSS Selectors <a name="use-js-prefix"></a><a name="5.1"></a> + - [5.1](#use-js-prefix) **Use js prefix** If a CSS class is only being used in JavaScript as a reference to the element, prefix the class name with `js-` ``` // bad <button class="add-user"></button> - + // good <button class="js-add-user"></button> ``` @@ -143,44 +150,51 @@ This is more maintainable and performant. ## Modules <a name="use-absolute-paths"></a><a name="6.1"></a> + - [6.1](#use-absolute-paths) **Use absolute paths for nearby modules** Use absolute paths if the module you are importing is less than two levels up. ``` // bad import GitLabStyleGuide from '~/guides/GitLabStyleGuide'; - + // good import GitLabStyleGuide from '../GitLabStyleGuide'; ``` <a name="use-relative-paths"></a><a name="6.2"></a> + - [6.2](#use-relative-paths) **Use relative paths for distant modules** If the module you are importing is two or more levels up, use a relative path instead of an absolute path. ``` // bad import GitLabStyleGuide from '../../../guides/GitLabStyleGuide'; - + // good import GitLabStyleGuide from '~/GitLabStyleGuide'; ``` <a name="global-namespace"></a><a name="6.3"></a> + - [6.3](#global-namespace) **Do not add to global namespace** <a name="domcontentloaded"></a><a name="6.4"></a> + - [6.4](#domcontentloaded) **Do not use DOMContentLoaded in non-page modules** Imported modules should act the same each time they are loaded. `DOMContentLoaded` events are only allowed on modules loaded in the `/pages/*` directory because those are loaded dynamically with webpack. ## Security <a name="avoid-xss"></a><a name="7.1"></a> + - [7.1](#avoid-xss) **Avoid XSS** Do not use `innerHTML`, `append()` or `html()` to set content. It opens up too many vulnerabilities. ## ESLint <a name="disable-eslint-file"></a><a name="8.1"></a> + - [8.1](#disable-eslint-file) **Disabling ESLint in new files** Do not disable ESLint when creating new files. Existing files may have existing rules disabled due to legacy compatibility reasons but they are in the process of being refactored. <a name="disable-eslint-rule"></a><a name="8.2"></a> + - [8.2](#disable-eslint-rule) **Disabling ESLint rule** Do not disable specific ESLint rules. Due to technical debt, you may disable the following rules only if you are invoking/instantiating existing code modules - [no-new][no-new] diff --git a/doc/development/policies.md b/doc/development/policies.md index 6a3b90f3604..c4ac42bb40a 100644 --- a/doc/development/policies.md +++ b/doc/development/policies.md @@ -88,10 +88,10 @@ An example debug output would look as follows: Each line represents a rule that was evaluated. There are a few things to note: 1. The `-` or `+` symbol indicates whether the rule block was evaluated to be -`false` or `true`, respectively. + `false` or `true`, respectively. 2. The number inside the brackets indicates the score. 3. The last part of the line (e.g. `@john : Issue/1`) shows the username -and subject for that rule. + and subject for that rule. Here you can see that the first four rules were evaluated `false` for which user and subject. For example, you can see in the last line that diff --git a/doc/development/polling.md b/doc/development/polling.md index 3b34f985cd4..76bb5ae7819 100644 --- a/doc/development/polling.md +++ b/doc/development/polling.md @@ -51,6 +51,7 @@ request path. By doing this we avoid query parameter ordering problems and make route matching easier. For more information see: + - [`Poll-Interval` header](fe_guide/performance.md#realtime-components) - [RFC 7232](https://tools.ietf.org/html/rfc7232) - [ETag proposal](https://gitlab.com/gitlab-org/gitlab-ce/issues/26926) diff --git a/doc/development/rake_tasks.md b/doc/development/rake_tasks.md index 4cc500ed1b6..dcb32c89f65 100644 --- a/doc/development/rake_tasks.md +++ b/doc/development/rake_tasks.md @@ -73,6 +73,7 @@ To make sure that indices still fit. You could find great details in: ## Run tests In order to run the test you can use the following commands: + - `rake spec` to run the rspec suite - `rake karma` to run the karma test suite - `rake gitlab:test` to run all the tests diff --git a/doc/development/testing_guide/end_to_end_tests.md b/doc/development/testing_guide/end_to_end_tests.md index e9f236c6b3a..a239dc84a1c 100644 --- a/doc/development/testing_guide/end_to_end_tests.md +++ b/doc/development/testing_guide/end_to_end_tests.md @@ -41,24 +41,24 @@ Currently, we are using _multi-project pipeline_-like approach to run QA pipelines. 1. Developer triggers a manual action, that can be found in CE / EE merge -requests. This starts a chain of pipelines in multiple projects. + requests. This starts a chain of pipelines in multiple projects. 1. The script being executed triggers a pipeline in [Omnibus GitLab][omnibus-gitlab] -and waits for the resulting status. We call this a _status attribution_. + and waits for the resulting status. We call this a _status attribution_. 1. GitLab packages are being built in the [Omnibus GitLab][omnibus-gitlab] -pipeline. Packages are then pushed to its Container Registry. + pipeline. Packages are then pushed to its Container Registry. 1. When packages are ready, and available in the registry, a final step in the -[Omnibus GitLab][omnibus-gitlab] pipeline, triggers a new -[GitLab QA pipeline][gitlab-qa-pipelines]. It also waits for a resulting status. + [Omnibus GitLab][omnibus-gitlab] pipeline, triggers a new + [GitLab QA pipeline][gitlab-qa-pipelines]. It also waits for a resulting status. 1. GitLab QA pulls images from the registry, spins-up containers and runs tests -against a test environment that has been just orchestrated by the `gitlab-qa` -tool. + against a test environment that has been just orchestrated by the `gitlab-qa` + tool. 1. The result of the [GitLab QA pipeline][gitlab-qa-pipelines] is being -propagated upstream, through Omnibus, back to the CE / EE merge request. + propagated upstream, through Omnibus, back to the CE / EE merge request. #### How do I write tests? |