diff options
author | Simon Knox <psimyn@gmail.com> | 2019-03-14 11:19:13 +0300 |
---|---|---|
committer | Simon Knox <psimyn@gmail.com> | 2019-03-22 01:24:10 +0300 |
commit | d7c92faacbaa4ad3aa53fc1de3c7c9d543624d97 (patch) | |
tree | 3298cf055f89908618d8691dd7cb23e457a66fc2 /doc/development | |
parent | a59b7cee0afc152efba6aa4c430c14c0b038107a (diff) |
Cleanup of fe_docs
Start moving back to regular fe_docs
Remove Initiatives, add section to index in fe_guide
Delete some no-longer-relevant parts from principles
Update title - Progressive Enchancement is a browser-support term
and could be confused
"When to use" parts are discussed elswhere
Vue & jQuery issue is no longer relevant
Delete duplicate Security docs
Remove empty files, move event_tracking
Shuffle index sections around
Remove sections on Vue & Webpack (we say same thing in prev paragraph)
Remove link to Droplab docs
Diffstat (limited to 'doc/development')
-rw-r--r-- | doc/development/fe_guide/event_tracking.md (renamed from doc/development/new_fe_guide/event_tracking.md) | 0 | ||||
-rw-r--r-- | doc/development/fe_guide/index.md | 35 | ||||
-rw-r--r-- | doc/development/fe_guide/principles.md | 15 | ||||
-rw-r--r-- | doc/development/fe_guide/vue.md | 7 | ||||
-rw-r--r-- | doc/development/new_fe_guide/development/design_patterns.md | 3 | ||||
-rw-r--r-- | doc/development/new_fe_guide/development/index.md | 12 | ||||
-rw-r--r-- | doc/development/new_fe_guide/development/network_requests.md | 3 | ||||
-rw-r--r-- | doc/development/new_fe_guide/development/security.md | 14 | ||||
-rw-r--r-- | doc/development/new_fe_guide/index.md | 11 | ||||
-rw-r--r-- | doc/development/new_fe_guide/initiatives.md | 3 | ||||
-rw-r--r-- | doc/development/new_fe_guide/principles.md | 35 |
11 files changed, 34 insertions, 104 deletions
diff --git a/doc/development/new_fe_guide/event_tracking.md b/doc/development/fe_guide/event_tracking.md index 6ab3fa4acf3..6ab3fa4acf3 100644 --- a/doc/development/new_fe_guide/event_tracking.md +++ b/doc/development/fe_guide/event_tracking.md diff --git a/doc/development/fe_guide/index.md b/doc/development/fe_guide/index.md index 86b8972a69e..d5cc28dc00c 100644 --- a/doc/development/fe_guide/index.md +++ b/doc/development/fe_guide/index.md @@ -1,8 +1,5 @@ # Frontend Development Guidelines -> **Notice:** -> We are currently in the process of re-writing our development guide to make it easier to find information. The new guide is still WIP but viewable in [development/new_fe_guide](../new_fe_guide/index.md) - This document describes various guidelines to ensure consistency and quality across GitLab's frontend team. @@ -12,15 +9,6 @@ GitLab is built on top of [Ruby on Rails][rails] using [Haml][haml] and also a J 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. - Working with our frontend assets requires Node (v8.10.0 or greater) and Yarn (v1.10.0 or greater). You can find information on how to install these on our [installation guide][install]. @@ -31,6 +19,14 @@ For our currently-supported browsers, see our [requirements][requirements]. --- +## Initiatives + +Current high-level frontend goals are listed on [Frontend Epics](https://gitlab.com/groups/gitlab-org/-/epics?label_name%5B%5D=frontend). + +## [Principles](principles.md) + +High-level guidelines for contributing to GitLab. + ## [Development Process](development_process.md) How we plan and execute the work on the frontend. @@ -73,6 +69,10 @@ How we use SVG for our Icons and Illustrations. How we use UI components. +## [Event Tracking](event_tracking.md) + +How we use Snowplow to track custom events. + --- ## Style Guides @@ -124,14 +124,3 @@ The [externalization part of the guide](../i18n/externalization.md) explains the [scss-lint]: https://github.com/brigade/scss-lint [install]: ../../install/installation.md#4-node [requirements]: ../../install/requirements.md#supported-web-browsers - ---- - -## [DropLab](droplab/droplab.md) - -Our internal `DropLab` dropdown library. - -- [DropLab](droplab/droplab.md) -- [Ajax plugin](droplab/plugins/ajax.md) -- [Filter plugin](droplab/plugins/filter.md) -- [InputSetter plugin](droplab/plugins/input_setter.md) diff --git a/doc/development/fe_guide/principles.md b/doc/development/fe_guide/principles.md new file mode 100644 index 00000000000..6fb3456222f --- /dev/null +++ b/doc/development/fe_guide/principles.md @@ -0,0 +1,15 @@ +# Principles + +These principles will ensure that your frontend contribution starts off in the right direction. + +## Discuss architecture before implementation + +Discuss your architecture design in an issue before writing code. This helps decrease the review time and also provides good practice for writing and thinking about system design. + +## Be consistent + +There are multiple ways of writing code to accomplish the same results. We should be as consistent as possible in how we write code across our codebases. This will make it more easier us to maintain our code across GitLab. + +## Improve code [iteratively](https://about.gitlab.com/handbook/values/#iteration) + +Whenever you see with existing code that does not follow our current style guide, update it proactively. You don't need to fix everything, but each merge request should iteratively improve our codebase, and reduce technical debt where possible. diff --git a/doc/development/fe_guide/vue.md b/doc/development/fe_guide/vue.md index 435fdf39fb4..a34d1fcec89 100644 --- a/doc/development/fe_guide/vue.md +++ b/doc/development/fe_guide/vue.md @@ -120,6 +120,13 @@ You can read more about components in Vue.js site, [Component System][component- #### Vuex Check this [page](vuex.md) for more details. +### Mixing Vue and jQuery + +- Mixing Vue and jQuery is not recommended. +- If you need to use a specific jQuery plugin in Vue, [create a wrapper around it][https://vuejs.org/v2/examples/select2.html]. +- It is acceptable for Vue to listen to existing jQuery events using jQuery event listeners. +- It is not recommended to add new jQuery events for Vue to interact with jQuery. + ## Style guide Please refer to the Vue section of our [style guide](style_guide_js.md#vuejs) diff --git a/doc/development/new_fe_guide/development/design_patterns.md b/doc/development/new_fe_guide/development/design_patterns.md deleted file mode 100644 index ee06566ed30..00000000000 --- a/doc/development/new_fe_guide/development/design_patterns.md +++ /dev/null @@ -1,3 +0,0 @@ -# Design patterns - -> TODO: Add content diff --git a/doc/development/new_fe_guide/development/index.md b/doc/development/new_fe_guide/development/index.md index cee8e43ebad..5dced3dc466 100644 --- a/doc/development/new_fe_guide/development/index.md +++ b/doc/development/new_fe_guide/development/index.md @@ -1,9 +1,5 @@ # Development -## [Design patterns](design_patterns.md) - -Examples of proven design patterns used in our codebase. - ## [Components](components.md) Documentation on existing components and how to best create a new component. @@ -12,14 +8,6 @@ Documentation on existing components and how to best create a new component. Learn how to implement an accessible frontend. -## [Network requests](network_requests.md) - -Learn how to handle network requests in our codebase. - -## [Security](security.md) - -Learn how to ensure that our frontend is secure. - ## [Performance](performance.md) Learn how to keep our frontend performant. diff --git a/doc/development/new_fe_guide/development/network_requests.md b/doc/development/new_fe_guide/development/network_requests.md deleted file mode 100644 index 047c00313bc..00000000000 --- a/doc/development/new_fe_guide/development/network_requests.md +++ /dev/null @@ -1,3 +0,0 @@ -# Network requests - -> TODO: Add content diff --git a/doc/development/new_fe_guide/development/security.md b/doc/development/new_fe_guide/development/security.md deleted file mode 100644 index 5bb38f17988..00000000000 --- a/doc/development/new_fe_guide/development/security.md +++ /dev/null @@ -1,14 +0,0 @@ -# Security - -## Avoid inline scripts and styles - -Inline scripts and styles should be avoided in almost all cases. In an effort to protect users from [XSS vulnerabilities](https://en.wikipedia.org/wiki/Cross-site_scripting), we will be disabling inline scripts using Content Security Policy. - -## Including external resources - -External fonts, CSS, and JavaScript should never be used with the exception of Google Analytics and Piwik - and only when the instance has enabled it. Assets should always be hosted and served locally from the GitLab instance. Embedded resources via `iframes` should never be used except in certain circumstances such as with ReCaptcha, which cannot be used without an `iframe`. - -## Resources for security testing - -- [Mozilla's HTTP Observatory CLI](https://github.com/mozilla/http-observatory-cli) -- [Qualys SSL Labs Server Test](https://www.ssllabs.com/ssltest/analyze.html) diff --git a/doc/development/new_fe_guide/index.md b/doc/development/new_fe_guide/index.md index 5fd5af252ef..0e8f5486861 100644 --- a/doc/development/new_fe_guide/index.md +++ b/doc/development/new_fe_guide/index.md @@ -3,14 +3,6 @@ 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. -## [Principles](principles.md) - -Ensure that your frontend contribution starts off in the right direction. - -## [Initiatives](initiatives.md) - -High level overview of where we are going from a frontend perspective. - ## [Development](development/index.md) Guidance on topics related to development. @@ -27,9 +19,6 @@ Learn about all the internal JavaScript modules that make up our frontend. Style guides to keep our code consistent. -## [Event Tracking with Snowplow](event_tracking.md) - -How we use Snowplow to track custom events. ## [Tips](tips.md) diff --git a/doc/development/new_fe_guide/initiatives.md b/doc/development/new_fe_guide/initiatives.md deleted file mode 100644 index c81ed3579f0..00000000000 --- a/doc/development/new_fe_guide/initiatives.md +++ /dev/null @@ -1,3 +0,0 @@ -# Initiatives - -> TODO: Add Initiatives diff --git a/doc/development/new_fe_guide/principles.md b/doc/development/new_fe_guide/principles.md deleted file mode 100644 index 0af5f506a91..00000000000 --- a/doc/development/new_fe_guide/principles.md +++ /dev/null @@ -1,35 +0,0 @@ -# Principles - -These principles will ensure that your frontend contribution starts off in the right direction. - -## Discuss architecture before implementation - -Discuss your architecture design in an issue before writing code. This helps decrease the review time and also provides good practice for writing and thinking about system design. - -## Be consistent - -There are multiple ways of writing code to accomplish the same results. We should be as consistent as possible in how we write code across our codebases. This will make it more easier us to maintain our code across GitLab. - -## Enhance progressively - -Whenever you see with existing code that does not follow our current style guide, update it proactively. Refrain from changing everything but each merge request should progressively enhance our codebase and reduce technical debt. - -## When to use Vue - -- Use Vue for feature that make use of heavy DOM manipulation -- Use Vue for reusable components - -## When to use jQuery - -- Use jQuery to interact with Bootstrap JavaScript components -- Avoid jQuery when a better alternative exists. We are slowly moving away from it [#43559][jquery-future] - -## Mixing Vue and jQuery - -- Mixing Vue and jQuery is not recommended. -- If you need to use a specific jQuery plugin in Vue, [create a wrapper around it][select2]. -- It is acceptable for Vue to listen to existing jQuery events using jQuery event listeners. -- It is not recommended to add new jQuery events for Vue to interact with jQuery. - -[jquery-future]: https://gitlab.com/gitlab-org/gitlab-ce/issues/43559 -[select2]: https://vuejs.org/v2/examples/select2.html |