gitlab-org--gitlab-foss/doc/development/fe_guide/index.md

# Frontend Development Guidelines

This document describes various guidelines to ensure consistency and quality
across GitLab's frontend team.

## Overview

GitLab is built on top of [Ruby on Rails][rails] using [Haml][haml] and also a JavaScript based Frontend with [Vue.js][vue].
Be wary of [the limitations that come with using Hamlit][hamlit-limits]. We also use [SCSS][scss] and plain JavaScript with
modern ECMAScript standards supported through [Babel][babel] and ES module support through [webpack][webpack].

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].

### Browser Support

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.

## [Architecture](architecture.md)

How we go about making fundamental design decisions in GitLab's frontend team
or make changes to our frontend development guidelines.

## [Testing](../testing_guide/frontend_testing.md)

How we write frontend tests, run the GitLab test suite, and debug test related
issues.

## [Design Patterns](design_patterns.md)

Common JavaScript design patterns in GitLab's codebase.

## [Vue.js Best Practices](vue.md)

Vue specific design patterns and practices.

## [Vuex](vuex.md)

Vuex specific design patterns and practices.

## [Axios](axios.md)

Axios specific practices and gotchas.

## [GraphQL](graphql.md)

How to use GraphQL

## [Icons and Illustrations](icons.md)

How we use SVG for our Icons and Illustrations.

## [Components](components.md)

How we use UI components.

## [Event Tracking](event_tracking.md)

How we use Snowplow to track custom events.

## Frontend FAQ

