BigW Consortium Gitlab

frontend.md 9.83 KB
Newer Older
1
# Frontend Development Guidelines
2

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

6 7
## Overview

8 9 10
GitLab is built on top of [Ruby on Rails][rails] using [Haml][haml] with
[Hamlit][hamlit]. Be wary of [the limitations that come with using
Hamlit][hamlit-limits]. We also use [SCSS][scss] and plain JavaScript with
11 12 13 14 15 16 17 18
[ES6 by way of Babel][es6].

The asset pipeline is [Sprockets][sprockets], which handles the concatenation,
minification, and compression of our assets.

[jQuery][jquery] is used throughout the application's JavaScript, with
[Vue.js][vue] for particularly advanced, dynamic elements.

19 20 21
### Vue

For more complex frontend features, we recommend using Vue.js. It shares
22
some ideas with React.js as well as Angular.
23 24 25

To get started with Vue, read through [their documentation][vue-docs].

26 27
## Performance

28 29 30 31 32 33 34
### Resources

- [WebPage Test][web-page-test] for testing site loading time and size.
- [Google PageSpeed Insights][pagespeed-insights] grades web pages and provides feedback to improve the page.
- [Profiling with Chrome DevTools][google-devtools-profiling]
- [Browser Diet][browser-diet] is a community-built guide that catalogues practical tips for improving web page performance.

35
### Page-specific JavaScript
36

37 38 39 40
Certain pages may require the use of a third party library, such as [d3][d3] for
the User Activity Calendar and [Chart.js][chartjs] for the Graphs pages. These
libraries increase the page size significantly, and impact load times due to
bandwidth bottlenecks and the browser needing to parse more JavaScript.
41

42
In cases where libraries are only used on a few specific pages, we use
43
"page-specific JavaScript" to prevent the main `application.js` file from
44 45 46 47 48 49
becoming unnecessarily large.

Steps to split page-specific JavaScript from the main `application.js`:

1. Create a directory for the specific page(s), e.g. `graphs/`.
1. In that directory, create a `namespace_bundle.js` file, e.g. `graphs_bundle.js`.
50
1. In `graphs_bundle.js` add the line `//= require_tree .`, this adds all other files in the directory to the bundle.
51
1. Add any necessary libraries to `app/assets/javascripts/lib/`, all files directly descendant from this directory will be precompiled as separate assets, in this case `chart.js` would be added.
52 53 54
1. Add the new "bundle" file to the list of precompiled assets in
`config/application.rb`.
  - For example: `config.assets.precompile << "graphs/graphs_bundle.js"`.
55
1. Move code reliant on these libraries into the `graphs` directory.
56 57 58 59 60 61 62 63
1. In the relevant views, add the scripts to the page with the following:

```haml
- content_for :page_specific_javascripts do
  = page_specific_javascript_tag('lib/chart.js')
  = page_specific_javascript_tag('graphs/graphs_bundle.js')
```

64
The above loads `chart.js` and `graphs_bundle.js` for this page only. `chart.js`
65
is separated from the bundle file so it can be cached separately from the bundle
66 67
and reused for other pages that also rely on the library. For an example, see
[this Haml file][page-specific-js-example].
68 69 70 71

### Minimizing page size

A smaller page size means the page loads faster (especially important on mobile
72 73
and poor connections), the page is parsed more quickly by the browser, and less
data is used for users with capped data plans.
74 75 76

General tips:

77
- Don't add new fonts.
78
- Prefer font formats with better compression, e.g. WOFF2 is better than WOFF, which is better than TTF.
79
- Compress and minify assets wherever possible (For CSS/JS, Sprockets does this for us).
80 81
- If some functionality can reasonably be achieved without adding extra libraries, avoid them.
- Use page-specific JavaScript as described above to dynamically load libraries that are only needed on certain pages.
82 83 84

## Accessibility

85 86
### Resources

87
[Chrome Accessibility Developer Tools][chrome-accessibility-developer-tools]
88 89 90 91 92 93 94
are useful for testing for potential accessibility problems in GitLab.

Accessibility best-practices and more in-depth information is available on
[the Audit Rules page][audit-rules] for the Chrome Accessibility Developer Tools.

## Security

95 96
### Resources

97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152
[Mozilla’s HTTP Observatory CLI][observatory-cli] and the
[Qualys SSL Labs Server Test][qualys-ssl] are good resources for finding
potential problems and ensuring compliance with security best practices.

<!-- Uncomment these sections when CSP/SRI are implemented.
### Content Security Policy (CSP)

Content Security Policy is a web standard that intends to mitigate certain
forms of Cross-Site Scripting (XSS) as well as data injection.

Content Security Policy rules should be taken into consideration when
implementing new features, especially those that may rely on connection with
external services.

GitLab's CSP is used for the following:

- Blocking plugins like Flash and Silverlight from running at all on our pages.
- Blocking the use of scripts and stylesheets downloaded from external sources.
- Upgrading `http` requests to `https` when possible.
- Preventing `iframe` elements from loading in most contexts.

Some exceptions include:

- Scripts from Google Analytics and Piwik if either is enabled.
- Connecting with GitHub, Bitbucket, GitLab.com, etc. to allow project importing.
- Connecting with Google, Twitter, GitHub, etc. to allow OAuth authentication.

We use [the Secure Headers gem][secure_headers] to enable Content
Security Policy headers in the GitLab Rails app.

Some resources on implementing Content Security Policy:

- [MDN Article on CSP][mdn-csp]
- [GitHub’s CSP Journey on the GitHub Engineering Blog][github-eng-csp]
- The Dropbox Engineering Blog's series on CSP: [1][dropbox-csp-1], [2][dropbox-csp-2], [3][dropbox-csp-3], [4][dropbox-csp-4]

### Subresource Integrity (SRI)

Subresource Integrity prevents malicious assets from being provided by a CDN by
guaranteeing that the asset downloaded is identical to the asset the server
is expecting.

The Rails app generates a unique hash of the asset, which is used as the
asset's `integrity` attribute. The browser generates the hash of the asset
on-load and will reject the asset if the hashes do not match.

All CSS and JavaScript assets should use Subresource Integrity. For implementation details,
see the documentation for [the Sprockets implementation of SRI][sprockets-sri].

Some resources on implementing Subresource Integrity:

- [MDN Article on SRI][mdn-sri]
- [Subresource Integrity on the GitHub Engineering Blog][github-eng-sri]

-->

153 154
### Including external resources

155 156 157 158 159
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`.
160 161 162

### Avoiding inline scripts and styles

163
In order to protect users from [XSS vulnerabilities][xss], we will disable inline scripts in the future using Content Security Policy.
164

165 166
While inline scripts can be useful, they're also a security concern. If
user-supplied content is unintentionally left un-sanitized, malicious users can
167
inject scripts into the web app.
168

169 170 171 172
Inline styles should be avoided in almost all cases, they should only be used
when no alternatives can be found. This allows reusability of styles as well as
readability.

173
## Style guides and linting
174

175
See the relevant style guides for our guidelines and for information on linting:
176 177 178

- [SCSS][scss-style-guide]

179 180
## Testing

181 182 183
Feature tests need to be written for all new features. Regression tests
also need to be written for all bug fixes to prevent them from occurring
again in the future.
184 185 186 187

See [the Testing Standards and Style Guidelines](testing.md) for more
information.

188 189 190 191
## Supported browsers

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

192 193 194 195 196 197 198 199 200
[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/
[es6]: https://babeljs.io/
[sprockets]: https://github.com/rails/sprockets
[jquery]: https://jquery.com/
[vue]: http://vuejs.org/
201
[vue-docs]: http://vuejs.org/guide/index.html
202 203 204 205
[web-page-test]: http://www.webpagetest.org/
[pagespeed-insights]: https://developers.google.com/speed/pagespeed/insights/
[google-devtools-profiling]: https://developers.google.com/web/tools/chrome-devtools/profile/?hl=en
[browser-diet]: https://browserdiet.com/
206 207
[d3]: https://d3js.org/
[chartjs]: http://www.chartjs.org/
208
[page-specific-js-example]: https://gitlab.com/gitlab-org/gitlab-ce/blob/13bb9ed77f405c5f6ee4fdbc964ecf635c9a223f/app/views/projects/graphs/_head.html.haml#L6-8
209 210
[chrome-accessibility-developer-tools]: https://github.com/GoogleChrome/accessibility-developer-tools
[audit-rules]: https://github.com/GoogleChrome/accessibility-developer-tools/wiki/Audit-Rules
211 212 213 214 215 216 217 218 219 220 221 222
[observatory-cli]: https://github.com/mozilla/http-observatory-cli)
[qualys-ssl]: https://www.ssllabs.com/ssltest/analyze.html
[secure_headers]: https://github.com/twitter/secureheaders
[mdn-csp]: https://developer.mozilla.org/en-US/docs/Web/Security/CSP
[github-eng-csp]: http://githubengineering.com/githubs-csp-journey/
[dropbox-csp-1]: https://blogs.dropbox.com/tech/2015/09/on-csp-reporting-and-filtering/
[dropbox-csp-2]: https://blogs.dropbox.com/tech/2015/09/unsafe-inline-and-nonce-deployment/
[dropbox-csp-3]: https://blogs.dropbox.com/tech/2015/09/csp-the-unexpected-eval/
[dropbox-csp-4]: https://blogs.dropbox.com/tech/2015/09/csp-third-party-integrations-and-privilege-separation/
[mdn-sri]: https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity
[github-eng-sri]: http://githubengineering.com/subresource-integrity/
[sprockets-sri]: https://github.com/rails/sprockets-rails#sri-support
223
[xss]: https://en.wikipedia.org/wiki/Cross-site_scripting
224
[scss-style-guide]: scss_styleguide.md
225
[requirements]: ../install/requirements.md#supported-web-browsers