Read the [frontend's FAQ](frontend_faq.md) for common small pieces of helpful information.

---

## Style Guides

### [JavaScript Style Guide](style_guide_js.md)

We use eslint to enforce our JavaScript style guides. Our guide is based on
the excellent [Airbnb][airbnb-js-style-guide] style guide with a few small
changes.

### [SCSS Style Guide](style_guide_scss.md)

Our SCSS conventions which are enforced through [scss-lint][scss-lint].

---

## [Performance](performance.md)

Best practices for monitoring and maximizing frontend performance.

---

## [Security](security.md)

Frontend security practices.

---

## [Accessibility](accessibility.md)

Our accessibility standards and resources.

## [Internationalization (i18n) and Translations](../i18n/externalization.md)

Frontend internationalization support is described in [this document](../i18n/).
The [externalization part of the guide](../i18n/externalization.md) explains the helpers/methods available.

[rails]: http://rubyonrails.org/
[haml]: http://haml.info/
[hamlit]: https://github.com/k0kubun/hamlit
[hamlit-limits]: https://github.com/k0kubun/hamlit/blob/master/REFERENCE.md#limitations
[scss]: http://sass-lang.com/
[babel]: https://babeljs.io/
[webpack]: https://webpack.js.org/
[jquery]: https://jquery.com/
[vue]: http://vuejs.org/
[axios]: https://github.com/axios/axios
[airbnb-js-style-guide]: https://github.com/airbnb/javascript
[scss-lint]: https://github.com/brigade/scss-lint
[install]: ../../install/installation.md#4-node
[requirements]: ../../install/requirements.md#supported-web-browsers
Creates Frontend Style guide 2017-03-22 15:30:54 -04:00			`# Frontend Development Guidelines`

			`This document describes various guidelines to ensure consistency and quality`
			`across GitLab's frontend team.`

			`## Overview`

Documentation: Frontend Building Checklist 2018-04-19 14:36:17 -04:00			`GitLab is built on top of [Ruby on Rails][rails] using [Haml][haml] and also a JavaScript based Frontend with [Vue.js][vue].`
			`Be wary of [the limitations that come with using Hamlit][hamlit-limits]. We also use [SCSS][scss] and plain JavaScript with`
			`modern ECMAScript standards supported through [Babel][babel] and ES module support through [webpack][webpack].`

Update FE developer and installation documentation 2019-01-10 12:35:01 -05:00			`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`
Creates Frontend Style guide 2017-03-22 15:30:54 -04:00			`[installation guide][install].`

			`### Browser Support`

			`For our currently-supported browsers, see our [requirements][requirements].`

Adds vue js example application and documentation 2017-04-20 07:24:40 -04:00			`---`

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 2019-03-14 04:19:13 -04:00			`## 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.`

Documentation: Frontend Building Checklist 2018-04-19 14:36:17 -04:00			`## [Development Process](development_process.md)`
Add event tracking documentation - Add link to Event tracking in FE guides 2019-02-13 09:43:19 -05:00
Documentation: Frontend Building Checklist 2018-04-19 14:36:17 -04:00			`How we plan and execute the work on the frontend.`
Creates Frontend Style guide 2017-03-22 15:30:54 -04:00
			`## [Architecture](architecture.md)`
Add event tracking documentation - Add link to Event tracking in FE guides 2019-02-13 09:43:19 -05:00
Creates Frontend Style guide 2017-03-22 15:30:54 -04:00			`How we go about making fundamental design decisions in GitLab's frontend team`
			`or make changes to our frontend development guidelines.`

Refactor the Development documentation, and divide the Testing documentation into multiple pages 2017-10-11 01:59:34 -04:00			`## [Testing](../testing_guide/frontend_testing.md)`
Add event tracking documentation - Add link to Event tracking in FE guides 2019-02-13 09:43:19 -05:00
Creates Frontend Style guide 2017-03-22 15:30:54 -04:00			`How we write frontend tests, run the GitLab test suite, and debug test related`
			`issues.`

			`## [Design Patterns](design_patterns.md)`
Add event tracking documentation - Add link to Event tracking in FE guides 2019-02-13 09:43:19 -05:00
Creates Frontend Style guide 2017-03-22 15:30:54 -04:00			`Common JavaScript design patterns in GitLab's codebase.`

			`## [Vue.js Best Practices](vue.md)`
Add event tracking documentation - Add link to Event tracking in FE guides 2019-02-13 09:43:19 -05:00
Creates Frontend Style guide 2017-03-22 15:30:54 -04:00			`Vue specific design patterns and practices.`

Fixes typos and adds mutations examples 2018-03-22 06:50:52 -04:00			`## [Vuex](vuex.md)`
Add event tracking documentation - Add link to Event tracking in FE guides 2019-02-13 09:43:19 -05:00
Fixes typos and adds mutations examples 2018-03-22 06:50:52 -04:00			`Vuex specific design patterns and practices.`

Use axios instead of vue resource - step 1 2017-11-20 04:57:08 -05:00			`## [Axios](axios.md)`
Add event tracking documentation - Add link to Event tracking in FE guides 2019-02-13 09:43:19 -05:00
Use axios instead of vue resource - step 1 2017-11-20 04:57:08 -05:00			`Axios specific practices and gotchas.`
Moves vue resource docs into a new file. Adds docs regarding handling 204 response 2017-10-23 08:07:44 -04:00
Added frontend GraphQL docs 2018-11-28 05:00:03 -05:00			`## [GraphQL](graphql.md)`
Add event tracking documentation - Add link to Event tracking in FE guides 2019-02-13 09:43:19 -05:00
Added frontend GraphQL docs 2018-11-28 05:00:03 -05:00			`How to use GraphQL`

Update Frontend documentation regarding Vue and Icons/Illustrations 2018-05-27 15:21:12 -04:00			`## [Icons and Illustrations](icons.md)`
Add event tracking documentation - Add link to Event tracking in FE guides 2019-02-13 09:43:19 -05:00
Update Frontend documentation regarding Vue and Icons/Illustrations 2018-05-27 15:21:12 -04:00			`How we use SVG for our Icons and Illustrations.`
Resolve "Better SVG Usage in the Frontend" 2017-09-22 04:39:47 -04:00
Add new modal Vue component 2018-02-14 04:16:04 -05:00			`## [Components](components.md)`

			`How we use UI components.`

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 2019-03-14 04:19:13 -04:00			`## [Event Tracking](event_tracking.md)`

			`How we use Snowplow to track custom events.`

Create frontend FAQ (documentation) 2019-04-16 11:22:05 -04:00			`## Frontend FAQ`

			`Read the [frontend's FAQ](frontend_faq.md) for common small pieces of helpful information.`

Resolve "Better SVG Usage in the Frontend" 2017-09-22 04:39:47 -04:00			`---`

Creates Frontend Style guide 2017-03-22 15:30:54 -04:00			`## Style Guides`

			`### [JavaScript Style Guide](style_guide_js.md)`

Add event tracking documentation - Add link to Event tracking in FE guides 2019-02-13 09:43:19 -05:00			`We use eslint to enforce our JavaScript style guides. Our guide is based on`
Creates Frontend Style guide 2017-03-22 15:30:54 -04:00			`the excellent [Airbnb][airbnb-js-style-guide] style guide with a few small`
			`changes.`

			`### [SCSS Style Guide](style_guide_scss.md)`

			`Our SCSS conventions which are enforced through [scss-lint][scss-lint].`

			`---`

			`## [Performance](performance.md)`
Add event tracking documentation - Add link to Event tracking in FE guides 2019-02-13 09:43:19 -05:00
Creates Frontend Style guide 2017-03-22 15:30:54 -04:00			`Best practices for monitoring and maximizing frontend performance.`

			`---`

			`## [Security](security.md)`
Add event tracking documentation - Add link to Event tracking in FE guides 2019-02-13 09:43:19 -05:00
Creates Frontend Style guide 2017-03-22 15:30:54 -04:00			`Frontend security practices.`

			`---`

			`## [Accessibility](accessibility.md)`
Add event tracking documentation - Add link to Event tracking in FE guides 2019-02-13 09:43:19 -05:00
Creates Frontend Style guide 2017-03-22 15:30:54 -04:00			`Our accessibility standards and resources.`

Update i18n in FE docs, marking, interpolation 2017-10-24 00:16:57 -04:00			`## [Internationalization (i18n) and Translations](../i18n/externalization.md)`
Add event tracking documentation - Add link to Event tracking in FE guides 2019-02-13 09:43:19 -05:00
Update i18n in FE docs, marking, interpolation 2017-10-24 00:16:57 -04:00			`Frontend internationalization support is described in [this document](../i18n/).`
			`The [externalization part of the guide](../i18n/externalization.md) explains the helpers/methods available.`

Creates Frontend Style guide 2017-03-22 15:30:54 -04:00			`[rails]: http://rubyonrails.org/`
			`[haml]: http://haml.info/`
			`[hamlit]: https://github.com/k0kubun/hamlit`
			`[hamlit-limits]: https://github.com/k0kubun/hamlit/blob/master/REFERENCE.md#limitations`
			`[scss]: http://sass-lang.com/`
			`[babel]: https://babeljs.io/`
			`[webpack]: https://webpack.js.org/`
			`[jquery]: https://jquery.com/`
			`[vue]: http://vuejs.org/`
Add axios to frontend docs as the default network request library 2018-02-15 18:19:54 -05:00			`[axios]: https://github.com/axios/axios`
Creates Frontend Style guide 2017-03-22 15:30:54 -04:00			`[airbnb-js-style-guide]: https://github.com/airbnb/javascript`
			`[scss-lint]: https://github.com/brigade/scss-lint`
			`[install]: ../../install/installation.md#4-node`
			`[requirements]: ../../install/requirements.md#supported-web-browsers`