From e000f02bd3b7c13f7f3a95b855fea6b3dd277417 Mon Sep 17 00:00:00 2001 From: Drew Blessing Date: Tue, 13 Sep 2016 17:15:14 -0500 Subject: Add support for column limits in add_column_with_default --- doc/development/migration_style_guide.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) (limited to 'doc/development') diff --git a/doc/development/migration_style_guide.md b/doc/development/migration_style_guide.md index b8fab3aaff7..295eae0a88e 100644 --- a/doc/development/migration_style_guide.md +++ b/doc/development/migration_style_guide.md @@ -111,6 +111,28 @@ class MyMigration < ActiveRecord::Migration end ``` + +## Integer column type + +By default, an integer column can hold up to a 4-byte (32-bit) number. That is +a max value of 2,147,483,647. Be aware of this when creating a column that will +hold file sizes in byte units. If you are tracking file size in bytes this +restricts the maximum file size to just over 2GB. + +To allow an integer column to hold up to an 8-byte (64-bit) number, explicitly +set the limit to 8-bytes. This will allow the column to hold a value up to +9,223,372,036,854,775,807. + +Rails migration example: + +``` +add_column_with_default(:projects, :foo, :integer, default: 10, limit: 8) + +# or + +add_column(:projects, :foo, :integer, default: 10, limit: 8) +``` + ## Testing Make sure that your migration works with MySQL and PostgreSQL with data. An empty database does not guarantee that your migration is correct. -- cgit v1.2.1 From 182bcc977aec49d802bb7b511faf618b2df1d4ea Mon Sep 17 00:00:00 2001 From: Connor Shea Date: Mon, 11 Jul 2016 12:48:00 -0600 Subject: Initial incomplete draft of the Frontend Development Guidelines. [ci skip] --- doc/development/README.md | 1 + doc/development/frontend.md | 61 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 62 insertions(+) create mode 100644 doc/development/frontend.md (limited to 'doc/development') diff --git a/doc/development/README.md b/doc/development/README.md index 58c00f618fa..9706cb1de7f 100644 --- a/doc/development/README.md +++ b/doc/development/README.md @@ -13,6 +13,7 @@ - [SQL Migration Style Guide](migration_style_guide.md) for creating safe SQL migrations - [Testing standards and style guidelines](testing.md) - [UI guide](ui_guide.md) for building GitLab with existing CSS styles and elements +- [Frontend guidelines](frontend.md) - [SQL guidelines](sql.md) for SQL guidelines ## Process diff --git a/doc/development/frontend.md b/doc/development/frontend.md new file mode 100644 index 00000000000..39460b72ec0 --- /dev/null +++ b/doc/development/frontend.md @@ -0,0 +1,61 @@ +# Frontend Guidelines + +This document describes various guidelines to follow to ensure good and +consistent performance of GitLab. + +## Performance + +### Per-page JavaScript + +Per-page JavaScript is JavaScript that is loaded only where necessary. + +There are some potential problems to per-page JavaScript as well. For one, + +### Minimizing page size + +A smaller page size means the page loads faster (especially important on mobile +and poor connections), the page is parsed faster by the browser, and less data is used for +users with capped data plans. + +General tips: + +- Don't add fonts that are unnecessary. +- Prefer font formats with better compression, e.g. WOFF2 is better than WOFF is better than TFF. +- Compress and minify assets wherever possible (For CSS/JS, Sprockets does this for us). +- If a piece of functionality can be reasonably done without adding extra libraries, prefer not to use extra libraries. +- Use per-page JavaScripts as described above to remove libraries that are only loaded on certain pages. + +## Accessibility + +The [Chrome Accessibility Developer Tools][chrome-accessibility-developer-tools] +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 + +### Content Security Policy + + + +### Subresource Integrity + + + +### Including external resources + +External fonts, CSS, JavaScript should never be used with the exception of +Google Analytics - 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 reasonably be used without an iframe. + +### Avoiding inline scripts and styles + +While inline scripts can be useful, they're also a security concern. If +user-supplied content is unintentionally left un-sanitized, malicious users can +inject scripts into the site. + +[chrome-accessibility-developer-tools]: https://github.com/GoogleChrome/accessibility-developer-tools +[audit-rules]: https://github.com/GoogleChrome/accessibility-developer-tools/wiki/Audit-Rules -- cgit v1.2.1 From ccbaed208b5ea3d79bafed7267d644147308556a Mon Sep 17 00:00:00 2001 From: Connor Shea Date: Mon, 25 Jul 2016 12:15:09 -0600 Subject: Add more information on page-specific JS. [ci skip] --- doc/development/frontend.md | 64 +++++++++++++++++++++++++++++++-------------- 1 file changed, 45 insertions(+), 19 deletions(-) (limited to 'doc/development') diff --git a/doc/development/frontend.md b/doc/development/frontend.md index 39460b72ec0..c2dd130c258 100644 --- a/doc/development/frontend.md +++ b/doc/development/frontend.md @@ -5,17 +5,40 @@ consistent performance of GitLab. ## Performance -### Per-page JavaScript +### Page-specific JavaScript -Per-page JavaScript is JavaScript that is loaded only where necessary. +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. -There are some potential problems to per-page JavaScript as well. For one, +In cases where libraries are only used on a few specific pages, we use +"Page-specific JavaScript" to prevent the main `application.js` file from +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`. +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"`. +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. +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') +``` + +The above loads `chart.js` and `graphs_bundle.js` for only this page. `chart.js` is separated from the bundle file so it can be cached separately from the bundle and reused for other pages that also rely on the library. ### Minimizing page size A smaller page size means the page loads faster (especially important on mobile -and poor connections), the page is parsed faster by the browser, and less data is used for -users with capped data plans. +and poor connections), the page is parsed more quickly by the browser, and less +data is used for users with capped data plans. General tips: @@ -23,7 +46,7 @@ General tips: - Prefer font formats with better compression, e.g. WOFF2 is better than WOFF is better than TFF. - Compress and minify assets wherever possible (For CSS/JS, Sprockets does this for us). - If a piece of functionality can be reasonably done without adding extra libraries, prefer not to use extra libraries. -- Use per-page JavaScripts as described above to remove libraries that are only loaded on certain pages. +- Use page-specific JavaScripts as described above to dynamically load libraries that are only needed on certain pages. ## Accessibility @@ -35,27 +58,30 @@ Accessibility best-practices and more in-depth information is available on ## Security -### Content Security Policy - - - -### Subresource Integrity - - - ### Including external resources -External fonts, CSS, JavaScript should never be used with the exception of -Google Analytics - 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 reasonably be used without an iframe. +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`. ### Avoiding inline scripts and styles +In order to protect users from [XSS vulnerabilities][xss], our intention is to +disable inline scripts entirely using Content Security Policy at some point in +the future. + While inline scripts can be useful, they're also a security concern. If user-supplied content is unintentionally left un-sanitized, malicious users can inject scripts into the site. +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. + +[d3]: https://d3js.org/ +[chartjs]: http://www.chartjs.org/ [chrome-accessibility-developer-tools]: https://github.com/GoogleChrome/accessibility-developer-tools [audit-rules]: https://github.com/GoogleChrome/accessibility-developer-tools/wiki/Audit-Rules +[xss]: https://en.wikipedia.org/wiki/Cross-site_scripting -- cgit v1.2.1 From 79c2f60e9172cb7ce41ae75ae47938d6ceddd4c4 Mon Sep 17 00:00:00 2001 From: Connor Shea Date: Mon, 25 Jul 2016 12:29:43 -0600 Subject: Further revisions/additions [ci skip] --- doc/development/frontend.md | 23 +++++++++++++++++------ 1 file changed, 17 insertions(+), 6 deletions(-) (limited to 'doc/development') diff --git a/doc/development/frontend.md b/doc/development/frontend.md index c2dd130c258..f6ed740a61a 100644 --- a/doc/development/frontend.md +++ b/doc/development/frontend.md @@ -1,7 +1,7 @@ -# Frontend Guidelines +# Frontend Development Guidelines -This document describes various guidelines to follow to ensure good and -consistent performance of GitLab. +This document describes various guidelines to ensure consistency and quality +across GitLab's frontend. ## Performance @@ -20,10 +20,12 @@ 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`. +1. In `graphs_bundle.js` add the line `//= require_tree .`, this adds all other files in the directory to the bundle. +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. 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"`. -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. +1. Move code reliant on these libraries into the `graphs` directory. 1. In the relevant views, add the scripts to the page with the following: ```haml @@ -32,7 +34,9 @@ Steps to split page-specific JavaScript from the main `application.js`: = page_specific_javascript_tag('graphs/graphs_bundle.js') ``` -The above loads `chart.js` and `graphs_bundle.js` for only this page. `chart.js` is separated from the bundle file so it can be cached separately from the bundle and reused for other pages that also rely on the library. +The above loads `chart.js` and `graphs_bundle.js` for only this page. `chart.js` +is separated from the bundle file so it can be cached separately from the bundle +and reused for other pages that also rely on the library. ### Minimizing page size @@ -42,7 +46,7 @@ data is used for users with capped data plans. General tips: -- Don't add fonts that are unnecessary. +- Don't add unnecessary fonts. - Prefer font formats with better compression, e.g. WOFF2 is better than WOFF is better than TFF. - Compress and minify assets wherever possible (For CSS/JS, Sprockets does this for us). - If a piece of functionality can be reasonably done without adding extra libraries, prefer not to use extra libraries. @@ -80,8 +84,15 @@ 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. +## Style Guides and Linting + +See the relevant style guides for details and information on linting: + +- [SCSS][scss-style-guide] + [d3]: https://d3js.org/ [chartjs]: http://www.chartjs.org/ [chrome-accessibility-developer-tools]: https://github.com/GoogleChrome/accessibility-developer-tools [audit-rules]: https://github.com/GoogleChrome/accessibility-developer-tools/wiki/Audit-Rules [xss]: https://en.wikipedia.org/wiki/Cross-site_scripting +[scss-style-guide]: scss_styleguide.md -- cgit v1.2.1 From 3b3e9d17b9f238ba1eab6c0a7e121c92f5f5d5c4 Mon Sep 17 00:00:00 2001 From: Connor Shea Date: Mon, 25 Jul 2016 13:23:19 -0600 Subject: Add CSP and SRI information [ci skip] --- doc/development/frontend.md | 74 +++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 71 insertions(+), 3 deletions(-) (limited to 'doc/development') diff --git a/doc/development/frontend.md b/doc/development/frontend.md index f6ed740a61a..ff75fe14393 100644 --- a/doc/development/frontend.md +++ b/doc/development/frontend.md @@ -13,7 +13,7 @@ libraries increase the page size significantly, and impact load times due to bandwidth bottlenecks and the browser needing to parse more JavaScript. In cases where libraries are only used on a few specific pages, we use -"Page-specific JavaScript" to prevent the main `application.js` file from +"page-specific JavaScript" to prevent the main `application.js` file from becoming unnecessarily large. Steps to split page-specific JavaScript from the main `application.js`: @@ -21,7 +21,7 @@ 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`. 1. In `graphs_bundle.js` add the line `//= require_tree .`, this adds all other files in the directory to the bundle. -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. +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. 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"`. @@ -62,6 +62,62 @@ Accessibility best-practices and more in-depth information is available on ## Security +[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. + + + ### Including external resources External fonts, CSS, and JavaScript should never be used with the exception of @@ -84,7 +140,7 @@ 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. -## Style Guides and Linting +## Style guides and linting See the relevant style guides for details and information on linting: @@ -94,5 +150,17 @@ See the relevant style guides for details and information on linting: [chartjs]: http://www.chartjs.org/ [chrome-accessibility-developer-tools]: https://github.com/GoogleChrome/accessibility-developer-tools [audit-rules]: https://github.com/GoogleChrome/accessibility-developer-tools/wiki/Audit-Rules +[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 [xss]: https://en.wikipedia.org/wiki/Cross-site_scripting [scss-style-guide]: scss_styleguide.md -- cgit v1.2.1 From d4e2c4eff57291157e3990fe412c095d3a7c8de9 Mon Sep 17 00:00:00 2001 From: Connor Shea Date: Wed, 27 Jul 2016 11:21:55 -0600 Subject: Add short Testing section, minor fixes. --- doc/development/frontend.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) (limited to 'doc/development') diff --git a/doc/development/frontend.md b/doc/development/frontend.md index ff75fe14393..05ea10e754c 100644 --- a/doc/development/frontend.md +++ b/doc/development/frontend.md @@ -47,7 +47,7 @@ data is used for users with capped data plans. General tips: - Don't add unnecessary fonts. -- Prefer font formats with better compression, e.g. WOFF2 is better than WOFF is better than TFF. +- Prefer font formats with better compression, e.g. WOFF2 is better than WOFF, which is better than TTF. - Compress and minify assets wherever possible (For CSS/JS, Sprockets does this for us). - If a piece of functionality can be reasonably done without adding extra libraries, prefer not to use extra libraries. - Use page-specific JavaScripts as described above to dynamically load libraries that are only needed on certain pages. @@ -146,6 +146,12 @@ See the relevant style guides for details and information on linting: - [SCSS][scss-style-guide] +## Testing + +Feature tests should be written for all new features as well as any regressions to prevent them from occuring again. + +See [the Testing Standards and Style Guidelines](testing.md) for more information. + [d3]: https://d3js.org/ [chartjs]: http://www.chartjs.org/ [chrome-accessibility-developer-tools]: https://github.com/GoogleChrome/accessibility-developer-tools -- cgit v1.2.1 From 7730ec2d1cc778f45ea65191b37d347f000ffecb Mon Sep 17 00:00:00 2001 From: Connor Shea Date: Wed, 27 Jul 2016 11:51:08 -0600 Subject: Add Overview section detailing our frontend stack. [ci skip] --- doc/development/frontend.md | 49 ++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 44 insertions(+), 5 deletions(-) (limited to 'doc/development') diff --git a/doc/development/frontend.md b/doc/development/frontend.md index 05ea10e754c..cded244c0d4 100644 --- a/doc/development/frontend.md +++ b/doc/development/frontend.md @@ -3,8 +3,28 @@ This document describes various guidelines to ensure consistency and quality across GitLab's frontend. +## Overview + +GitLab is built on top of [Ruby on Rails][rails] using [Haml][haml] (with +[Hamlit][hamlit] for performance reasons, be wary of [the limitations this comes +with][hamlit-limits]), [SCSS][scss], and plain JavaScript with +[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. + ## Performance +### 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. + ### Page-specific JavaScript Certain pages may require the use of a third party library, such as [d3][d3] for @@ -54,6 +74,8 @@ General tips: ## Accessibility +### Resources + The [Chrome Accessibility Developer Tools][chrome-accessibility-developer-tools] are useful for testing for potential accessibility problems in GitLab. @@ -62,6 +84,8 @@ Accessibility best-practices and more in-depth information is available on ## Security +### Resources + [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. @@ -142,16 +166,31 @@ readability. ## Style guides and linting -See the relevant style guides for details and information on linting: +See the relevant style guides for our guidelines and for information on linting: - [SCSS][scss-style-guide] ## Testing -Feature tests should be written for all new features as well as any regressions to prevent them from occuring again. - -See [the Testing Standards and Style Guidelines](testing.md) for more information. - +Feature tests should be written for all new features as well as any regressions +to prevent them from occurring again. + +See [the Testing Standards and Style Guidelines](testing.md) for more +information. + +[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/ +[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/ [d3]: https://d3js.org/ [chartjs]: http://www.chartjs.org/ [chrome-accessibility-developer-tools]: https://github.com/GoogleChrome/accessibility-developer-tools -- cgit v1.2.1 From 059656ad21430c165de57f4de639f5e30e727d4c Mon Sep 17 00:00:00 2001 From: Connor Shea Date: Thu, 4 Aug 2016 14:05:22 -0600 Subject: Add a section on vue and one on supported browsers. --- doc/development/frontend.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) (limited to 'doc/development') diff --git a/doc/development/frontend.md b/doc/development/frontend.md index cded244c0d4..9073a11a2f3 100644 --- a/doc/development/frontend.md +++ b/doc/development/frontend.md @@ -16,6 +16,14 @@ minification, and compression of our assets. [jQuery][jquery] is used throughout the application's JavaScript, with [Vue.js][vue] for particularly advanced, dynamic elements. +### Vue + +For more complex frontend features, we recommend using Vue.js. It shares +some ideas with React.js while being smaller and – arguably – easier to get +into. + +To get started with Vue, read through [their documentation][vue-docs]. + ## Performance ### Resources @@ -178,6 +186,10 @@ to prevent them from occurring again. See [the Testing Standards and Style Guidelines](testing.md) for more information. +## Supported browsers + +For our currently-supported browsers, see our [requirements][requirements]. + [rails]: http://rubyonrails.org/ [haml]: http://haml.info/ [hamlit]: https://github.com/k0kubun/hamlit @@ -187,6 +199,7 @@ information. [sprockets]: https://github.com/rails/sprockets [jquery]: https://jquery.com/ [vue]: http://vuejs.org/ +[vue-docs]: http://vuejs.org/guide/index.html [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 @@ -209,3 +222,4 @@ information. [sprockets-sri]: https://github.com/rails/sprockets-rails#sri-support [xss]: https://en.wikipedia.org/wiki/Cross-site_scripting [scss-style-guide]: scss_styleguide.md +[requirements]: ../install/requirements.md#supported-web-browsers -- cgit v1.2.1 From fc94c637b12eabfbf82452eee331458da7193bd6 Mon Sep 17 00:00:00 2001 From: Connor Shea Date: Sun, 11 Sep 2016 15:12:42 -0600 Subject: Update Frontend Docs based on feedback. --- doc/development/frontend.md | 36 ++++++++++++++++++------------------ 1 file changed, 18 insertions(+), 18 deletions(-) (limited to 'doc/development') diff --git a/doc/development/frontend.md b/doc/development/frontend.md index 9073a11a2f3..f879cd57e25 100644 --- a/doc/development/frontend.md +++ b/doc/development/frontend.md @@ -1,13 +1,13 @@ # Frontend Development Guidelines This document describes various guidelines to ensure consistency and quality -across GitLab's frontend. +across GitLab's frontend team. ## Overview -GitLab is built on top of [Ruby on Rails][rails] using [Haml][haml] (with -[Hamlit][hamlit] for performance reasons, be wary of [the limitations this comes -with][hamlit-limits]), [SCSS][scss], and plain JavaScript with +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 [ES6 by way of Babel][es6]. The asset pipeline is [Sprockets][sprockets], which handles the concatenation, @@ -19,8 +19,7 @@ minification, and compression of our assets. ### Vue For more complex frontend features, we recommend using Vue.js. It shares -some ideas with React.js while being smaller and – arguably – easier to get -into. +some ideas with React.js as well as Angular. To get started with Vue, read through [their documentation][vue-docs]. @@ -62,9 +61,10 @@ Steps to split page-specific JavaScript from the main `application.js`: = page_specific_javascript_tag('graphs/graphs_bundle.js') ``` -The above loads `chart.js` and `graphs_bundle.js` for only this page. `chart.js` +The above loads `chart.js` and `graphs_bundle.js` for this page only. `chart.js` is separated from the bundle file so it can be cached separately from the bundle -and reused for other pages that also rely on the library. +and reused for other pages that also rely on the library. For an example, see +[this Haml file][page-specific-js-example]. ### Minimizing page size @@ -74,17 +74,17 @@ data is used for users with capped data plans. General tips: -- Don't add unnecessary fonts. +- Don't add new fonts. - Prefer font formats with better compression, e.g. WOFF2 is better than WOFF, which is better than TTF. - Compress and minify assets wherever possible (For CSS/JS, Sprockets does this for us). -- If a piece of functionality can be reasonably done without adding extra libraries, prefer not to use extra libraries. -- Use page-specific JavaScripts as described above to dynamically load libraries that are only needed on certain pages. +- 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. ## Accessibility ### Resources -The [Chrome Accessibility Developer Tools][chrome-accessibility-developer-tools] +[Chrome Accessibility Developer Tools][chrome-accessibility-developer-tools] are useful for testing for potential accessibility problems in GitLab. Accessibility best-practices and more in-depth information is available on @@ -160,13 +160,11 @@ such as with ReCaptcha, which cannot be used without an `iframe`. ### Avoiding inline scripts and styles -In order to protect users from [XSS vulnerabilities][xss], our intention is to -disable inline scripts entirely using Content Security Policy at some point in -the future. +In order to protect users from [XSS vulnerabilities][xss], we will disable inline scripts in the future using Content Security Policy. While inline scripts can be useful, they're also a security concern. If user-supplied content is unintentionally left un-sanitized, malicious users can -inject scripts into the site. +inject scripts into the web app. 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 @@ -180,8 +178,9 @@ See the relevant style guides for our guidelines and for information on linting: ## Testing -Feature tests should be written for all new features as well as any regressions -to prevent them from occurring again. +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. See [the Testing Standards and Style Guidelines](testing.md) for more information. @@ -206,6 +205,7 @@ For our currently-supported browsers, see our [requirements][requirements]. [browser-diet]: https://browserdiet.com/ [d3]: https://d3js.org/ [chartjs]: http://www.chartjs.org/ +[page-specific-js-example]: https://gitlab.com/gitlab-org/gitlab-ce/blob/13bb9ed77f405c5f6ee4fdbc964ecf635c9a223f/app/views/projects/graphs/_head.html.haml#L6-8 [chrome-accessibility-developer-tools]: https://github.com/GoogleChrome/accessibility-developer-tools [audit-rules]: https://github.com/GoogleChrome/accessibility-developer-tools/wiki/Audit-Rules [observatory-cli]: https://github.com/mozilla/http-observatory-cli) -- cgit v1.2.1 From 1553275ebc5ecccda208c1138755edf9b3198700 Mon Sep 17 00:00:00 2001 From: Matt Lee Date: Thu, 29 Sep 2016 17:00:21 -0400 Subject: Added CC0 license to list of licenses --- doc/development/licensing.md | 2 ++ 1 file changed, 2 insertions(+) (limited to 'doc/development') diff --git a/doc/development/licensing.md b/doc/development/licensing.md index 8c8c7486fff..05972b33fdb 100644 --- a/doc/development/licensing.md +++ b/doc/development/licensing.md @@ -54,6 +54,7 @@ Libraries with the following licenses are acceptable for use: - [BSD 2-Clause License][BSD-2-Clause]: A permissive (non-copyleft) license as defined by the Open Source Initiative. - [BSD 3-Clause License][BSD-3-Clause] (also known as New BSD or Modified BSD): A permissive (non-copyleft) license as defined by the Open Source Initiative - [ISC License][ISC] (also known as the OpenBSD License): A permissive (non-copyleft) license as defined by the Open Source Initiative. +- [Creative Commons Zero (CC0)][CC0]: A public domain dedication, recommended as a way to disclaim copyright on your work to the maximum extent possible. ## Unacceptable Licenses @@ -85,6 +86,7 @@ Gems which are included only in the "development" or "test" groups by Bundler ar [BSD-2-Clause]: https://opensource.org/licenses/BSD-2-Clause [BSD-3-Clause]: https://opensource.org/licenses/BSD-3-Clause [ISC]: https://opensource.org/licenses/ISC +[CC0]: https://creativecommons.org/publicdomain/zero/1.0/ [GPL]: http://choosealicense.com/licenses/gpl-3.0/ [GPLv2]: http://www.gnu.org/licenses/gpl-2.0.txt [GPLv3]: http://www.gnu.org/licenses/gpl-3.0.txt -- cgit v1.2.1 From 267a96f3d42c1cdd38fc1424fe2e53ede8bd9950 Mon Sep 17 00:00:00 2001 From: Nick Thomas Date: Sun, 2 Oct 2016 12:32:30 +0100 Subject: Link to the "What requires downtime?" page from the Migration Style Guide [ci skip] --- doc/development/migration_style_guide.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'doc/development') diff --git a/doc/development/migration_style_guide.md b/doc/development/migration_style_guide.md index 295eae0a88e..61b0fbc89c9 100644 --- a/doc/development/migration_style_guide.md +++ b/doc/development/migration_style_guide.md @@ -9,10 +9,10 @@ a big burden for most organizations. For this reason it is important that your migrations are written carefully, can be applied online and adhere to the style guide below. Migrations should not require GitLab installations to be taken offline unless -_absolutely_ necessary. If a migration requires downtime this should be -clearly mentioned during the review process as well as being documented in the -monthly release post. For more information see the "Downtime Tagging" section -below. +_absolutely_ necessary - see the ["What Requires Downtime?"](what_requires_downtime.md) +page. If a migration requires downtime, this should be clearly mentioned during +the review process, as well as being documented in the monthly release post. For +more information, see the "Downtime Tagging" section below. When writing your migrations, also consider that databases might have stale data or inconsistencies and guard for that. Try to make as little assumptions as possible -- cgit v1.2.1 From 2f7e28d1f700e1cdafb7771d4a61d8f71b68df04 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=C3=A9my=20Coutable?= Date: Fri, 7 Oct 2016 15:28:15 +0200 Subject: Improve the contribution and MR review guide MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Rémy Coutable --- doc/development/code_review.md | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'doc/development') diff --git a/doc/development/code_review.md b/doc/development/code_review.md index 40ae55ab905..98279948888 100644 --- a/doc/development/code_review.md +++ b/doc/development/code_review.md @@ -34,6 +34,10 @@ request is up to one of our merge request "endbosses", denoted on the ## Having your code reviewed +Please keep in mind that code review is a process that can take multiple +iterations, and reviewer may spot things later that they may not have seen the +first time. + - The first reviewer of your code is _you_. Before you perform that first push of your shiny new branch, read through the entire diff. Does it make sense? Did you include something unrelated to the overall purpose of the changes? Did @@ -55,6 +59,7 @@ request is up to one of our merge request "endbosses", denoted on the Understand why the change is necessary (fixes a bug, improves the user experience, refactors the existing code). Then: +- Try to be thorough in your reviews to reduce the number of iterations. - Communicate which ideas you feel strongly about and those you don't. - Identify ways to simplify the code while still solving the problem. - Offer alternative implementations, but assume the author already considered @@ -66,6 +71,8 @@ experience, refactors the existing code). Then: "LGTM :thumbsup:", or "Just a couple things to address." - Avoid accepting a merge request before the build succeeds ("Merge when build succeeds" is fine). +- If you set the MR to "Merge when build succeeds", you should take over + subsequent revisions for anything that would be spotted after that. ## Credits -- cgit v1.2.1 From 52ca9bf600235459721fbcf16e4f582b839b3b37 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=C3=A9my=20Coutable?= Date: Fri, 7 Oct 2016 16:17:28 +0200 Subject: Fix typo and add he MWBS accronym for "Merge When Build Succeeds" MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Rémy Coutable --- doc/development/code_review.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'doc/development') diff --git a/doc/development/code_review.md b/doc/development/code_review.md index 98279948888..c5c23b5c0b8 100644 --- a/doc/development/code_review.md +++ b/doc/development/code_review.md @@ -35,7 +35,7 @@ request is up to one of our merge request "endbosses", denoted on the ## Having your code reviewed Please keep in mind that code review is a process that can take multiple -iterations, and reviewer may spot things later that they may not have seen the +iterations, and reviewers may spot things later that they may not have seen the first time. - The first reviewer of your code is _you_. Before you perform that first push @@ -69,9 +69,9 @@ experience, refactors the existing code). Then: someone else would be confused by it as well. - After a round of line notes, it can be helpful to post a summary note such as "LGTM :thumbsup:", or "Just a couple things to address." -- Avoid accepting a merge request before the build succeeds ("Merge when build - succeeds" is fine). -- If you set the MR to "Merge when build succeeds", you should take over +- Avoid accepting a merge request before the build succeeds. Of course, "Merge + When Build Succeeds" (MWBS) is fine. +- If you set the MR to "Merge When Build Succeeds", you should take over subsequent revisions for anything that would be spotted after that. ## Credits -- cgit v1.2.1 From ce8aedf030f0980b3712a3b0090b918fa1451a2d Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Tue, 11 Oct 2016 15:06:46 +0200 Subject: Add examples of fake tokens to be used in docs [ci skip] --- doc/development/doc_styleguide.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) (limited to 'doc/development') diff --git a/doc/development/doc_styleguide.md b/doc/development/doc_styleguide.md index 39b801f761d..0b725cf200c 100644 --- a/doc/development/doc_styleguide.md +++ b/doc/development/doc_styleguide.md @@ -314,6 +314,29 @@ In this case: - different highlighting languages are used for each config in the code block - the [references](#references) guide is used for reconfigure/restart +## Fake tokens + +There may be times where a token is needed to demonstrate an API call using +cURL or a secret variable used in CI. It is strongly advised not to use real +tokens in documentation even if the probability of a token being exploited is +low. + +You can use the following fake tokens as examples. + +| **Token type** | **Token value** | +| --------------------- | --------------------------------- | +| Private user token | `9koXpg98eAheJpvBs5tK` | +| Personal access token | `n671WNGecHugsdEDPsyo` | +| Application ID | `2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6` | +| Application secret | `04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df` | +| Secret CI variable | `Li8j-mLUVA3eZYjPfd_H` | +| Specific Runner token | `yrnZW46BrtBFqM7xDzE7dddd` | +| Shared Runner token | `6Vk7ZsosqQyfreAxXTZr` | +| Trigger token | `be20d8dcc028677c931e04f3871a9b` | +| Webhook secret token | `6XhDroRcYPM5by_h-HLY` | +| Health check token | `Tu7BgjR9qeZTEyRzGG2P` | +| Request profile token | `7VgpS4Ax5utVD2esNstz` | + ## API Here is a list of must-have items. Use them in the exact order that appears -- cgit v1.2.1 From abfb4f6e32ac13929678039e324307ee3ef2af43 Mon Sep 17 00:00:00 2001 From: Bryce Johnson Date: Wed, 12 Oct 2016 19:00:38 +0200 Subject: Document Capybara errors from es6 in es5 file. --- doc/development/frontend.md | 11 +++++++++++ 1 file changed, 11 insertions(+) (limited to 'doc/development') diff --git a/doc/development/frontend.md b/doc/development/frontend.md index f879cd57e25..56c8516508e 100644 --- a/doc/development/frontend.md +++ b/doc/development/frontend.md @@ -223,3 +223,14 @@ For our currently-supported browsers, see our [requirements][requirements]. [xss]: https://en.wikipedia.org/wiki/Cross-site_scripting [scss-style-guide]: scss_styleguide.md [requirements]: ../install/requirements.md#supported-web-browsers + +## Common Errors + +### Rspec (Capybara/Poltergeist) chokes on general JavaScript errors + +If you see very generic JavaScript errors (e.g. `jQuery is undefined`) being thrown in tests, but +can't reproduce them manually, you may have included `ES6`-style JavaScript in files that don't +have the `.js.es6` file extension. Either use ES5-friendly JavaScript or rename the file you're +working in (`git mv .js> `). + + -- cgit v1.2.1 From cb7872c3a0c789f9e906492098bb7d643f135e52 Mon Sep 17 00:00:00 2001 From: Dmitriy Zaporozhets Date: Thu, 13 Oct 2016 14:24:09 +0300 Subject: Remove /u/ prefix from user pages in documentation Signed-off-by: Dmitriy Zaporozhets --- doc/development/performance.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/development') diff --git a/doc/development/performance.md b/doc/development/performance.md index 7ff603e2c4a..a00c0fe07b5 100644 --- a/doc/development/performance.md +++ b/doc/development/performance.md @@ -253,5 +253,5 @@ impact on runtime performance, and as such, using a constant instead of referencing an object directly may even slow code down. [#15607]: https://gitlab.com/gitlab-org/gitlab-ce/issues/15607 -[yorickpeterse]: https://gitlab.com/u/yorickpeterse +[yorickpeterse]: https://gitlab.com/yorickpeterse [anti-pattern]: https://en.wikipedia.org/wiki/Anti-pattern -- cgit v1.2.1 From b2c771f45261e1484158d1304cd898e866002f07 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=C3=A9my=20Coutable?= Date: Thu, 13 Oct 2016 18:44:52 +0200 Subject: Add an API styleguide MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Rémy Coutable --- doc/development/README.md | 2 ++ doc/development/api_styleguide.md | 58 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 60 insertions(+) create mode 100644 doc/development/api_styleguide.md (limited to 'doc/development') diff --git a/doc/development/README.md b/doc/development/README.md index 9706cb1de7f..630fe64cee6 100644 --- a/doc/development/README.md +++ b/doc/development/README.md @@ -8,6 +8,8 @@ ## Styleguides +- [API styleguide](api_styleguide.md) Use this styleguide if you are + contributing to the API. - [Documentation styleguide](doc_styleguide.md) Use this styleguide if you are contributing to documentation. - [SQL Migration Style Guide](migration_style_guide.md) for creating safe SQL migrations diff --git a/doc/development/api_styleguide.md b/doc/development/api_styleguide.md new file mode 100644 index 00000000000..ee5e7ad3988 --- /dev/null +++ b/doc/development/api_styleguide.md @@ -0,0 +1,58 @@ +# API styleguide + +This styleguide recommends best practices for the API development. + +## Declared params + +> Grape allows you to access only the parameters that have been declared by your +`params` block. It filters out the params that have been passed, but are not +allowed. + +– https://github.com/ruby-grape/grape#declared + +### Exclude params from parent namespaces + +> By default `declared(params) `includes parameters that were defined in all +parent namespaces. + +– https://github.com/ruby-grape/grape#include-parent-namespaces + +In most cases you will want to exclude params from the parent namespaces: + +```ruby +declared(params, include_parent_namespaces: false) +``` + +### When to use `declared(params)`? + +You should always use `declared(params)` when you pass the params hash as +arguments to a method call. + +For instance: + +```ruby +# bad +User.create(params) # imagine the user submitted `admin=1`... :) + +# good +User.create(declared(params, include_parent_namespaces: false).to_h) +``` + +>**Note:** +`declared(params)` return a `Hashie::Mash` object, on which you will have to +call `.to_h`. + +But we can use directly `params[key]` when we access single elements. + +For instance: + +```ruby +# good +Model.create(foo: params[:foo]) +``` + +>**Note:** +Since you [should use Grape's DSL to declare params](doc_styleguide.md#method-description), [parameters validation and +coercion] comes for free! + +[parameters validation and coercion]: https://github.com/ruby-grape/grape#parameter-validation-and-coercion -- cgit v1.2.1 From c1dd1795ed57c9481a1a9cab81daef39dd218346 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=C3=A9my=20Coutable?= Date: Thu, 13 Oct 2016 19:35:57 +0200 Subject: Move the Grape DSL part from Doc styleguide to API styleguide MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Also improve API styleguide Signed-off-by: Rémy Coutable --- doc/development/api_styleguide.md | 48 +++++++++++++++++++++++++++++++++++---- doc/development/doc_styleguide.md | 6 ----- 2 files changed, 43 insertions(+), 11 deletions(-) (limited to 'doc/development') diff --git a/doc/development/api_styleguide.md b/doc/development/api_styleguide.md index ee5e7ad3988..be303fc6d39 100644 --- a/doc/development/api_styleguide.md +++ b/doc/development/api_styleguide.md @@ -2,6 +2,47 @@ This styleguide recommends best practices for the API development. +## Instance variables + +Please do not use instance variables, there is no need for them (we don't need +to access them as we do in Rails views), local variables are fine. + +## Entities + +Always use an [Entity] to present the endpoint's payload. + +## Methods and parameters description + +Every method must be described using the [Grape DSL](https://github.com/ruby-grape/grape#describing-methods) +(see https://gitlab.com/gitlab-org/gitlab-ce/blob/master/lib/api/environments.rb +for a good example): + +- `desc` for the method summary. You should pass it a block for additional + details such as: + - The GitLab version when the endpoint was added + - If the endpoint is deprecated, and if yes when will it be removed + +- `params` for the method params. This acts as description, validation, and + coercion of the parameters + +A good example is as follows: + +```ruby +desc 'Get all broadcast messages' do + detail 'This feature was introduced in GitLab 8.12.' + success Entities::BroadcastMessage +end +params do + optional :page, type: Integer, desc: 'Current page number' + optional :per_page, type: Integer, desc: 'Number of messages per page' +end +get do + messages = BroadcastMessage.all + + present paginate(messages), with: Entities::BroadcastMessage +end +``` + ## Declared params > Grape allows you to access only the parameters that have been declared by your @@ -10,7 +51,7 @@ allowed. – https://github.com/ruby-grape/grape#declared -### Exclude params from parent namespaces +### Exclude params from parent namespaces! > By default `declared(params) `includes parameters that were defined in all parent namespaces. @@ -51,8 +92,5 @@ For instance: Model.create(foo: params[:foo]) ``` ->**Note:** -Since you [should use Grape's DSL to declare params](doc_styleguide.md#method-description), [parameters validation and -coercion] comes for free! - +[Entity]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/lib/api/entities.rb [parameters validation and coercion]: https://github.com/ruby-grape/grape#parameter-validation-and-coercion diff --git a/doc/development/doc_styleguide.md b/doc/development/doc_styleguide.md index 0b725cf200c..882da2a6562 100644 --- a/doc/development/doc_styleguide.md +++ b/doc/development/doc_styleguide.md @@ -342,12 +342,6 @@ You can use the following fake tokens as examples. Here is a list of must-have items. Use them in the exact order that appears on this document. Further explanation is given below. -- Every method must be described using [Grape's DSL](https://github.com/ruby-grape/grape/tree/v0.13.0#describing-methods) - (see https://gitlab.com/gitlab-org/gitlab-ce/blob/master/lib/api/environments.rb - for a good example): - - `desc` for the method summary (you can pass it a block for additional details) - - `params` for the method params (this acts as description **and** validation - of the params) - Every method must have the REST API request. For example: ``` -- cgit v1.2.1 From 3a1d9bccd6c3ce8249e90153f4299db1c037eb56 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=C3=A9my=20Coutable?= Date: Thu, 13 Oct 2016 19:38:38 +0200 Subject: Fix typo MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Rémy Coutable --- doc/development/api_styleguide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/development') diff --git a/doc/development/api_styleguide.md b/doc/development/api_styleguide.md index be303fc6d39..94047dfe173 100644 --- a/doc/development/api_styleguide.md +++ b/doc/development/api_styleguide.md @@ -1,6 +1,6 @@ # API styleguide -This styleguide recommends best practices for the API development. +This styleguide recommends best practices for API development. ## Instance variables -- cgit v1.2.1 From b4810fd2bce42d66cada56af3ef697219f176b87 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=C3=A9my=20Coutable?= Date: Thu, 13 Oct 2016 19:40:20 +0200 Subject: More improvements MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Rémy Coutable --- doc/development/api_styleguide.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'doc/development') diff --git a/doc/development/api_styleguide.md b/doc/development/api_styleguide.md index 94047dfe173..2a41314d2db 100644 --- a/doc/development/api_styleguide.md +++ b/doc/development/api_styleguide.md @@ -22,8 +22,8 @@ for a good example): - The GitLab version when the endpoint was added - If the endpoint is deprecated, and if yes when will it be removed -- `params` for the method params. This acts as description, validation, and - coercion of the parameters +- `params` for the method params. This acts as description, + [validation, and coercion of the parameters] A good example is as follows: @@ -93,4 +93,4 @@ Model.create(foo: params[:foo]) ``` [Entity]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/lib/api/entities.rb -[parameters validation and coercion]: https://github.com/ruby-grape/grape#parameter-validation-and-coercion +[validation, and coercion of the parameters]: https://github.com/ruby-grape/grape#parameter-validation-and-coercion -- cgit v1.2.1 From c180221a5b0e58c42632412d2084efc3bd4cda99 Mon Sep 17 00:00:00 2001 From: Ahmad Sherif Date: Fri, 14 Oct 2016 19:49:36 +0200 Subject: Add docs for request profiling Closes #23239 --- doc/development/performance.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'doc/development') diff --git a/doc/development/performance.md b/doc/development/performance.md index 7ff603e2c4a..65d34829025 100644 --- a/doc/development/performance.md +++ b/doc/development/performance.md @@ -34,10 +34,11 @@ graphs/dashboards. ## Tooling -GitLab provides two built-in tools to aid the process of improving performance: +GitLab provides built-in tools to aid the process of improving performance: * [Sherlock](profiling.md#sherlock) * [GitLab Performance Monitoring](../monitoring/performance/monitoring.md) +* [Request Profiling](../administration/monitoring/performance/request_profiling.md) GitLab employees can use GitLab.com's performance monitoring systems located at , this requires you to log in using your -- cgit v1.2.1 From 54c0286a3f7306f8e5bfbbbf321cd098e4fc6e11 Mon Sep 17 00:00:00 2001 From: De Wet Blomerus Date: Fri, 14 Oct 2016 21:03:27 +0200 Subject: remove ashley since she no longer works here --- doc/development/doc_styleguide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/development') diff --git a/doc/development/doc_styleguide.md b/doc/development/doc_styleguide.md index 0b725cf200c..975ff9a4612 100644 --- a/doc/development/doc_styleguide.md +++ b/doc/development/doc_styleguide.md @@ -96,7 +96,7 @@ merge request. - When introducing a new document, be careful for the headings to be grammatically and syntactically correct. It is advised to mention one or all of the following GitLab members for a review: `@axil`, `@rspeicher`, - `@dblessing`, `@ashleys`. This is to ensure that no document + `@dblessing`. This is to ensure that no document with wrong heading is going live without an audit, thus preventing dead links and redirection issues when corrected - Leave exactly one newline after a heading -- cgit v1.2.1 From 5174b7ad7e4b90761467388a29fa016d77e7a16d Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Sun, 16 Oct 2016 11:35:51 +0200 Subject: Add the tech writers usernames in the doc_sytleguide doc [ci skip] --- doc/development/doc_styleguide.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'doc/development') diff --git a/doc/development/doc_styleguide.md b/doc/development/doc_styleguide.md index 0b725cf200c..47ebcebc770 100644 --- a/doc/development/doc_styleguide.md +++ b/doc/development/doc_styleguide.md @@ -95,10 +95,10 @@ merge request. someone in the Merge Request - When introducing a new document, be careful for the headings to be grammatically and syntactically correct. It is advised to mention one or all - of the following GitLab members for a review: `@axil`, `@rspeicher`, - `@dblessing`, `@ashleys`. This is to ensure that no document - with wrong heading is going live without an audit, thus preventing dead links - and redirection issues when corrected + of the following GitLab members for a review: `@axil`, `@rspeicher`, `@marcia`, + `@SeanPackham`. This is to ensure that no document with wrong heading is going + live without an audit, thus preventing dead links and redirection issues when + corrected - Leave exactly one newline after a heading ## Links -- cgit v1.2.1 From 11e40c0e26e07d153cd2712bf23b5d679b54615c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=C3=A9my=20Coutable?= Date: Mon, 17 Oct 2016 10:10:13 +0200 Subject: Improve copy MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Rémy Coutable --- doc/development/api_styleguide.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'doc/development') diff --git a/doc/development/api_styleguide.md b/doc/development/api_styleguide.md index 2a41314d2db..ce444ebdde4 100644 --- a/doc/development/api_styleguide.md +++ b/doc/development/api_styleguide.md @@ -20,7 +20,7 @@ for a good example): - `desc` for the method summary. You should pass it a block for additional details such as: - The GitLab version when the endpoint was added - - If the endpoint is deprecated, and if yes when will it be removed + - If the endpoint is deprecated, and if so, when will it be removed - `params` for the method params. This acts as description, [validation, and coercion of the parameters] @@ -83,7 +83,7 @@ User.create(declared(params, include_parent_namespaces: false).to_h) `declared(params)` return a `Hashie::Mash` object, on which you will have to call `.to_h`. -But we can use directly `params[key]` when we access single elements. +But we can use `params[key]` directly when we access single elements. For instance: -- cgit v1.2.1 From 97731760d7252acf8ee94c707c0e107492b1ef24 Mon Sep 17 00:00:00 2001 From: Yorick Peterse Date: Fri, 21 Oct 2016 18:13:41 +0200 Subject: Re-organize queues to use for Sidekiq Dumping too many jobs in the same queue (e.g. the "default" queue) is a dangerous setup. Jobs that take a long time to process can effectively block any other work from being performed given there are enough of these jobs. Furthermore it becomes harder to monitor the jobs as a single queue could contain jobs for different workers. In such a setup the only reliable way of getting counts per job is to iterate over all jobs in a queue, which is a rather time consuming process. By using separate queues for various workers we have better control over throughput, we can add weight to queues, and we can monitor queues better. Some workers still use the same queue whenever their work is related. For example, the various CI pipeline workers use the same "pipeline" queue. This commit includes a Rails migration that moves Sidekiq jobs from the old queues to the new ones. This migration also takes care of doing the inverse if ever needed. This does require downtime as otherwise new jobs could be scheduled in the old queues after this migration completes. This commit also includes an RSpec test that blacklists the use of the "default" queue and ensures cron workers use the "cronjob" queue. Fixes gitlab-org/gitlab-ce#23370 --- doc/development/README.md | 3 ++- doc/development/sidekiq_style_guide.md | 38 ++++++++++++++++++++++++++++++++++ 2 files changed, 40 insertions(+), 1 deletion(-) create mode 100644 doc/development/sidekiq_style_guide.md (limited to 'doc/development') diff --git a/doc/development/README.md b/doc/development/README.md index 9706cb1de7f..fb6a8a5b095 100644 --- a/doc/development/README.md +++ b/doc/development/README.md @@ -14,7 +14,8 @@ - [Testing standards and style guidelines](testing.md) - [UI guide](ui_guide.md) for building GitLab with existing CSS styles and elements - [Frontend guidelines](frontend.md) -- [SQL guidelines](sql.md) for SQL guidelines +- [SQL guidelines](sql.md) for working with SQL queries +- [Sidekiq guidelines](sidekiq_style_guide.md) for working with Sidekiq workers ## Process diff --git a/doc/development/sidekiq_style_guide.md b/doc/development/sidekiq_style_guide.md new file mode 100644 index 00000000000..e3a20f29a09 --- /dev/null +++ b/doc/development/sidekiq_style_guide.md @@ -0,0 +1,38 @@ +# Sidekiq Style Guide + +This document outlines various guidelines that should be followed when adding or +modifying Sidekiq workers. + +## Default Queue + +Use of the "default" queue is not allowed. Every worker should use a queue that +matches the worker's purpose the closest. For example, workers that are to be +executed periodically should use the "cronjob" queue. + +A list of all available queues can be found in `config/sidekiq_queues.yml`. + +## Dedicated Queues + +Most workers should use their own queue. To ease this process a worker can +include the `DedicatedSidekiqQueue` concern as follows: + +```ruby +class ProcessSomethingWorker + include Sidekiq::Worker + include DedicatedSidekiqQueue +end +``` + +This will set the queue name based on the class' name, minus the `Worker` +suffix. In the above example this would lead to the queue being +`process_something`. + +In some cases multiple workers do use the same queue. For example, the various +workers for updating CI pipelines all use the `pipeline` queue. Adding workers +to existing queues should be done with care, as adding more workers can lead to +slow jobs blocking work (even for different jobs) on the shared queue. + +## Tests + +Each Sidekiq worker must be tested using RSpec, just like any other class. These +tests should be placed in `spec/workers`. -- cgit v1.2.1 From 8b7634c2b665f6c3dc8b0f82b870fd2032f7d247 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Mon, 24 Oct 2016 16:45:00 +0200 Subject: Fix old monitoring links to point to the new location --- doc/development/performance.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/development') diff --git a/doc/development/performance.md b/doc/development/performance.md index c4a964d1da3..8337c2d9cb3 100644 --- a/doc/development/performance.md +++ b/doc/development/performance.md @@ -37,7 +37,7 @@ graphs/dashboards. GitLab provides built-in tools to aid the process of improving performance: * [Sherlock](profiling.md#sherlock) -* [GitLab Performance Monitoring](../monitoring/performance/monitoring.md) +* [GitLab Performance Monitoring](../administration/monitoring/performance/monitoring.md) * [Request Profiling](../administration/monitoring/performance/request_profiling.md) GitLab employees can use GitLab.com's performance monitoring systems located at -- cgit v1.2.1 From f285f4790ff4a2188fbac75fc4a70b7f31c740bb Mon Sep 17 00:00:00 2001 From: Bryce Johnson Date: Tue, 25 Oct 2016 16:30:14 +0000 Subject: Add ES array methods as cause of Phantom.js errors. --- doc/development/frontend.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) (limited to 'doc/development') diff --git a/doc/development/frontend.md b/doc/development/frontend.md index 56c8516508e..54890989ea1 100644 --- a/doc/development/frontend.md +++ b/doc/development/frontend.md @@ -224,13 +224,18 @@ For our currently-supported browsers, see our [requirements][requirements]. [scss-style-guide]: scss_styleguide.md [requirements]: ../install/requirements.md#supported-web-browsers -## Common Errors +## Gotchas -### Rspec (Capybara/Poltergeist) chokes on general JavaScript errors +### Phantom.JS (used by Teaspoon & Rspec) chokes, returning vague JavaScript errors If you see very generic JavaScript errors (e.g. `jQuery is undefined`) being thrown in tests, but can't reproduce them manually, you may have included `ES6`-style JavaScript in files that don't have the `.js.es6` file extension. Either use ES5-friendly JavaScript or rename the file you're -working in (`git mv .js> `). +working in (`git mv `). + +Similar errors will be thrown if you're using +any of the [array methods introduced in ES6](http://www.2ality.com/2014/05/es6-array-methods.html) +whether or not you've updated the file extension. + -- cgit v1.2.1 From 69ab287b360f89edecb7a410e4de823b43878b51 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Thu, 27 Oct 2016 08:26:35 +0200 Subject: Add note about ephemeral statuses in headings [ci skip] --- doc/development/doc_styleguide.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'doc/development') diff --git a/doc/development/doc_styleguide.md b/doc/development/doc_styleguide.md index 4cc581dd991..2cfa30f652e 100644 --- a/doc/development/doc_styleguide.md +++ b/doc/development/doc_styleguide.md @@ -93,6 +93,8 @@ merge request. links shift too, which eventually leads to dead links. If you think it is compelling to add numbers in headings, make sure to at least discuss it with someone in the Merge Request +- Avoid adding things that show ephemeral statuses. For example, if a feature is + considered beta or experimental, put this info in a note, not in the heading. - When introducing a new document, be careful for the headings to be grammatically and syntactically correct. It is advised to mention one or all of the following GitLab members for a review: `@axil`, `@rspeicher`, `@marcia`, @@ -466,4 +468,4 @@ curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --data "domain [doc-restart]: ../administration/restart_gitlab.md "GitLab restart documentation" [ce-3349]: https://gitlab.com/gitlab-org/gitlab-ce/issues/3349 "Documentation restructure" [graffle]: https://gitlab.com/gitlab-org/gitlab-design/blob/d8d39f4a87b90fb9ae89ca12dc565347b4900d5e/production/resources/gitlab-map.graffle -[gitlab-map]: https://gitlab.com/gitlab-org/gitlab-design/raw/master/production/resources/gitlab-map.png \ No newline at end of file +[gitlab-map]: https://gitlab.com/gitlab-org/gitlab-design/raw/master/production/resources/gitlab-map.png -- cgit v1.2.1 From cd3c8e9b1279dce29c5283b54d9b3305be73110f Mon Sep 17 00:00:00 2001 From: Winnie Date: Thu, 27 Oct 2016 13:15:54 +0000 Subject: Document how to run frontend tests --- doc/development/frontend.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) (limited to 'doc/development') diff --git a/doc/development/frontend.md b/doc/development/frontend.md index 56c8516508e..4fb56444917 100644 --- a/doc/development/frontend.md +++ b/doc/development/frontend.md @@ -185,6 +185,20 @@ again in the future. See [the Testing Standards and Style Guidelines](testing.md) for more information. +### Running frontend tests + +`rake teaspoon` runs the frontend-only (JavaScript) tests. +It consists of two subtasks: + +- `rake teaspoon:fixtures` (re-)generates fixtures +- `rake teaspoon:tests` actually executes the tests + +As long as the fixtures don't change, `rake teaspoon:tests` is sufficient +(and saves you some time). + +Please note: Not all of the frontend fixtures are generated. Some are still static +files. These will not be touched by `rake teaspoon:fixtures`. + ## Supported browsers For our currently-supported browsers, see our [requirements][requirements]. -- cgit v1.2.1 From 5fb226a934b07b214dcbd6711f1068866c0c1dae Mon Sep 17 00:00:00 2001 From: Bryce Johnson Date: Thu, 27 Oct 2016 19:09:58 +0200 Subject: Remove leftover references to coffeescript from comments and docs. --- doc/development/gotchas.md | 6 ++---- doc/development/testing.md | 4 ++-- 2 files changed, 4 insertions(+), 6 deletions(-) (limited to 'doc/development') diff --git a/doc/development/gotchas.md b/doc/development/gotchas.md index 159d5ce286d..b25ce79e89f 100644 --- a/doc/development/gotchas.md +++ b/doc/development/gotchas.md @@ -41,9 +41,9 @@ Rubocop](https://gitlab.com/gitlab-org/gitlab-ce/blob/8-4-stable/.rubocop.yml#L9 [Exception]: http://stackoverflow.com/q/10048173/223897 -## Don't use inline CoffeeScript/JavaScript in views +## Don't use inline JavaScript in views -Using the inline `:coffee` or `:coffeescript` Haml filters comes with a +Using the inline `:javascript` Haml filters comes with a performance overhead. Using inline JavaScript is not a good way to structure your code and should be avoided. _**Note:** We've [removed these two filters](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/config/initializers/hamlit.rb) @@ -51,9 +51,7 @@ in an initializer._ ### Further reading -- Pull Request: [Replace CoffeeScript block into JavaScript in Views](https://git.io/vztMu) - Stack Overflow: [Why you should not write inline JavaScript](http://programmers.stackexchange.com/questions/86589/why-should-i-avoid-inline-scripting) -- Stack Overflow: [Performance implications of using :coffescript filter inside HAML templates?](http://stackoverflow.com/a/17571242/223897) ## ID-based CSS selectors need to be a bit more specific diff --git a/doc/development/testing.md b/doc/development/testing.md index 513457d203a..8e91ac5e3ba 100644 --- a/doc/development/testing.md +++ b/doc/development/testing.md @@ -36,8 +36,8 @@ the command line via `bundle exec teaspoon`, or via a web browser at `http://localhost:3000/teaspoon` when the Rails server is running. - JavaScript tests live in `spec/javascripts/`, matching the folder structure of - `app/assets/javascripts/`: `app/assets/javascripts/behaviors/autosize.js.coffee` has a corresponding - `spec/javascripts/behaviors/autosize_spec.js.coffee` file. + `app/assets/javascripts/`: `app/assets/javascripts/behaviors/autosize.js.es6` has a corresponding + `spec/javascripts/behaviors/autosize_spec.js.es6` file. - Haml fixtures required for JavaScript tests live in `spec/javascripts/fixtures`. They should contain the bare minimum amount of markup necessary for the test. -- cgit v1.2.1 From 83c8241160ed48ab066e2c5bd58d0914a745197c Mon Sep 17 00:00:00 2001 From: Yorick Peterse Date: Thu, 27 Oct 2016 14:36:53 +0200 Subject: Support for post deployment migrations These are regular Rails migrations that are executed by default. A user can opt-out of these migrations by setting an environment variable during the deployment process. Fixes gitlab-org/gitlab-ce#22133 --- doc/development/README.md | 1 + doc/development/post_deployment_migrations.md | 75 +++++++++++++++++++++++++++ 2 files changed, 76 insertions(+) create mode 100644 doc/development/post_deployment_migrations.md (limited to 'doc/development') diff --git a/doc/development/README.md b/doc/development/README.md index 14d6f08e43a..3f2151bbe8e 100644 --- a/doc/development/README.md +++ b/doc/development/README.md @@ -41,6 +41,7 @@ - [What requires downtime?](what_requires_downtime.md) - [Adding database indexes](adding_database_indexes.md) +- [Post Deployment Migrations](post_deployment_migrations.md) ## Compliance diff --git a/doc/development/post_deployment_migrations.md b/doc/development/post_deployment_migrations.md new file mode 100644 index 00000000000..cfc91539bee --- /dev/null +++ b/doc/development/post_deployment_migrations.md @@ -0,0 +1,75 @@ +# Post Deployment Migrations + +Post deployment migrations are regular Rails migrations that can optionally be +executed after a deployment. By default these migrations are executed alongside +the other migrations. To skip these migrations you will have to set the +environment variable `SKIP_POST_DEPLOYMENT_MIGRATIONS` to a non-empty value +when running `rake db:migrate`. + +For example, this would run all migrations including any post deployment +migrations: + +```bash +bundle exec rake db:migrate +``` + +This however will skip post deployment migrations: + +```bash +SKIP_POST_DEPLOYMENT_MIGRATIONS=true bundle exec rake db:migrate +``` + +## Deployment Integration + +Say you're using Chef for deploying new versions of GitLab and you'd like to run +post deployment migrations after deploying a new version. Let's assume you +normally use the command `chef-client` to do so. To make use of this feature +you'd have to run this command as follows: + +```bash +SKIP_POST_DEPLOYMENT_MIGRATIONS=true sudo chef-client +``` + +Once all servers have been updated you can run `chef-client` again on a single +server _without_ the environment variable. + +The process is similar for other deployment techniques: first you would deploy +with the environment variable set, then you'll essentially re-deploy a single +server but with the variable _unset_. + +## Creating Migrations + +To create a post deployment migration you can use the following Rails generator: + +```bash +bundle exec rails g post_deployment_migration migration_name_here +``` + +This will generate the migration file in `db/post_migrate`. These migrations +behave exactly like regular Rails migrations. + +## Use Cases + +Post deployment migrations can be used to perform migrations that mutate state +that an existing version of GitLab depends on. For example, say you want to +remove a column from a table. This requires downtime as a GitLab instance +depends on this column being present while it's running. Normally you'd follow +these steps in such a case: + +1. Stop the GitLab instance +2. Run the migration removing the column +3. Start the GitLab instance again + +Using post deployment migrations we can instead follow these steps: + +1. Deploy a new version of GitLab while ignoring post deployment migrations +2. Re-run `rake db:migrate` but without the environment variable set + +Here we don't need any downtime as the migration takes place _after_ a new +version (which doesn't depend on the column anymore) has been deployed. + +Some other examples where these migrations are useful: + +* Cleaning up data generated due to a bug in GitLab +* Removing tables +* Migrating jobs from one Sidekiq queue to another -- cgit v1.2.1 From a612daf17763979fc840f0fa247ab082973fbd4f Mon Sep 17 00:00:00 2001 From: Sean McGivern Date: Mon, 31 Oct 2016 12:11:56 +0000 Subject: Add OSL to licensing doc --- doc/development/licensing.md | 3 +++ 1 file changed, 3 insertions(+) (limited to 'doc/development') diff --git a/doc/development/licensing.md b/doc/development/licensing.md index 05972b33fdb..5d177eb26ee 100644 --- a/doc/development/licensing.md +++ b/doc/development/licensing.md @@ -62,6 +62,7 @@ Libraries with the following licenses are unacceptable for use: - [GNU GPL][GPL] (version 1, [version 2][GPLv2], [version 3][GPLv3], or any future versions): GPL-licensed libraries cannot be linked to from non-GPL projects. - [GNU AGPLv3][AGPLv3]: AGPL-licensed libraries cannot be linked to from non-GPL projects. +- [Open Software License (OSL)][OSL]: is a copyleft license. In addition, the FSF [recommend against its use][OSL-GNU]. ## Notes @@ -93,3 +94,5 @@ Gems which are included only in the "development" or "test" groups by Bundler ar [AGPLv3]: http://choosealicense.com/licenses/agpl-3.0/ [GNU-GPL-FAQ]: http://www.gnu.org/licenses/gpl-faq.html#IfLibraryIsGPL [OSI-GPL]: https://opensource.org/faq#linking-proprietary-code +[OSL]: https://opensource.org/licenses/OSL-3.0 +[OSL-GNU]: https://www.gnu.org/licenses/license-list.en.html#OSL -- cgit v1.2.1 From 23312b484f14c4843c782fd195a690e5e288af11 Mon Sep 17 00:00:00 2001 From: Robert Speicher Date: Tue, 25 Oct 2016 13:09:46 +0100 Subject: Add changelog documentation --- doc/development/README.md | 1 + doc/development/changelog.md | 164 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 165 insertions(+) create mode 100644 doc/development/changelog.md (limited to 'doc/development') diff --git a/doc/development/README.md b/doc/development/README.md index 14d6f08e43a..9e0a5178eeb 100644 --- a/doc/development/README.md +++ b/doc/development/README.md @@ -21,6 +21,7 @@ ## Process +- [Generate a changelog entry with `bin/changelog`](changelog.md) - [Code review guidelines](code_review.md) for reviewing code and having code reviewed. - [Merge request performance guidelines](merge_request_performance_guidelines.md) for ensuring merge requests do not negatively impact GitLab performance diff --git a/doc/development/changelog.md b/doc/development/changelog.md new file mode 100644 index 00000000000..f10f4c6722a --- /dev/null +++ b/doc/development/changelog.md @@ -0,0 +1,164 @@ +# Generate a changelog entry + +This guide contains instructions for generating a changelog entry data file, as +well as information and history about our changelog process. + +## Overview + +Each bullet point, or **entry**, in our [`CHANGELOG.md`][changelog.md] file is +generated from a single data file in the [`changelogs/unreleased/`][unreleased] +(or corresponding EE) folder. The file is expected to be a [YAML] file in the +following format: + +```yaml +--- +title: "Going through change[log]s" +merge_request: 1972 +author: Ozzy Osbourne +``` + +The `merge_request` value is a reference to a merge request that adds this +entry, and the `author` key is used to give attribution to community +contributors. Both are optional. + +If you're working on the GitLab EE repository, the entry will be added to +`changelogs/unreleased-ee/` instead. + +[changelog.md]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/CHANGELOG.md +[unreleased]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/changelogs/ +[YAML]: https://en.wikipedia.org/wiki/YAML + +## Instructions + +A `bin/changelog` script is available to generate the changelog entry file +automatically. + +Its simplest usage is to provide the value for `title`: + +```text +$ bin/changelog Hey DZ, I added a feature to GitLab! +create changelogs/unreleased/my-feature.yml +--- +title: Hey DZ, I added a feature to GitLab! +merge_request: +author: +``` + +The entry filename is based on the name of the current Git branch. If you run +the command above on a branch called `feature/hey-dz`, it will generate a +`changelogs/unreleased/feature-hey-dz` file. + +### Arguments + +| Argument | Shorthand | Purpose | +| ----------------- | --------- | --------------------------------------------- | +| `--amend` | | Amend the previous commit | +| `--merge-request` | `-m` | Merge Request ID | +| `--dry-run` | `-n` | Don't actually write anything, just print | +| `--git-username` | `-u` | Use Git user.name configuration as the author | +| `--help` | `-h` | Print help message | + +#### `--amend` + +You can pass the **`--amend`** argument to automatically stage the generated +file and amend it to the previous commit. + +If you use **`--amend`** and don't provide a title, it will automatically use +the "subject" of the previous commit, which is the first line of the commit +message: + +```text +$ git show --oneline +ab88683 Added an awesome new feature to GitLab + +$ bin/changelog --amend +create changelogs/unreleased/feature-hey-dz.yml +--- +title: Added an awesome new feature to GitLab +merge_request: +author: +``` + +#### `--merge-request` or `-m` + +Use the **`--merge-request`** or **`-m`** argument to provide the +`merge_request` value: + +```text +$ bin/changelog Hey DZ, I added a feature to GitLab! -m 1983 +create changelogs/unreleased/feature-hey-dz.yml +--- +title: Hey DZ, I added a feature to GitLab! +merge_request: 1983 +author: +``` + +#### `--dry-run` or `-n` + +Use the **`--dry-run`** or **`-n`** argument to prevent actually writing or +committing anything: + +```text +$ bin/changelog --amend --dry-run +create changelogs/unreleased/feature-hey-dz.yml +--- +title: Added an awesome new feature to GitLab +merge_request: +author: + +$ ls changelogs/unreleased/ +``` + +#### `--git-username` or `-u` + +Use the **`--git-username`** or **`-u`** argument to automatically fill in the +`author` value with your configured Git `user.name` value: + +```text +$ git config user.name +Jane Doe + +$ bin/changelog --u Hey DZ, I added a feature to GitLab! +create changelogs/unreleased/feature-hey-dz.yml +--- +title: Hey DZ, I added a feature to GitLab! +merge_request: +author: Jane Doe +``` + +## History and Reasoning + +Our `CHANGELOG` file was previously updated manually by each contributor that +felt their change warranted an entry. When two merge requests added their own +entries at the same spot in the list, it created a merge conflict in one as soon +as the other was merged. When we had dozens of merge requests fighting for the +same changelog entry location, this quickly became a major source of merge +conflicts and delays in development. + +This led us to a [boring solution] of "add your entry in a random location in +the list." This actually worked pretty well as we got further along in each +monthly release cycle, but at the start of a new cycle, when a new version +section was added and there were fewer places to "randomly" add an entry, the +conflicts became a problem again until we had a sufficient number of entries. + +On top of all this, it created an entirely different headache for [release managers] +when they cherry-picked a commit into a stable branch for a patch release. If +the commit included an entry in the `CHANGELOG`, it would include the entire +changelog for the latest version in `master`, so the release manager would have +to manually remove the later entries. They often would have had to do this +multiple times per patch release. This was compounded when we had to release +multiple patches at once due to a security issue. + +We needed to automate all of this manual work. So we [started brainstorming]. +After much discussion we settled on the current solution of one file per entry, +and then compiling the entries into the overall `CHANGELOG.md` file during the +[release process]. + +[boring solution]: https://about.gitlab.com/handbook/#boring-solutions +[release managers]: https://gitlab.com/gitlab-org/release-tools/blob/master/doc/release-manager.md +[started brainstorming]: https://gitlab.com/gitlab-org/gitlab-ce/issues/17826 +[release process]: https://gitlab.com/gitlab-org/release-tools + +--- + +[Return to Development documentation](README.md) -- cgit v1.2.1 From 7f0ac04db59cb290961bd77a4e0d18cffd248151 Mon Sep 17 00:00:00 2001 From: Bryce Johnson Date: Fri, 30 Sep 2016 17:30:21 +0200 Subject: Document convention for singleton use in front-end code. --- doc/development/frontend.md | 49 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 49 insertions(+) (limited to 'doc/development') diff --git a/doc/development/frontend.md b/doc/development/frontend.md index 4fb56444917..735b41314ef 100644 --- a/doc/development/frontend.md +++ b/doc/development/frontend.md @@ -199,6 +199,55 @@ As long as the fixtures don't change, `rake teaspoon:tests` is sufficient Please note: Not all of the frontend fixtures are generated. Some are still static files. These will not be touched by `rake teaspoon:fixtures`. +## Design Patterns + +### Singletons + +When exactly one object is needed for a given task, prefer to define it as a +`class` rather than as an object literal. Prefer also to explicitly restrict +instantiation, unless flexibility is important (e.g. for testing). + +``` +// bad + +gl.MyThing = { + prop1: 'hello', + method1: () => {} +}; + +// good + +class MyThing { + constructor() { + this.prop1 = 'hello'; + } + method1() {} +} + +gl.MyThing = new MyThing(); + +// best +let singleton; + +class MyThing { + constructor() { + if (!singleton) { + singleton = this; + singleton.init(); + } + return singleton; + } + + init() { + this.prop1 = 'hello'; + } + + method1() {} +} + +gl.MyThing = MyThing; +``` + ## Supported browsers For our currently-supported browsers, see our [requirements][requirements]. -- cgit v1.2.1 From 2159c8792b289bb27f9947fb834fbd497efeeb28 Mon Sep 17 00:00:00 2001 From: Bryce Johnson Date: Tue, 1 Nov 2016 20:40:01 +0100 Subject: Fix spacing in code sample. --- doc/development/frontend.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) (limited to 'doc/development') diff --git a/doc/development/frontend.md b/doc/development/frontend.md index 735b41314ef..c6aafc926ee 100644 --- a/doc/development/frontend.md +++ b/doc/development/frontend.md @@ -227,14 +227,15 @@ class MyThing { gl.MyThing = new MyThing(); // best + let singleton; class MyThing { constructor() { if (!singleton) { - singleton = this; - singleton.init(); - } + singleton = this; + singleton.init(); + } return singleton; } @@ -246,6 +247,7 @@ class MyThing { } gl.MyThing = MyThing; + ``` ## Supported browsers -- cgit v1.2.1 From af5322e90b47e830e7713482854ddf6450a0d8c1 Mon Sep 17 00:00:00 2001 From: Drew Blessing Date: Tue, 2 Aug 2016 22:46:43 -0600 Subject: Add Rake task to create/repair GitLab Shell hooks symlinks --- doc/development/testing.md | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) (limited to 'doc/development') diff --git a/doc/development/testing.md b/doc/development/testing.md index 8e91ac5e3ba..b0b26ccf57a 100644 --- a/doc/development/testing.md +++ b/doc/development/testing.md @@ -132,6 +132,42 @@ Adding new Spinach scenarios is acceptable _only if_ the new scenario requires no more than one new `step` definition. If more than that is required, the test should be re-implemented using RSpec instead. +## Testing Rake Tasks + +To make testing Rake tasks a little easier, there is a helper that can be included +in lieu of the standard Spec helper. Instead of `require 'spec_helper'`, use +`require 'rake_helper'`. The helper includes `spec_helper` for you, and configures +a few other things to make testing Rake tasks easier. + +At a minimum, requiring the Rake helper will redirect `stdout`, include the +runtime task helpers, and include the `RakeHelpers` Spec support module. + +The `RakeHelpers` module exposes a `run_rake_task()` method to make +executing tasks simple. See `spec/support/rake_helpers.rb` for all available +methods. + +Example: + +```ruby +require 'rake_helper' + +describe 'gitlab:shell rake tasks' do + before do + Rake.application.rake_require 'tasks/gitlab/shell' + + stub_warn_user_is_not_gitlab + end + + describe 'install task' do + it 'invokes create_hooks task' do + expect(Rake::Task['gitlab:shell:create_hooks']).to receive(:invoke) + + run_rake_task('gitlab:shell:install') + end + end +end +``` + --- [Return to Development documentation](README.md) -- cgit v1.2.1 From c1ee879c66ea81b28d36d1c1f0b34ead296cffbf Mon Sep 17 00:00:00 2001 From: Robert Speicher Date: Wed, 2 Nov 2016 15:16:19 +0000 Subject: Update examples in changelog docs to use single quotes around title [ci skip] --- doc/development/changelog.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'doc/development') diff --git a/doc/development/changelog.md b/doc/development/changelog.md index f10f4c6722a..d08c476e9d6 100644 --- a/doc/development/changelog.md +++ b/doc/development/changelog.md @@ -36,7 +36,7 @@ automatically. Its simplest usage is to provide the value for `title`: ```text -$ bin/changelog Hey DZ, I added a feature to GitLab! +$ bin/changelog 'Hey DZ, I added a feature to GitLab!' create changelogs/unreleased/my-feature.yml --- title: Hey DZ, I added a feature to GitLab! @@ -85,7 +85,7 @@ Use the **`--merge-request`** or **`-m`** argument to provide the `merge_request` value: ```text -$ bin/changelog Hey DZ, I added a feature to GitLab! -m 1983 +$ bin/changelog 'Hey DZ, I added a feature to GitLab!' -m 1983 create changelogs/unreleased/feature-hey-dz.yml --- title: Hey DZ, I added a feature to GitLab! @@ -118,7 +118,7 @@ Use the **`--git-username`** or **`-u`** argument to automatically fill in the $ git config user.name Jane Doe -$ bin/changelog --u Hey DZ, I added a feature to GitLab! +$ bin/changelog --u 'Hey DZ, I added a feature to GitLab!' create changelogs/unreleased/feature-hey-dz.yml --- title: Hey DZ, I added a feature to GitLab! -- cgit v1.2.1 From 895673733a5712ee4b69c84195a1d717a72fc032 Mon Sep 17 00:00:00 2001 From: Robert Speicher Date: Wed, 2 Nov 2016 22:15:20 +0000 Subject: Add a `--force` option to bin/changelog --- doc/development/changelog.md | 20 +++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) (limited to 'doc/development') diff --git a/doc/development/changelog.md b/doc/development/changelog.md index d08c476e9d6..390eb549d0b 100644 --- a/doc/development/changelog.md +++ b/doc/development/changelog.md @@ -46,13 +46,14 @@ author: The entry filename is based on the name of the current Git branch. If you run the command above on a branch called `feature/hey-dz`, it will generate a -`changelogs/unreleased/feature-hey-dz` file. +`changelogs/unreleased/feature-hey-dz.yml` file. ### Arguments | Argument | Shorthand | Purpose | | ----------------- | --------- | --------------------------------------------- | | `--amend` | | Amend the previous commit | +| `--force` | `-f` | Overwrite an existing entry | | `--merge-request` | `-m` | Merge Request ID | | `--dry-run` | `-n` | Don't actually write anything, just print | | `--git-username` | `-u` | Use Git user.name configuration as the author | @@ -79,6 +80,23 @@ merge_request: author: ``` +#### `--force` or `-f` + +Use **`--force`** or **`-f`** to overwrite an existing changelog entry if it +already exists. + +```text +$ bin/changelog 'Hey DZ, I added a feature to GitLab!' +error changelogs/unreleased/feature-hey-dz.yml already exists! Use `--force` to overwrite. + +$ bin/changelog 'Hey DZ, I added a feature to GitLab!' --force +create changelogs/unreleased/feature-hey-dz.yml +--- +title: Hey DZ, I added a feature to GitLab! +merge_request: 1983 +author: +``` + #### `--merge-request` or `-m` Use the **`--merge-request`** or **`-m`** argument to provide the -- cgit v1.2.1 From 4ba789cd40dfca5de9569dc34db2c4b0252437fc Mon Sep 17 00:00:00 2001 From: Robert Speicher Date: Thu, 3 Nov 2016 10:38:21 +0000 Subject: Remove unused `gitlab:generate_docs` Rake task This was the only thing using the `sdoc` gem, which was blocking another gem from updating. --- doc/development/rake_tasks.md | 8 -------- 1 file changed, 8 deletions(-) (limited to 'doc/development') diff --git a/doc/development/rake_tasks.md b/doc/development/rake_tasks.md index a7175f3f87e..827db7e99b8 100644 --- a/doc/development/rake_tasks.md +++ b/doc/development/rake_tasks.md @@ -42,14 +42,6 @@ To run several tests inside one directory: If you want to use [Spring](https://github.com/rails/spring) set `ENABLE_SPRING=1` in your environment. -## Generate searchable docs for source code - -You can find results under the `doc/code` directory. - -``` -bundle exec rake gitlab:generate_docs -``` - ## Generate API documentation for project services (e.g. Slack) ``` -- cgit v1.2.1 From 492ef142ad13389d79c74128b1bdf543b6f662c2 Mon Sep 17 00:00:00 2001 From: Robert Speicher Date: Thu, 3 Nov 2016 18:00:18 +0000 Subject: Clarify the author field for the changelog documentation [ci skip] --- doc/development/changelog.md | 3 +++ 1 file changed, 3 insertions(+) (limited to 'doc/development') diff --git a/doc/development/changelog.md b/doc/development/changelog.md index 390eb549d0b..6a97fae9cac 100644 --- a/doc/development/changelog.md +++ b/doc/development/changelog.md @@ -21,6 +21,9 @@ The `merge_request` value is a reference to a merge request that adds this entry, and the `author` key is used to give attribution to community contributors. Both are optional. +Community contributors and core team members are encouraged to add their name to +the `author` field. GitLab team members should not. + If you're working on the GitLab EE repository, the entry will be added to `changelogs/unreleased-ee/` instead. -- cgit v1.2.1 From 8a998b632ad9abbc31d6da1678eef9c0cefb1ad2 Mon Sep 17 00:00:00 2001 From: Connor Shea Date: Sun, 23 Oct 2016 16:07:54 -0600 Subject: Change a bunch of doc links to either relative or https://docs.gitlab.com. --- doc/development/doc_styleguide.md | 1 + 1 file changed, 1 insertion(+) (limited to 'doc/development') diff --git a/doc/development/doc_styleguide.md b/doc/development/doc_styleguide.md index 2cfa30f652e..b137e6ae82e 100644 --- a/doc/development/doc_styleguide.md +++ b/doc/development/doc_styleguide.md @@ -465,6 +465,7 @@ curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --data "domain [cURL]: http://curl.haxx.se/ "cURL website" [single spaces]: http://www.slate.com/articles/technology/technology/2011/01/space_invaders.html [gfm]: http://docs.gitlab.com/ce/user/markdown.html#newlines "GitLab flavored markdown documentation" +[ce-1242]: https://gitlab.com/gitlab-org/gitlab-ce/issues/1242 [doc-restart]: ../administration/restart_gitlab.md "GitLab restart documentation" [ce-3349]: https://gitlab.com/gitlab-org/gitlab-ce/issues/3349 "Documentation restructure" [graffle]: https://gitlab.com/gitlab-org/gitlab-design/blob/d8d39f4a87b90fb9ae89ca12dc565347b4900d5e/production/resources/gitlab-map.graffle -- cgit v1.2.1 From 06dcb0776eb2160ecff4910b9459f31ca6368507 Mon Sep 17 00:00:00 2001 From: Bryce Johnson Date: Thu, 3 Nov 2016 09:57:30 +0000 Subject: Add tip for using Chrome to run and debug teaspoon tests. --- doc/development/frontend.md | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'doc/development') diff --git a/doc/development/frontend.md b/doc/development/frontend.md index ece8f880542..1d7d9127a64 100644 --- a/doc/development/frontend.md +++ b/doc/development/frontend.md @@ -196,6 +196,12 @@ It consists of two subtasks: As long as the fixtures don't change, `rake teaspoon:tests` is sufficient (and saves you some time). +If you need to debug your tests and/or application code while they're +running, navigate to [localhost:3000/teaspoon](http://localhost:3000/teaspoon) +in your browser, open DevTools, and run tests for individual files by clicking +on them. This is also much faster than setting up and running tests from the +command line. + Please note: Not all of the frontend fixtures are generated. Some are still static files. These will not be touched by `rake teaspoon:fixtures`. -- cgit v1.2.1 From 0c36b810abede73b3cf59f951e7467dbac54ec98 Mon Sep 17 00:00:00 2001 From: Sam Rose Date: Sun, 6 Nov 2016 13:26:44 -0500 Subject: Fix broken link to observatory cli on Frontend Dev Guide --- doc/development/frontend.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/development') diff --git a/doc/development/frontend.md b/doc/development/frontend.md index 1d7d9127a64..ec8f2d6531c 100644 --- a/doc/development/frontend.md +++ b/doc/development/frontend.md @@ -228,7 +228,7 @@ For our currently-supported browsers, see our [requirements][requirements]. [page-specific-js-example]: https://gitlab.com/gitlab-org/gitlab-ce/blob/13bb9ed77f405c5f6ee4fdbc964ecf635c9a223f/app/views/projects/graphs/_head.html.haml#L6-8 [chrome-accessibility-developer-tools]: https://github.com/GoogleChrome/accessibility-developer-tools [audit-rules]: https://github.com/GoogleChrome/accessibility-developer-tools/wiki/Audit-Rules -[observatory-cli]: https://github.com/mozilla/http-observatory-cli) +[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 -- cgit v1.2.1 From 630eb119cb99eb971a9e29d83293774b5b882490 Mon Sep 17 00:00:00 2001 From: Nick Thomas Date: Fri, 4 Nov 2016 12:55:15 +0000 Subject: Renaming columns requires downtime --- doc/development/what_requires_downtime.md | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'doc/development') diff --git a/doc/development/what_requires_downtime.md b/doc/development/what_requires_downtime.md index 2574c2c0472..bbcd26477f3 100644 --- a/doc/development/what_requires_downtime.md +++ b/doc/development/what_requires_downtime.md @@ -66,6 +66,12 @@ producing errors whenever it tries to use the `dummy` column. As a result of the above downtime _is_ required when removing a column, even when using PostgreSQL. +## Renaming Columns + +Renaming columns requires downtime as running GitLab instances will continue +using the old column name until a new version is deployed. This can result +in the instance producing errors, which in turn can impact the user experience. + ## Changing Column Constraints Generally changing column constraints requires checking all rows in the table to -- cgit v1.2.1 From 9a2ad60ffa5d02d6826546e9ca712db1fab804ad Mon Sep 17 00:00:00 2001 From: Robert Speicher Date: Wed, 9 Nov 2016 10:59:15 +0000 Subject: Add more highlighting to Migration Style Guide doc [ci skip] --- doc/development/migration_style_guide.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) (limited to 'doc/development') diff --git a/doc/development/migration_style_guide.md b/doc/development/migration_style_guide.md index 61b0fbc89c9..fd8335d251e 100644 --- a/doc/development/migration_style_guide.md +++ b/doc/development/migration_style_guide.md @@ -60,7 +60,7 @@ migration was tested. If you need to remove index, please add a condition like in following example: -``` +```ruby remove_index :namespaces, column: :name if index_exists?(:namespaces, :name) ``` @@ -75,7 +75,7 @@ need for downtime. To use this method you must disable transactions by calling the method `disable_ddl_transaction!` in the body of your migration class like so: -``` +```ruby class MyMigration < ActiveRecord::Migration include Gitlab::Database::MigrationHelpers disable_ddl_transaction! @@ -96,7 +96,7 @@ the `up` and `down` methods in your migration class. For example, to add the column `foo` to the `projects` table with a default value of `10` you'd write the following: -``` +```ruby class MyMigration < ActiveRecord::Migration include Gitlab::Database::MigrationHelpers disable_ddl_transaction! @@ -125,7 +125,7 @@ set the limit to 8-bytes. This will allow the column to hold a value up to Rails migration example: -``` +```ruby add_column_with_default(:projects, :foo, :integer, default: 10, limit: 8) # or @@ -145,7 +145,7 @@ Please prefer Arel and plain SQL over usual ActiveRecord syntax. In case of usin Example with Arel: -``` +```ruby users = Arel::Table.new(:users) users.group(users[:user_id]).having(users[:id].count.gt(5)) @@ -154,7 +154,7 @@ users.group(users[:user_id]).having(users[:id].count.gt(5)) Example with plain SQL and `quote_string` helper: -``` +```ruby select_all("SELECT name, COUNT(id) as cnt FROM tags GROUP BY name HAVING COUNT(id) > 1").each do |tag| tag_name = quote_string(tag["name"]) duplicate_ids = select_all("SELECT id FROM tags WHERE name = '#{tag_name}'").map{|tag| tag["id"]} -- cgit v1.2.1 From 57f9ee0b9f77dc1aa0882fe0423228b77b8e8a33 Mon Sep 17 00:00:00 2001 From: Robert Speicher Date: Wed, 9 Nov 2016 11:05:05 +0000 Subject: Add more highlighting to Instrumentation doc [ci skip] --- doc/development/instrumentation.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'doc/development') diff --git a/doc/development/instrumentation.md b/doc/development/instrumentation.md index 105e2f1242a..b8669964c84 100644 --- a/doc/development/instrumentation.md +++ b/doc/development/instrumentation.md @@ -24,7 +24,7 @@ namespace you can use the `configure` class method. This method simply yields the supplied block while passing `Gitlab::Metrics::Instrumentation` as its argument. An example: -``` +```ruby Gitlab::Metrics::Instrumentation.configure do |conf| conf.instrument_method(Foo, :bar) conf.instrument_method(Foo, :baz) @@ -41,7 +41,7 @@ Method instrumentation should be added in the initializer Instrumenting a single method: -``` +```ruby Gitlab::Metrics::Instrumentation.configure do |conf| conf.instrument_method(User, :find_by) end @@ -49,7 +49,7 @@ end Instrumenting an entire class hierarchy: -``` +```ruby Gitlab::Metrics::Instrumentation.configure do |conf| conf.instrument_class_hierarchy(ActiveRecord::Base) end @@ -57,7 +57,7 @@ end Instrumenting all public class methods: -``` +```ruby Gitlab::Metrics::Instrumentation.configure do |conf| conf.instrument_methods(User) end @@ -68,7 +68,7 @@ end The easiest way to check if a method has been instrumented is to check its source location. For example: -``` +```ruby method = Rugged::TagCollection.instance_method(:[]) method.source_location -- cgit v1.2.1 From de4334635e2f3cd992a91726a546ac5b324a8f4b Mon Sep 17 00:00:00 2001 From: Robert Speicher Date: Wed, 9 Nov 2016 11:06:49 +0000 Subject: Add more highlighting to Shell Commands doc [ci skip] --- doc/development/shell_commands.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'doc/development') diff --git a/doc/development/shell_commands.md b/doc/development/shell_commands.md index 65cdd74bdb6..73893f9dd46 100644 --- a/doc/development/shell_commands.md +++ b/doc/development/shell_commands.md @@ -129,7 +129,7 @@ Various methods for opening and reading files in Ruby can be used to read the standard output of a process instead of a file. The following two commands do roughly the same: -``` +```ruby `touch /tmp/pawned-by-backticks` File.read('|touch /tmp/pawned-by-file-read') ``` @@ -142,7 +142,7 @@ attacker cannot control the start of the filename string you are opening. For instance, the following is sufficient to protect against accidentally starting a shell command with `|`: -``` +```ruby # we assume repo_path is not controlled by the attacker (user) path = File.join(repo_path, user_input) # path cannot start with '|' now. @@ -160,7 +160,7 @@ Path traversal is a security where the program (GitLab) tries to restrict user access to a certain directory on disk, but the user manages to open a file outside that directory by taking advantage of the `../` path notation. -``` +```ruby # Suppose the user gave us a path and they are trying to trick us user_input = '../other-repo.git/other-file' @@ -177,7 +177,7 @@ File.open(full_path) do # Oops! A good way to protect against this is to compare the full path with its 'absolute path' according to Ruby's `File.absolute_path`. -``` +```ruby full_path = File.join(repo_path, user_input) if full_path != File.absolute_path(full_path) raise "Invalid path: #{full_path.inspect}" -- cgit v1.2.1 From 11510bf729e04ea6f4a713820582b490266505d2 Mon Sep 17 00:00:00 2001 From: awhildy Date: Fri, 21 Oct 2016 14:25:09 -0700 Subject: [ci skip] Establish basic structure for ux_guide README.md Block out pages needed for ux_guide Add resources stub to ux_guide home Fill out principles and basics Add TOC to basics Move all of UI guide to new UX guide structure Add first level structure on ux-guide pages Add more details to buttons Add button images. Update link on development Renamed surfaces to templates. Add tooltip details Update typography and icons on Basics page Add images for color. First draft of voice and tone Delete findings page Refine pages. Fill out Surfaces pages Clean up layout on basics, surfaces, features. Add anchorlinks and counts to components Fill out components page Add item title and system info block Fill out Features page Switch tooltip placement image --- doc/development/README.md | 2 +- doc/development/ux_guide/README.md | 59 +++++ doc/development/ux_guide/basics.md | 112 ++++++++ doc/development/ux_guide/components.md | 282 +++++++++++++++++++++ doc/development/ux_guide/features.md | 63 +++++ doc/development/ux_guide/img/button-primary.png | Bin 0 -> 8410 bytes doc/development/ux_guide/img/button-secondary.png | Bin 0 -> 11160 bytes doc/development/ux_guide/img/color-blue.png | Bin 0 -> 3865 bytes doc/development/ux_guide/img/color-green.png | Bin 0 -> 4127 bytes doc/development/ux_guide/img/color-grey.png | Bin 0 -> 2384 bytes doc/development/ux_guide/img/color-orange.png | Bin 0 -> 4698 bytes doc/development/ux_guide/img/color-red.png | Bin 0 -> 3669 bytes doc/development/ux_guide/img/components-alerts.png | Bin 0 -> 46785 bytes .../ux_guide/img/components-anchorlinks.png | Bin 0 -> 36456 bytes .../ux_guide/img/components-contentblock.png | Bin 0 -> 19841 bytes doc/development/ux_guide/img/components-counts.png | Bin 0 -> 2438 bytes .../ux_guide/img/components-coverblock.png | Bin 0 -> 15757 bytes .../ux_guide/img/components-dateexact.png | Bin 0 -> 5609 bytes .../ux_guide/img/components-daterelative.png | Bin 0 -> 5843 bytes .../ux_guide/img/components-dropdown.png | Bin 0 -> 60448 bytes .../ux_guide/img/components-fileholder.png | Bin 0 -> 4953 bytes .../ux_guide/img/components-horizontalform.png | Bin 0 -> 5708 bytes .../ux_guide/img/components-listinsidepanel.png | Bin 0 -> 3962 bytes .../ux_guide/img/components-listwithavatar.png | Bin 0 -> 7952 bytes .../ux_guide/img/components-listwithhover.png | Bin 0 -> 3313 bytes doc/development/ux_guide/img/components-panels.png | Bin 0 -> 32886 bytes .../ux_guide/img/components-referencehover.png | Bin 0 -> 11519 bytes .../ux_guide/img/components-referenceissues.png | Bin 0 -> 14587 bytes .../ux_guide/img/components-referencelabels.png | Bin 0 -> 4643 bytes .../ux_guide/img/components-referencemilestone.png | Bin 0 -> 2468 bytes .../ux_guide/img/components-referencemrs.png | Bin 0 -> 12646 bytes .../ux_guide/img/components-referencepeople.png | Bin 0 -> 7214 bytes .../ux_guide/img/components-rowcontentblock.png | Bin 0 -> 19730 bytes .../ux_guide/img/components-simplelist.png | Bin 0 -> 3078 bytes doc/development/ux_guide/img/components-table.png | Bin 0 -> 7668 bytes .../ux_guide/img/components-verticalform.png | Bin 0 -> 6541 bytes .../ux_guide/img/features-contextualnav.png | Bin 0 -> 8051 bytes .../ux_guide/img/features-emptystates.png | Bin 0 -> 114540 bytes doc/development/ux_guide/img/features-filters.png | Bin 0 -> 4529 bytes .../ux_guide/img/features-globalnav.png | Bin 0 -> 8953 bytes doc/development/ux_guide/img/icon-add.png | Bin 0 -> 155 bytes doc/development/ux_guide/img/icon-close.png | Bin 0 -> 225 bytes doc/development/ux_guide/img/icon-edit.png | Bin 0 -> 231 bytes doc/development/ux_guide/img/icon-notification.png | Bin 0 -> 259 bytes doc/development/ux_guide/img/icon-rss.png | Bin 0 -> 307 bytes doc/development/ux_guide/img/icon-subscribe.png | Bin 0 -> 348 bytes doc/development/ux_guide/img/icon-trash.png | Bin 0 -> 380 bytes .../ux_guide/img/monospacefont-sample.png | Bin 0 -> 14282 bytes .../ux_guide/img/sourcesanspro-sample.png | Bin 0 -> 10948 bytes .../ux_guide/img/surfaces-contentitemtitle.png | Bin 0 -> 7463 bytes doc/development/ux_guide/img/surfaces-header.png | Bin 0 -> 6103 bytes .../img/surfaces-systeminformationblock.png | Bin 0 -> 15412 bytes doc/development/ux_guide/img/surfaces-ux.png | Bin 0 -> 7673 bytes doc/development/ux_guide/img/tooltip-placement.png | Bin 0 -> 2645 bytes doc/development/ux_guide/img/tooltip-usage.png | Bin 0 -> 9160 bytes doc/development/ux_guide/principles.md | 29 +++ doc/development/ux_guide/resources.md | 13 + doc/development/ux_guide/surfaces.md | 53 ++++ doc/development/ux_guide/tips.md | 46 ++++ doc/development/ux_guide/users.md | 18 ++ 60 files changed, 676 insertions(+), 1 deletion(-) create mode 100644 doc/development/ux_guide/README.md create mode 100644 doc/development/ux_guide/basics.md create mode 100644 doc/development/ux_guide/components.md create mode 100644 doc/development/ux_guide/features.md create mode 100644 doc/development/ux_guide/img/button-primary.png create mode 100644 doc/development/ux_guide/img/button-secondary.png create mode 100644 doc/development/ux_guide/img/color-blue.png create mode 100644 doc/development/ux_guide/img/color-green.png create mode 100644 doc/development/ux_guide/img/color-grey.png create mode 100644 doc/development/ux_guide/img/color-orange.png create mode 100644 doc/development/ux_guide/img/color-red.png create mode 100644 doc/development/ux_guide/img/components-alerts.png create mode 100644 doc/development/ux_guide/img/components-anchorlinks.png create mode 100644 doc/development/ux_guide/img/components-contentblock.png create mode 100644 doc/development/ux_guide/img/components-counts.png create mode 100644 doc/development/ux_guide/img/components-coverblock.png create mode 100644 doc/development/ux_guide/img/components-dateexact.png create mode 100644 doc/development/ux_guide/img/components-daterelative.png create mode 100644 doc/development/ux_guide/img/components-dropdown.png create mode 100644 doc/development/ux_guide/img/components-fileholder.png create mode 100644 doc/development/ux_guide/img/components-horizontalform.png create mode 100644 doc/development/ux_guide/img/components-listinsidepanel.png create mode 100644 doc/development/ux_guide/img/components-listwithavatar.png create mode 100644 doc/development/ux_guide/img/components-listwithhover.png create mode 100644 doc/development/ux_guide/img/components-panels.png create mode 100644 doc/development/ux_guide/img/components-referencehover.png create mode 100644 doc/development/ux_guide/img/components-referenceissues.png create mode 100644 doc/development/ux_guide/img/components-referencelabels.png create mode 100644 doc/development/ux_guide/img/components-referencemilestone.png create mode 100644 doc/development/ux_guide/img/components-referencemrs.png create mode 100644 doc/development/ux_guide/img/components-referencepeople.png create mode 100644 doc/development/ux_guide/img/components-rowcontentblock.png create mode 100644 doc/development/ux_guide/img/components-simplelist.png create mode 100644 doc/development/ux_guide/img/components-table.png create mode 100644 doc/development/ux_guide/img/components-verticalform.png create mode 100644 doc/development/ux_guide/img/features-contextualnav.png create mode 100644 doc/development/ux_guide/img/features-emptystates.png create mode 100644 doc/development/ux_guide/img/features-filters.png create mode 100644 doc/development/ux_guide/img/features-globalnav.png create mode 100644 doc/development/ux_guide/img/icon-add.png create mode 100644 doc/development/ux_guide/img/icon-close.png create mode 100644 doc/development/ux_guide/img/icon-edit.png create mode 100644 doc/development/ux_guide/img/icon-notification.png create mode 100644 doc/development/ux_guide/img/icon-rss.png create mode 100644 doc/development/ux_guide/img/icon-subscribe.png create mode 100644 doc/development/ux_guide/img/icon-trash.png create mode 100644 doc/development/ux_guide/img/monospacefont-sample.png create mode 100644 doc/development/ux_guide/img/sourcesanspro-sample.png create mode 100644 doc/development/ux_guide/img/surfaces-contentitemtitle.png create mode 100644 doc/development/ux_guide/img/surfaces-header.png create mode 100644 doc/development/ux_guide/img/surfaces-systeminformationblock.png create mode 100644 doc/development/ux_guide/img/surfaces-ux.png create mode 100644 doc/development/ux_guide/img/tooltip-placement.png create mode 100644 doc/development/ux_guide/img/tooltip-usage.png create mode 100644 doc/development/ux_guide/principles.md create mode 100644 doc/development/ux_guide/resources.md create mode 100644 doc/development/ux_guide/surfaces.md create mode 100644 doc/development/ux_guide/tips.md create mode 100644 doc/development/ux_guide/users.md (limited to 'doc/development') diff --git a/doc/development/README.md b/doc/development/README.md index bf1f054b7d5..87306b1501d 100644 --- a/doc/development/README.md +++ b/doc/development/README.md @@ -14,7 +14,7 @@ contributing to documentation. - [SQL Migration Style Guide](migration_style_guide.md) for creating safe SQL migrations - [Testing standards and style guidelines](testing.md) -- [UI guide](ui_guide.md) for building GitLab with existing CSS styles and elements +- [UX guide](ux_guide/README.md) for building GitLab with existing CSS styles and elements - [Frontend guidelines](frontend.md) - [SQL guidelines](sql.md) for working with SQL queries - [Sidekiq guidelines](sidekiq_style_guide.md) for working with Sidekiq workers diff --git a/doc/development/ux_guide/README.md b/doc/development/ux_guide/README.md new file mode 100644 index 00000000000..e17a4559069 --- /dev/null +++ b/doc/development/ux_guide/README.md @@ -0,0 +1,59 @@ +# GitLab UX Guide + +The goal of this guide is to provide standards, principles and in-depth information to design beautiful and effective GitLab features. This will be a living document, and we welcome contributions, feedback and suggestions. + +## Design + +--- + +### [Principles](principles.md) +These guiding principles set a solid foundation for our design system, and should remain relatively stable over multiple releases. They should be referenced as new design patterns are created. + +--- + +### [Basics](basics.md) +The basic ingredients of our experience establish our personality and feel. This section includes details about typography, color, and motion. + +--- + +### [Components](components.md) +Components are the controls that make up the GitLab experience, including guidance around buttons, links, dropdowns, etc. + +--- + +### [Surfaces](surfaces.md) +The GitLab experience is broken apart into several surfaces. Each of these surfaces is designated for a specific scope or type of content. Examples include the header, global menu, side pane, etc. + +--- + +### [Features](features.md) +The previous building blocks are combined into complete features in the GitLab UX. Examples include our navigation, filters, search results, and empty states. + +--- + +
+ +## Research + +--- + +### [Users](users.md) +How we think about the variety of users of GitLab, from small to large teams, comparing opensource usage to enterprise, etc. + +--- + +
+ +## Other + +--- + +### [Tips for designers](tips.md) +Tips for exporting assets, and other guidance. + +--- + +### [Resources](resources.md) +Resources for GitLab UX + +--- diff --git a/doc/development/ux_guide/basics.md b/doc/development/ux_guide/basics.md new file mode 100644 index 00000000000..7e7cb103694 --- /dev/null +++ b/doc/development/ux_guide/basics.md @@ -0,0 +1,112 @@ +# Basics + +## Contents +* [Responsive](#responsive) +* [Typography](#typography) +* [Icons](#icons) +* [Color](#color) +* [Motion](#motion) +* [Voice and tone](#voice-and-tone) + +--- + +
+ +## Responsive +GitLab is a responsive experience that works well across all screen sizes, from mobile devices to large monitors. In order to provide a great user experience, the core functionality (browsing files, creating issues, writing comments, etc.) must be available at all resolutions. However, due to size limitations, some secondary functionality may be hidden on smaller screens. Please keep this functionality limited to rare actions that aren't expected to be needed on small devices. + +--- + +
+ +## Typography +### Primary typeface +GitLab's main typeface used throughout the UI is **Source Sans Pro**. We support both the bold and regular weight. + +![Source Sans Pro sample](img/sourcesanspro-sample.png) + + +### Monospace typeface +This is the typeface used for code blocks. GitLab uses the OS default font. +- **Menlo** (Mac) +- **Consolas** (Windows) +- **Liberation Mono** (Linux) + +![Monospace font sample](img/monospacefont-sample.png) + +--- + +
+ +## Icons +GitLab uses Font Awesome icons throughout our interface. + +![Trash icon](img/icon-trash.png) +The trash icon is used for destructive actions that deletes information. + +![Edit icon](img/icon-edit.png) +The pencil icon is used for editing content such as comments. + +![Notification icon](img/icon-notification.png) +The bell icon is for notifications, such as Todos. + +![Subscribe icon](img/icon-subscribe.png) +The eye icon is for subscribing to updates. For example, you can subscribe to a label and get updated on issues with that label. + +![RSS icon](img/icon-rss.png) +The standard RSS icon is used for linking to RSS/atom feeds. + +![Close icon](img/icon-close.png) +An 'x' is used for closing UI elements such as dropdowns. + +![Add icon](img/icon-add.png) +A plus is used when creating new objects, such as issues, projects, etc. + +>>> +TODO: update this section, add more general guidance to icon usage and personality, etc. +>>> + +--- + +
+ +## Color + +![Blue](img/color-blue.png) +Blue is used to highlight primary active elements (such as current tab), as well as other organization and managing commands. + +![Green](img/color-green.png) +Green is for actions that create new objects. + +![Orange](img/color-orange.png) +Orange is used for warnings + +![Red](img/color-red.png) +Red is reserved for delete and other destructive commands + +![Grey](img/color-grey.png) +Grey, and white (depending on context) is used for netral, secondary elements + +>>> +TODO: Establish a perspective for color in terms of our personality and rationalize with Marketing usage. +>>> + +--- + +
+ +## Motion + +Motion is a tool to help convey important relationships, changes or transitions between elements. It should be used sparingly and intentionally, highlighting the right elements at the right moment. + +>>> +TODO: Determine a more concrete perspective on motion, create consistent easing/timing curves to follow. +>>> + +--- + +
+ +## Voice and tone + +The copy for GitLab is clear and direct. We strike a clear balance between professional and friendly. We can empathesize with users (such as celebrating completing all Todos), and remain respectful of the importance of the work. We are that trusted, friendly coworker that is helpful and understanding. \ No newline at end of file diff --git a/doc/development/ux_guide/components.md b/doc/development/ux_guide/components.md new file mode 100644 index 00000000000..6b21566265c --- /dev/null +++ b/doc/development/ux_guide/components.md @@ -0,0 +1,282 @@ +# Components + +## Contents +* [Tooltips](#tooltips) +* [Anchor links](#anchor-links) +* [Buttons](#buttons) +* [Dropdowns](#dropdowns) +* [Counts](#counts) +* [Lists](#lists) +* [Tables](#tables) +* [Blocks](#blocks) +* [Panels](#panels) +* [Alerts](#alerts) +* [Forms](#forms) +* [File holders](#file-holders) +* [Data formats](#data-formats) + +--- + +
+ +## Tooltips + +### Usage +A tooltip should only be added if additional information is required. + +![Tooltip usage](img/tooltip-usage.png) + +### Placement +By default, tooltips should be placed below the element that they refer to. However, if there is not enough space in the viewpoint, the tooltip should be moved to the side as needed. + +![Tooltip placement location](img/tooltip-placement.png) + +--- + +
+ +## Anchor links + +Anchor links are used for navigational actions and lone, secondary commands (such as 'Reset filters' on the Issues List) when deemed appropriate by the UX team. + +### States + +#### Rest + +Primary links are blue in their rest state. Secondary links (such as the time stamp on comments) are a neutral gray color in rest. Details on the main GitLab navigation links can be found on the [features](features.md#navigation) page. + +#### Hover + +An underline should always be added on hover. A gray link becomes blue on hover. + +#### Focus + +The focus state should match the hover state. + +![Anchor link states ](img/components-anchorlinks.png) + +--- + +
+ +## Buttons + +Buttons communicate the command that will occur when the user clicks on them. + +### Types + +#### Primary +Primary buttons communicate the main call to action. There should only be one call to action in any given experience. Visually, primary buttons are conveyed with a full background fill + +![Primary button example](img/button-primary.png) + +#### Secondary +Secondary buttons are for alternative commands. They should be conveyed by a button with an stroke, and no background fill. + +![Secondary button example](img/button-secondary.png) + +### Icon and text treatment +Text should be in sentence case, where only the first word is capitalized. "Create issue" is correct, not "Create Issue". Buttons should only contain an icon or a text, not both. + +>>> +TODO: Rationalize this. Ensure that we still believe this. +>>> + +### Colors +Follow the color guidance on the [basics](basics.md#color) page. The default color treatment is the white/grey button. + +--- + +
+ +## Dropdowns + +Dropdowns are used to allow users to choose one (or many) options from a list of options. If this list of options is more 20, there should generally be a way to search through and filter the options (see the complex filter dropdowns below.) + +>>> +TODO: Will update this section when the new filters UI is implemented. +>>> + +![Dropdown states](img/components-dropdown.png) + + + +--- + +
+ +## Counts + +A count element is used in navigation contexts where it is helpful to indicate the count, or number of items, in a list. Always use the [`number_with_delimiter`][number_with_delimiter] helper to display counts in the UI. + +![Counts example](img/components-counts.png) + +[number_with_delimiter]: http://api.rubyonrails.org/classes/ActionView/Helpers/NumberHelper.html#method-i-number_with_delimiter + +--- + +
+ +## Lists + +Lists are used where ever there is a single column of information to display. Ths [issues list](https://gitlab.com/gitlab-org/gitlab-ce/issues) is an example of a important list in the GitLab UI. + +### Types + +Simple list using .content-list + +![Simple list](img/components-simplelist.png) + +List with avatar, title and description using .content-list + +![List with avatar](img/components-listwithavatar.png) + +List with hover effect .well-list + +![List with hover effect](img/components-listwithhover.png) + +List inside panel + +![List inside panel](img/components-listinsidepanel.png) + +--- + +
+ +## Tables + +When the information is too complex for a list, with multiple columns of information, a table can be used. For example, the [pipelines page](https://gitlab.com/gitlab-org/gitlab-ce/pipelines) uses a table. + +![Table](img/components-table.png) + +--- + +
+ +## Blocks + +Blocks are a way to group related information. + +### Types + +#### Content blocks + +Content blocks (`.content-block`) are the basic grouping of content. They are commonly used in [lists](#lists), and are separated by a botton border. + +![Content block](img/components-contentblock.png) + +#### Row content blocks + +A background color can be added to this blocks. For example, items in the [issue list](https://gitlab.com/gitlab-org/gitlab-ce/issues) have a green background if they were created recently. Below is an example of a gray content block with side padding using `.row-content-block`. + +![Row content block](img/components-rowcontentblock.png) + +#### Cover blocks +Cover blocks are generally used to create a heading element for a page, such as a new project, or a user profile page. Below is a cover block (`.cover-block`) for the profile page with an avatar, name and description. + +![Cover block](img/components-coverblock.png) + +--- + +
+ +## Panels + +>>> +TODO: Catalog how we are currently using panels and rationalize how they relate to alerts +>>> + +![Panels](img/components-panels.png) + +--- + +
+ +## Alerts + +>>> +TODO: Catalog how we are currently using alerts +>>> + +![Alerts](img/components-alerts.png) + +--- + +
+ +## Forms + +There are two options shown below regarding the positioning of labels in forms. Both are options to consider based on context and available size. However, it is important to have a consistent treatment of labels in the same form. + +### Types + +#### Labels stack vertically + +Form (`form`) with label rendered above input. + +![Vertical form](img/components-verticalform.png) + +#### Labels side-by-side + +Horizontal form (`form.horizontal-form`) with label rendered inline with input. + +![Horizontal form](img/components-horizontalform.png) + +--- + +
+ +## File holders +A file holder (`.file-holder`) is used to show the contents of a file inline on a page of GitLab. + +![File Holder component](img/components-fileholder.png) + +--- + +
+ +## Data formats + +### Dates + +#### Exact + +Format for exacts dates should be ‘Mon DD, YYYY’, such as the examples below. + +![Exact date](img/components-dateexact.png) + +#### Relative + +This format relates how long since an action has occurred. The exact date can be shown as a tooltip on hover. + +![Relative date](img/components-daterelative.png) + +### References + +Referencing GitLab items depends on a symbol for each type of item. Typing that symbol will invoke a dropdown that allows you to search for and autocomplete the item you were looking for. References are shown as [links](#links) in context, and hovering on them shows the full title or name of the item. + +![Hovering on a reference](img/components-referencehover.png) + +#### `%` Milestones + +![Milestone reference](img/components-referencemilestone.png) + +#### `#` Issues + +![Issue reference](img/components-referenceissues.png) + +#### `!` Merge Requests + +![Merge request reference](img/components-referencemrs.png) + +#### `~` Labels + +![Labels reference](img/components-referencelabels.png) + +#### `@` People + +![People reference](img/components-referencepeople.png) + +>>> +Open issue: Some commit references use monospace fonts, but others don't. Need to standardize this. +>>> diff --git a/doc/development/ux_guide/features.md b/doc/development/ux_guide/features.md new file mode 100644 index 00000000000..00700af72aa --- /dev/null +++ b/doc/development/ux_guide/features.md @@ -0,0 +1,63 @@ +# Features + +## Contents +* [Navigation](#navigation) +* [Filtering](#filtering) +* [Search results](#search-results) +* [Conversations](#conversations) +* [Empty states](#empty-states) + +--- + +## Navigation + +### Global navigation + +The global navigation is accessible via the menu button on the top left of the screen, and can be pinned to keep it open. It contains a consistent list of pages that allow you to view content that is across GitLab. For example, you can view your todos, issues and merge requests across projects and groups. + +![Global nav](img/features-globalnav.png) + + +### Contextual navigation + +The navigation in the header is contextual to each page. These options change depending on if you are looking at a project, group, or settings page. There should be no more than 10 items on a level in the contextual navigation, allowing it to comfortably fit on a typical laptop screen. There can be up to too levels of navigation. Each sub nav group should be a self-contained group of functionality. For example, everything related to the issue tracker should be under the 'Issue' tab, while everything relating to the wiki will be grouped under the 'Wiki' tab. The names used for each section should be short and easy to remember, ideally 1-2 words in length. + +![Contextual nav](img/features-contextualnav.png) + +### Information architecture + +The [GitLab Product Map](https://gitlab.com/gitlab-org/gitlab-design/raw/master/production/resources/gitlab-map.png) shows a visual representation of the information architecture for GitLab. + +--- + +
+ +## Filtering + +Today, lists are filtered by a series of dropdowns. Some of these dropdowns allow multiselect (labels), while others allow you to filter to one option (milestones). However, we are currently implementing a [new model](https://gitlab.com/gitlab-org/gitlab-ce/issues/21747) for this, and will update the guide when it is ready. + +![Filters](img/features-filters.png) + +--- + +
+ +## Search results + +### Global search + +[Global search](https://gitlab.com/search?group_id=&project_id=13083&repository_ref=&scope=issues&search=mobile) allows you to search across items in a project, or even across multiple projects. You can switch tabs to filter on type of object, or filter by group. + +### List search + +There are several core lists in the GitLab experience, such as the Issue list and the Merge Request list. You are also able to [filter and search these lists](https://gitlab.com/gitlab-org/gitlab-ce/issues?utf8=%E2%9C%93&search=mobile). This UI will be updated with the [new filtering model](https://gitlab.com/gitlab-org/gitlab-ce/issues/21747). + +--- + +
+ +## Empty states + +Empty states need to be considered in the design of features. They are vital to helping onboard new users, making the experience feel more approachable and understandable. Empty states should feel inviting and provide just enough information to get people started. There should be a single call to action and a clear explanation of what to use the feature for. + +![Empty states](img/features-emptystates.png) diff --git a/doc/development/ux_guide/img/button-primary.png b/doc/development/ux_guide/img/button-primary.png new file mode 100644 index 00000000000..f4c673f5b88 Binary files /dev/null and b/doc/development/ux_guide/img/button-primary.png differ diff --git a/doc/development/ux_guide/img/button-secondary.png b/doc/development/ux_guide/img/button-secondary.png new file mode 100644 index 00000000000..57fa65b247c Binary files /dev/null and b/doc/development/ux_guide/img/button-secondary.png differ diff --git a/doc/development/ux_guide/img/color-blue.png b/doc/development/ux_guide/img/color-blue.png new file mode 100644 index 00000000000..6449613eb16 Binary files /dev/null and b/doc/development/ux_guide/img/color-blue.png differ diff --git a/doc/development/ux_guide/img/color-green.png b/doc/development/ux_guide/img/color-green.png new file mode 100644 index 00000000000..15475b36f02 Binary files /dev/null and b/doc/development/ux_guide/img/color-green.png differ diff --git a/doc/development/ux_guide/img/color-grey.png b/doc/development/ux_guide/img/color-grey.png new file mode 100644 index 00000000000..58c474d5ce9 Binary files /dev/null and b/doc/development/ux_guide/img/color-grey.png differ diff --git a/doc/development/ux_guide/img/color-orange.png b/doc/development/ux_guide/img/color-orange.png new file mode 100644 index 00000000000..f4fc09b2d9b Binary files /dev/null and b/doc/development/ux_guide/img/color-orange.png differ diff --git a/doc/development/ux_guide/img/color-red.png b/doc/development/ux_guide/img/color-red.png new file mode 100644 index 00000000000..6fbbf0a885d Binary files /dev/null and b/doc/development/ux_guide/img/color-red.png differ diff --git a/doc/development/ux_guide/img/components-alerts.png b/doc/development/ux_guide/img/components-alerts.png new file mode 100644 index 00000000000..0b2ecc16a5f Binary files /dev/null and b/doc/development/ux_guide/img/components-alerts.png differ diff --git a/doc/development/ux_guide/img/components-anchorlinks.png b/doc/development/ux_guide/img/components-anchorlinks.png new file mode 100644 index 00000000000..950f348277d Binary files /dev/null and b/doc/development/ux_guide/img/components-anchorlinks.png differ diff --git a/doc/development/ux_guide/img/components-contentblock.png b/doc/development/ux_guide/img/components-contentblock.png new file mode 100644 index 00000000000..31fc1eec9df Binary files /dev/null and b/doc/development/ux_guide/img/components-contentblock.png differ diff --git a/doc/development/ux_guide/img/components-counts.png b/doc/development/ux_guide/img/components-counts.png new file mode 100644 index 00000000000..19280e988a0 Binary files /dev/null and b/doc/development/ux_guide/img/components-counts.png differ diff --git a/doc/development/ux_guide/img/components-coverblock.png b/doc/development/ux_guide/img/components-coverblock.png new file mode 100644 index 00000000000..c8f1f87a108 Binary files /dev/null and b/doc/development/ux_guide/img/components-coverblock.png differ diff --git a/doc/development/ux_guide/img/components-dateexact.png b/doc/development/ux_guide/img/components-dateexact.png new file mode 100644 index 00000000000..8c0c5c1be40 Binary files /dev/null and b/doc/development/ux_guide/img/components-dateexact.png differ diff --git a/doc/development/ux_guide/img/components-daterelative.png b/doc/development/ux_guide/img/components-daterelative.png new file mode 100644 index 00000000000..1dc6d89e4ef Binary files /dev/null and b/doc/development/ux_guide/img/components-daterelative.png differ diff --git a/doc/development/ux_guide/img/components-dropdown.png b/doc/development/ux_guide/img/components-dropdown.png new file mode 100644 index 00000000000..5770a393b37 Binary files /dev/null and b/doc/development/ux_guide/img/components-dropdown.png differ diff --git a/doc/development/ux_guide/img/components-fileholder.png b/doc/development/ux_guide/img/components-fileholder.png new file mode 100644 index 00000000000..4b8962905d6 Binary files /dev/null and b/doc/development/ux_guide/img/components-fileholder.png differ diff --git a/doc/development/ux_guide/img/components-horizontalform.png b/doc/development/ux_guide/img/components-horizontalform.png new file mode 100644 index 00000000000..92e28cf9afc Binary files /dev/null and b/doc/development/ux_guide/img/components-horizontalform.png differ diff --git a/doc/development/ux_guide/img/components-listinsidepanel.png b/doc/development/ux_guide/img/components-listinsidepanel.png new file mode 100644 index 00000000000..30ceb3eaa08 Binary files /dev/null and b/doc/development/ux_guide/img/components-listinsidepanel.png differ diff --git a/doc/development/ux_guide/img/components-listwithavatar.png b/doc/development/ux_guide/img/components-listwithavatar.png new file mode 100644 index 00000000000..d3cb0ebc02b Binary files /dev/null and b/doc/development/ux_guide/img/components-listwithavatar.png differ diff --git a/doc/development/ux_guide/img/components-listwithhover.png b/doc/development/ux_guide/img/components-listwithhover.png new file mode 100644 index 00000000000..1484ecba6a0 Binary files /dev/null and b/doc/development/ux_guide/img/components-listwithhover.png differ diff --git a/doc/development/ux_guide/img/components-panels.png b/doc/development/ux_guide/img/components-panels.png new file mode 100644 index 00000000000..6e71d0ad9c9 Binary files /dev/null and b/doc/development/ux_guide/img/components-panels.png differ diff --git a/doc/development/ux_guide/img/components-referencehover.png b/doc/development/ux_guide/img/components-referencehover.png new file mode 100644 index 00000000000..e9fb27e2aa9 Binary files /dev/null and b/doc/development/ux_guide/img/components-referencehover.png differ diff --git a/doc/development/ux_guide/img/components-referenceissues.png b/doc/development/ux_guide/img/components-referenceissues.png new file mode 100644 index 00000000000..caf9477db38 Binary files /dev/null and b/doc/development/ux_guide/img/components-referenceissues.png differ diff --git a/doc/development/ux_guide/img/components-referencelabels.png b/doc/development/ux_guide/img/components-referencelabels.png new file mode 100644 index 00000000000..a122b45d1f1 Binary files /dev/null and b/doc/development/ux_guide/img/components-referencelabels.png differ diff --git a/doc/development/ux_guide/img/components-referencemilestone.png b/doc/development/ux_guide/img/components-referencemilestone.png new file mode 100644 index 00000000000..5aa9ecd1a78 Binary files /dev/null and b/doc/development/ux_guide/img/components-referencemilestone.png differ diff --git a/doc/development/ux_guide/img/components-referencemrs.png b/doc/development/ux_guide/img/components-referencemrs.png new file mode 100644 index 00000000000..6280243859a Binary files /dev/null and b/doc/development/ux_guide/img/components-referencemrs.png differ diff --git a/doc/development/ux_guide/img/components-referencepeople.png b/doc/development/ux_guide/img/components-referencepeople.png new file mode 100644 index 00000000000..99772a539cf Binary files /dev/null and b/doc/development/ux_guide/img/components-referencepeople.png differ diff --git a/doc/development/ux_guide/img/components-rowcontentblock.png b/doc/development/ux_guide/img/components-rowcontentblock.png new file mode 100644 index 00000000000..1c2d7096955 Binary files /dev/null and b/doc/development/ux_guide/img/components-rowcontentblock.png differ diff --git a/doc/development/ux_guide/img/components-simplelist.png b/doc/development/ux_guide/img/components-simplelist.png new file mode 100644 index 00000000000..892f507cfc2 Binary files /dev/null and b/doc/development/ux_guide/img/components-simplelist.png differ diff --git a/doc/development/ux_guide/img/components-table.png b/doc/development/ux_guide/img/components-table.png new file mode 100644 index 00000000000..7e964c885cf Binary files /dev/null and b/doc/development/ux_guide/img/components-table.png differ diff --git a/doc/development/ux_guide/img/components-verticalform.png b/doc/development/ux_guide/img/components-verticalform.png new file mode 100644 index 00000000000..38863ad3c1c Binary files /dev/null and b/doc/development/ux_guide/img/components-verticalform.png differ diff --git a/doc/development/ux_guide/img/features-contextualnav.png b/doc/development/ux_guide/img/features-contextualnav.png new file mode 100644 index 00000000000..df157f54c84 Binary files /dev/null and b/doc/development/ux_guide/img/features-contextualnav.png differ diff --git a/doc/development/ux_guide/img/features-emptystates.png b/doc/development/ux_guide/img/features-emptystates.png new file mode 100644 index 00000000000..3befc14588e Binary files /dev/null and b/doc/development/ux_guide/img/features-emptystates.png differ diff --git a/doc/development/ux_guide/img/features-filters.png b/doc/development/ux_guide/img/features-filters.png new file mode 100644 index 00000000000..281e55d590c Binary files /dev/null and b/doc/development/ux_guide/img/features-filters.png differ diff --git a/doc/development/ux_guide/img/features-globalnav.png b/doc/development/ux_guide/img/features-globalnav.png new file mode 100644 index 00000000000..3c0db2247ca Binary files /dev/null and b/doc/development/ux_guide/img/features-globalnav.png differ diff --git a/doc/development/ux_guide/img/icon-add.png b/doc/development/ux_guide/img/icon-add.png new file mode 100644 index 00000000000..0d4c1a7692a Binary files /dev/null and b/doc/development/ux_guide/img/icon-add.png differ diff --git a/doc/development/ux_guide/img/icon-close.png b/doc/development/ux_guide/img/icon-close.png new file mode 100644 index 00000000000..88d2b3b0c6d Binary files /dev/null and b/doc/development/ux_guide/img/icon-close.png differ diff --git a/doc/development/ux_guide/img/icon-edit.png b/doc/development/ux_guide/img/icon-edit.png new file mode 100644 index 00000000000..f73be7a10fb Binary files /dev/null and b/doc/development/ux_guide/img/icon-edit.png differ diff --git a/doc/development/ux_guide/img/icon-notification.png b/doc/development/ux_guide/img/icon-notification.png new file mode 100644 index 00000000000..4758632edd7 Binary files /dev/null and b/doc/development/ux_guide/img/icon-notification.png differ diff --git a/doc/development/ux_guide/img/icon-rss.png b/doc/development/ux_guide/img/icon-rss.png new file mode 100644 index 00000000000..c7ac9fb1349 Binary files /dev/null and b/doc/development/ux_guide/img/icon-rss.png differ diff --git a/doc/development/ux_guide/img/icon-subscribe.png b/doc/development/ux_guide/img/icon-subscribe.png new file mode 100644 index 00000000000..5cb277bfd5d Binary files /dev/null and b/doc/development/ux_guide/img/icon-subscribe.png differ diff --git a/doc/development/ux_guide/img/icon-trash.png b/doc/development/ux_guide/img/icon-trash.png new file mode 100644 index 00000000000..357289a6fff Binary files /dev/null and b/doc/development/ux_guide/img/icon-trash.png differ diff --git a/doc/development/ux_guide/img/monospacefont-sample.png b/doc/development/ux_guide/img/monospacefont-sample.png new file mode 100644 index 00000000000..1cd290b713c Binary files /dev/null and b/doc/development/ux_guide/img/monospacefont-sample.png differ diff --git a/doc/development/ux_guide/img/sourcesanspro-sample.png b/doc/development/ux_guide/img/sourcesanspro-sample.png new file mode 100644 index 00000000000..f7ecf0c7c66 Binary files /dev/null and b/doc/development/ux_guide/img/sourcesanspro-sample.png differ diff --git a/doc/development/ux_guide/img/surfaces-contentitemtitle.png b/doc/development/ux_guide/img/surfaces-contentitemtitle.png new file mode 100644 index 00000000000..2eb926c1c43 Binary files /dev/null and b/doc/development/ux_guide/img/surfaces-contentitemtitle.png differ diff --git a/doc/development/ux_guide/img/surfaces-header.png b/doc/development/ux_guide/img/surfaces-header.png new file mode 100644 index 00000000000..ab44d4de696 Binary files /dev/null and b/doc/development/ux_guide/img/surfaces-header.png differ diff --git a/doc/development/ux_guide/img/surfaces-systeminformationblock.png b/doc/development/ux_guide/img/surfaces-systeminformationblock.png new file mode 100644 index 00000000000..5d91e993e24 Binary files /dev/null and b/doc/development/ux_guide/img/surfaces-systeminformationblock.png differ diff --git a/doc/development/ux_guide/img/surfaces-ux.png b/doc/development/ux_guide/img/surfaces-ux.png new file mode 100644 index 00000000000..e692c51e8c0 Binary files /dev/null and b/doc/development/ux_guide/img/surfaces-ux.png differ diff --git a/doc/development/ux_guide/img/tooltip-placement.png b/doc/development/ux_guide/img/tooltip-placement.png new file mode 100644 index 00000000000..29a61c8400a Binary files /dev/null and b/doc/development/ux_guide/img/tooltip-placement.png differ diff --git a/doc/development/ux_guide/img/tooltip-usage.png b/doc/development/ux_guide/img/tooltip-usage.png new file mode 100644 index 00000000000..e8e4c6ded91 Binary files /dev/null and b/doc/development/ux_guide/img/tooltip-usage.png differ diff --git a/doc/development/ux_guide/principles.md b/doc/development/ux_guide/principles.md new file mode 100644 index 00000000000..32520845e41 --- /dev/null +++ b/doc/development/ux_guide/principles.md @@ -0,0 +1,29 @@ +# Principles + +These are the guiding principles that we should strive for to establish a solid foundation for the GitLab experience. + +
+ +## Professional and productive +GitLab is a tool to support what people do, day in, day out. We need to respect the importance of their work, and avoid gimicky details. + +
+ +## Minimal and efficient +While work can get complicated, GitLab is about bringing a sharp focus, helping our customers know what matters now. + +
+ +## Immediately recognizable +When you look at any screen, you should know immediately that it is GitLab. Our personality is strong and consistent across product and marketing experiences. + +
+ +## Human and quirky +We need to build empathy with our users, understanding their state of mind, and connect with them at a human level. Quirkiness is part of our DNA, and we should embrace it in the right moments and contexts. + +
+ +>>> +TODO: Ensure these principles align well with the goals of the Marketing team +>>> \ No newline at end of file diff --git a/doc/development/ux_guide/resources.md b/doc/development/ux_guide/resources.md new file mode 100644 index 00000000000..2f760c94414 --- /dev/null +++ b/doc/development/ux_guide/resources.md @@ -0,0 +1,13 @@ +# Resources + +## GitLab UI development kit + +We created a page inside GitLab where you can check commonly used html and css elements. + +When you run GitLab instance locally - just visit http://localhost:3000/help/ui page to see UI examples +you can use during GitLab development. + +## Design repository + +All design files are stored in the [gitlab-design](https://gitlab.com/gitlab-org/gitlab-design) +repository and maintained by GitLab UX designers. \ No newline at end of file diff --git a/doc/development/ux_guide/surfaces.md b/doc/development/ux_guide/surfaces.md new file mode 100644 index 00000000000..d9e48a66185 --- /dev/null +++ b/doc/development/ux_guide/surfaces.md @@ -0,0 +1,53 @@ +# Surfaces + +## Contents +* [Header](#header) +* [Global menu](#global-menu) +* [Side pane](#side-pane) +* [Content area](#content-area) + +--- + +![Surfaces UX](img/surfaces-ux.png) + +## Global menu + +This menu is to navigate to pages that contain content global to GitLab. + +--- + +
+ +## Header + +The header contains 3 main elements: Project switching and searching, user account avatar and settings, and a contextual menu that changes based on the current page. + +![Surfaces Header](img/surfaces-header.png) + +--- + +
+ +## Side pane + +The side pane holds supporting information and meta data for the information in the content area. + +--- + +
+ +## Content area + +The main content of the page. The content area can include other surfaces. + +### Item title bar + +The item title bar contains the top level information to identify the item, such as the name, id and status. + +![Item title](img/surfaces-contentitemtitle.png) + +### Item system information + +The system information block contains relevant system controlled information. + +![Item system information](img/surfaces-systeminformationblock.png) \ No newline at end of file diff --git a/doc/development/ux_guide/tips.md b/doc/development/ux_guide/tips.md new file mode 100644 index 00000000000..190ce9a2ee9 --- /dev/null +++ b/doc/development/ux_guide/tips.md @@ -0,0 +1,46 @@ +# Tips + +## Contents +* [SVGs](#svgs) + +--- + +## SVGs + +When exporting SVGs, be sure to follow the following guidelines: + +1. Convert all strokes to outlines. +2. Use pathfinder tools to combine overlapping paths and create compound paths. +3. SVGs that are limited to one color should be exported without a fill color so the color can be set using CSS. +4. Ensure that exported SVGs have been run through an [SVG cleaner](https://github.com/RazrFalcon/SVGCleaner) to remove unused elements and attributes. + +You can open your svg in a text editor to ensure that it is clean. +Incorrect files will look like this: + +```xml + + + + Group + Created with Sketch. + + + + + + + + + + +``` + +Correct file will look like this: + +```xml + +``` + +>>> +TODO: Checkout [https://github.com/svg/svgo](https://github.com/svg/svgo) +>>> \ No newline at end of file diff --git a/doc/development/ux_guide/users.md b/doc/development/ux_guide/users.md new file mode 100644 index 00000000000..cab4190604e --- /dev/null +++ b/doc/development/ux_guide/users.md @@ -0,0 +1,18 @@ +# Users + +>>> +TODO: Create personas. Understand the similarities and differences across the below spectrums. +>>> + +## Users by organization + +- Enterprise +- Medium company +- Small company +- Open source communities + +## Users by role + +- Admin +- Manager +- Developer \ No newline at end of file -- cgit v1.2.1 From deef24a27dd09f7f42221e6900a1b96db0e4ad47 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Fri, 11 Nov 2016 18:20:41 +0100 Subject: Rename README.md to index.md --- doc/development/ux_guide/README.md | 59 -------------------------------------- doc/development/ux_guide/index.md | 53 ++++++++++++++++++++++++++++++++++ 2 files changed, 53 insertions(+), 59 deletions(-) delete mode 100644 doc/development/ux_guide/README.md create mode 100644 doc/development/ux_guide/index.md (limited to 'doc/development') diff --git a/doc/development/ux_guide/README.md b/doc/development/ux_guide/README.md deleted file mode 100644 index e17a4559069..00000000000 --- a/doc/development/ux_guide/README.md +++ /dev/null @@ -1,59 +0,0 @@ -# GitLab UX Guide - -The goal of this guide is to provide standards, principles and in-depth information to design beautiful and effective GitLab features. This will be a living document, and we welcome contributions, feedback and suggestions. - -## Design - ---- - -### [Principles](principles.md) -These guiding principles set a solid foundation for our design system, and should remain relatively stable over multiple releases. They should be referenced as new design patterns are created. - ---- - -### [Basics](basics.md) -The basic ingredients of our experience establish our personality and feel. This section includes details about typography, color, and motion. - ---- - -### [Components](components.md) -Components are the controls that make up the GitLab experience, including guidance around buttons, links, dropdowns, etc. - ---- - -### [Surfaces](surfaces.md) -The GitLab experience is broken apart into several surfaces. Each of these surfaces is designated for a specific scope or type of content. Examples include the header, global menu, side pane, etc. - ---- - -### [Features](features.md) -The previous building blocks are combined into complete features in the GitLab UX. Examples include our navigation, filters, search results, and empty states. - ---- - -
- -## Research - ---- - -### [Users](users.md) -How we think about the variety of users of GitLab, from small to large teams, comparing opensource usage to enterprise, etc. - ---- - -
- -## Other - ---- - -### [Tips for designers](tips.md) -Tips for exporting assets, and other guidance. - ---- - -### [Resources](resources.md) -Resources for GitLab UX - ---- diff --git a/doc/development/ux_guide/index.md b/doc/development/ux_guide/index.md new file mode 100644 index 00000000000..1a61be4ed51 --- /dev/null +++ b/doc/development/ux_guide/index.md @@ -0,0 +1,53 @@ +# GitLab UX Guide + +The goal of this guide is to provide standards, principles and in-depth information to design beautiful and effective GitLab features. This will be a living document, and we welcome contributions, feedback and suggestions. + +## Design + +--- + +### [Principles](principles.md) +These guiding principles set a solid foundation for our design system, and should remain relatively stable over multiple releases. They should be referenced as new design patterns are created. + +--- + +### [Basics](basics.md) +The basic ingredients of our experience establish our personality and feel. This section includes details about typography, color, and motion. + +--- + +### [Components](components.md) +Components are the controls that make up the GitLab experience, including guidance around buttons, links, dropdowns, etc. + +--- + +### [Surfaces](surfaces.md) +The GitLab experience is broken apart into several surfaces. Each of these surfaces is designated for a specific scope or type of content. Examples include the header, global menu, side pane, etc. + +--- + +### [Features](features.md) +The previous building blocks are combined into complete features in the GitLab UX. Examples include our navigation, filters, search results, and empty states. + +--- + +## Research + +--- + +### [Users](users.md) +How we think about the variety of users of GitLab, from small to large teams, comparing opensource usage to enterprise, etc. + +--- + +## Other + +--- + +### [Tips for designers](tips.md) +Tips for exporting assets, and other guidance. + +--- + +### [Resources](resources.md) +Resources for GitLab UX -- cgit v1.2.1 From 406eda17d444e534bfa429d8c72a90c8f91a6f00 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Fri, 11 Nov 2016 18:20:56 +0100 Subject: Remove
and replace GFM blockquote with the Markdown general [ci skip] --- doc/development/ux_guide/basics.md | 26 ++++---------------------- doc/development/ux_guide/components.md | 30 +----------------------------- doc/development/ux_guide/features.md | 6 ------ doc/development/ux_guide/principles.md | 14 +------------- doc/development/ux_guide/surfaces.md | 8 +------- doc/development/ux_guide/tips.md | 4 +--- doc/development/ux_guide/users.md | 6 ++---- 7 files changed, 10 insertions(+), 84 deletions(-) (limited to 'doc/development') diff --git a/doc/development/ux_guide/basics.md b/doc/development/ux_guide/basics.md index 7e7cb103694..62ac56a6bce 100644 --- a/doc/development/ux_guide/basics.md +++ b/doc/development/ux_guide/basics.md @@ -10,15 +10,11 @@ --- -
- ## Responsive GitLab is a responsive experience that works well across all screen sizes, from mobile devices to large monitors. In order to provide a great user experience, the core functionality (browsing files, creating issues, writing comments, etc.) must be available at all resolutions. However, due to size limitations, some secondary functionality may be hidden on smaller screens. Please keep this functionality limited to rare actions that aren't expected to be needed on small devices. --- -
- ## Typography ### Primary typeface GitLab's main typeface used throughout the UI is **Source Sans Pro**. We support both the bold and regular weight. @@ -36,8 +32,6 @@ This is the typeface used for code blocks. GitLab uses the OS default font. --- -
- ## Icons GitLab uses Font Awesome icons throughout our interface. @@ -62,14 +56,10 @@ An 'x' is used for closing UI elements such as dropdowns. ![Add icon](img/icon-add.png) A plus is used when creating new objects, such as issues, projects, etc. ->>> -TODO: update this section, add more general guidance to icon usage and personality, etc. ->>> +> TODO: update this section, add more general guidance to icon usage and personality, etc. --- -
- ## Color ![Blue](img/color-blue.png) @@ -87,26 +77,18 @@ Red is reserved for delete and other destructive commands ![Grey](img/color-grey.png) Grey, and white (depending on context) is used for netral, secondary elements ->>> -TODO: Establish a perspective for color in terms of our personality and rationalize with Marketing usage. ->>> +> TODO: Establish a perspective for color in terms of our personality and rationalize with Marketing usage. --- -
- ## Motion Motion is a tool to help convey important relationships, changes or transitions between elements. It should be used sparingly and intentionally, highlighting the right elements at the right moment. ->>> -TODO: Determine a more concrete perspective on motion, create consistent easing/timing curves to follow. ->>> +> TODO: Determine a more concrete perspective on motion, create consistent easing/timing curves to follow. --- -
- ## Voice and tone -The copy for GitLab is clear and direct. We strike a clear balance between professional and friendly. We can empathesize with users (such as celebrating completing all Todos), and remain respectful of the importance of the work. We are that trusted, friendly coworker that is helpful and understanding. \ No newline at end of file +The copy for GitLab is clear and direct. We strike a clear balance between professional and friendly. We can empathesize with users (such as celebrating completing all Todos), and remain respectful of the importance of the work. We are that trusted, friendly coworker that is helpful and understanding. diff --git a/doc/development/ux_guide/components.md b/doc/development/ux_guide/components.md index 6b21566265c..764c3355714 100644 --- a/doc/development/ux_guide/components.md +++ b/doc/development/ux_guide/components.md @@ -17,8 +17,6 @@ --- -
- ## Tooltips ### Usage @@ -33,8 +31,6 @@ By default, tooltips should be placed below the element that they refer to. Howe --- -
- ## Anchor links Anchor links are used for navigational actions and lone, secondary commands (such as 'Reset filters' on the Issues List) when deemed appropriate by the UX team. @@ -57,8 +53,6 @@ The focus state should match the hover state. --- -
- ## Buttons Buttons communicate the command that will occur when the user clicks on them. @@ -87,8 +81,6 @@ Follow the color guidance on the [basics](basics.md#color) page. The default col --- -
- ## Dropdowns Dropdowns are used to allow users to choose one (or many) options from a list of options. If this list of options is more 20, there should generally be a way to search through and filter the options (see the complex filter dropdowns below.) @@ -103,8 +95,6 @@ TODO: Will update this section when the new filters UI is implemented. --- -
- ## Counts A count element is used in navigation contexts where it is helpful to indicate the count, or number of items, in a list. Always use the [`number_with_delimiter`][number_with_delimiter] helper to display counts in the UI. @@ -115,8 +105,6 @@ A count element is used in navigation contexts where it is helpful to indicate t --- -
- ## Lists Lists are used where ever there is a single column of information to display. Ths [issues list](https://gitlab.com/gitlab-org/gitlab-ce/issues) is an example of a important list in the GitLab UI. @@ -141,8 +129,6 @@ List inside panel --- -
- ## Tables When the information is too complex for a list, with multiple columns of information, a table can be used. For example, the [pipelines page](https://gitlab.com/gitlab-org/gitlab-ce/pipelines) uses a table. @@ -151,8 +137,6 @@ When the information is too complex for a list, with multiple columns of informa --- -
- ## Blocks Blocks are a way to group related information. @@ -178,8 +162,6 @@ Cover blocks are generally used to create a heading element for a page, such as --- -
- ## Panels >>> @@ -190,8 +172,6 @@ TODO: Catalog how we are currently using panels and rationalize how they relate --- -
- ## Alerts >>> @@ -202,8 +182,6 @@ TODO: Catalog how we are currently using alerts --- -
- ## Forms There are two options shown below regarding the positioning of labels in forms. Both are options to consider based on context and available size. However, it is important to have a consistent treatment of labels in the same form. @@ -224,8 +202,6 @@ Horizontal form (`form.horizontal-form`) with label rendered inline with input. --- -
- ## File holders A file holder (`.file-holder`) is used to show the contents of a file inline on a page of GitLab. @@ -233,8 +209,6 @@ A file holder (`.file-holder`) is used to show the contents of a file inline on --- -
- ## Data formats ### Dates @@ -277,6 +251,4 @@ Referencing GitLab items depends on a symbol for each type of item. Typing that ![People reference](img/components-referencepeople.png) ->>> -Open issue: Some commit references use monospace fonts, but others don't. Need to standardize this. ->>> +> TODO: Open issue: Some commit references use monospace fonts, but others don't. Need to standardize this. diff --git a/doc/development/ux_guide/features.md b/doc/development/ux_guide/features.md index 00700af72aa..9472995c68c 100644 --- a/doc/development/ux_guide/features.md +++ b/doc/development/ux_guide/features.md @@ -30,8 +30,6 @@ The [GitLab Product Map](https://gitlab.com/gitlab-org/gitlab-design/raw/master/ --- -
- ## Filtering Today, lists are filtered by a series of dropdowns. Some of these dropdowns allow multiselect (labels), while others allow you to filter to one option (milestones). However, we are currently implementing a [new model](https://gitlab.com/gitlab-org/gitlab-ce/issues/21747) for this, and will update the guide when it is ready. @@ -40,8 +38,6 @@ Today, lists are filtered by a series of dropdowns. Some of these dropdowns allo --- -
- ## Search results ### Global search @@ -54,8 +50,6 @@ There are several core lists in the GitLab experience, such as the Issue list an --- -
- ## Empty states Empty states need to be considered in the design of features. They are vital to helping onboard new users, making the experience feel more approachable and understandable. Empty states should feel inviting and provide just enough information to get people started. There should be a single call to action and a clear explanation of what to use the feature for. diff --git a/doc/development/ux_guide/principles.md b/doc/development/ux_guide/principles.md index 32520845e41..1a297cba2cc 100644 --- a/doc/development/ux_guide/principles.md +++ b/doc/development/ux_guide/principles.md @@ -2,28 +2,16 @@ These are the guiding principles that we should strive for to establish a solid foundation for the GitLab experience. -
- ## Professional and productive GitLab is a tool to support what people do, day in, day out. We need to respect the importance of their work, and avoid gimicky details. -
- ## Minimal and efficient While work can get complicated, GitLab is about bringing a sharp focus, helping our customers know what matters now. -
- ## Immediately recognizable When you look at any screen, you should know immediately that it is GitLab. Our personality is strong and consistent across product and marketing experiences. -
- ## Human and quirky We need to build empathy with our users, understanding their state of mind, and connect with them at a human level. Quirkiness is part of our DNA, and we should embrace it in the right moments and contexts. -
- ->>> -TODO: Ensure these principles align well with the goals of the Marketing team ->>> \ No newline at end of file +> TODO: Ensure these principles align well with the goals of the Marketing team diff --git a/doc/development/ux_guide/surfaces.md b/doc/development/ux_guide/surfaces.md index d9e48a66185..881d6aa4cd6 100644 --- a/doc/development/ux_guide/surfaces.md +++ b/doc/development/ux_guide/surfaces.md @@ -16,8 +16,6 @@ This menu is to navigate to pages that contain content global to GitLab. --- -
- ## Header The header contains 3 main elements: Project switching and searching, user account avatar and settings, and a contextual menu that changes based on the current page. @@ -26,16 +24,12 @@ The header contains 3 main elements: Project switching and searching, user accou --- -
- ## Side pane The side pane holds supporting information and meta data for the information in the content area. --- -
- ## Content area The main content of the page. The content area can include other surfaces. @@ -50,4 +44,4 @@ The item title bar contains the top level information to identify the item, such The system information block contains relevant system controlled information. -![Item system information](img/surfaces-systeminformationblock.png) \ No newline at end of file +![Item system information](img/surfaces-systeminformationblock.png) diff --git a/doc/development/ux_guide/tips.md b/doc/development/ux_guide/tips.md index 190ce9a2ee9..8348de4f8a2 100644 --- a/doc/development/ux_guide/tips.md +++ b/doc/development/ux_guide/tips.md @@ -41,6 +41,4 @@ Correct file will look like this: ``` ->>> -TODO: Checkout [https://github.com/svg/svgo](https://github.com/svg/svgo) ->>> \ No newline at end of file +> TODO: Checkout [https://github.com/svg/svgo](https://github.com/svg/svgo) diff --git a/doc/development/ux_guide/users.md b/doc/development/ux_guide/users.md index cab4190604e..717a902c424 100644 --- a/doc/development/ux_guide/users.md +++ b/doc/development/ux_guide/users.md @@ -1,8 +1,6 @@ # Users ->>> -TODO: Create personas. Understand the similarities and differences across the below spectrums. ->>> +> TODO: Create personas. Understand the similarities and differences across the below spectrums. ## Users by organization @@ -15,4 +13,4 @@ TODO: Create personas. Understand the similarities and differences across the be - Admin - Manager -- Developer \ No newline at end of file +- Developer -- cgit v1.2.1 From 8b70a89c57d41d035e4b8ba06cc33859383f095a Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Sat, 12 Nov 2016 20:48:41 +0100 Subject: Fix link to index.md in development README.md [ci skip] --- doc/development/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/development') diff --git a/doc/development/README.md b/doc/development/README.md index 87306b1501d..f88456a7a7a 100644 --- a/doc/development/README.md +++ b/doc/development/README.md @@ -14,7 +14,7 @@ contributing to documentation. - [SQL Migration Style Guide](migration_style_guide.md) for creating safe SQL migrations - [Testing standards and style guidelines](testing.md) -- [UX guide](ux_guide/README.md) for building GitLab with existing CSS styles and elements +- [UX guide](ux_guide/index.md) for building GitLab with existing CSS styles and elements - [Frontend guidelines](frontend.md) - [SQL guidelines](sql.md) for working with SQL queries - [Sidekiq guidelines](sidekiq_style_guide.md) for working with Sidekiq workers -- cgit v1.2.1 From f92ea120bae61c071f8588befd2c82ec5ce0e302 Mon Sep 17 00:00:00 2001 From: Victor Wu Date: Mon, 14 Nov 2016 18:52:09 +0000 Subject: [ci skip] Link to the copy (messaging) page. Add new file for copy (messaging) guidelines Update copy guidelines Fix typo Add forms to guidelines Simplify Copy heading Refine copy page. Add images and table Fix toc link on Copy page --- doc/development/ux_guide/copy.md | 78 +++++++++++++++++++++ .../ux_guide/img/copy-form-addissuebutton.png | Bin 0 -> 26541 bytes .../ux_guide/img/copy-form-addissueform.png | Bin 0 -> 38242 bytes .../ux_guide/img/copy-form-editissuebutton.png | Bin 0 -> 16466 bytes .../ux_guide/img/copy-form-editissueform.png | Bin 0 -> 40660 bytes doc/development/ux_guide/index.md | 5 ++ 6 files changed, 83 insertions(+) create mode 100644 doc/development/ux_guide/copy.md create mode 100644 doc/development/ux_guide/img/copy-form-addissuebutton.png create mode 100644 doc/development/ux_guide/img/copy-form-addissueform.png create mode 100644 doc/development/ux_guide/img/copy-form-editissuebutton.png create mode 100644 doc/development/ux_guide/img/copy-form-editissueform.png (limited to 'doc/development') diff --git a/doc/development/ux_guide/copy.md b/doc/development/ux_guide/copy.md new file mode 100644 index 00000000000..03392a003ee --- /dev/null +++ b/doc/development/ux_guide/copy.md @@ -0,0 +1,78 @@ +# Copy + +The copy and messaging is a core part of the experience of GitLab and the conversation with our users. Follow the below conventions throughout GitLab. + +>**Note:** +We are currently inconsistent with this guidance. Images below are created to illustrate the point. As this guidance is refined, we will ensure that our experiences align. + +## Contents +* [Brevity](#brevity) +* [Forms](#forms) +* [Terminology](#terminology) + +--- + +## Brevity +Users will skim content, rather than read text carefully. +When familiar with a web app, users rely on muscle memory, and may read even less when moving quickly. +A good experience should quickly orient a user, regardless of their experience, to the purpose of the current screen. This should happen without the user having to consciously read long strings of text. +In general, text is burdensome and adds cognitive load. This is especially pronounced in a powerful productivity tool such as GitLab. +We should _not_ rely on words as a crutch to explain the purpose of a screen. +The current navigation and composition of the elements on the screen should get the user 95% there, with the remaining 5% being specific elements such as text. +This means that, as a rule, copy should be very short. A long message or label is a red flag hinting at design that needs improvement. + +>**Example:** +Use `Add` instead of `Add issue` as a button label. +Preferrably use context and placement of controls to make it obvious what clicking on them will do. + +--- + +## Forms + +### Adding items + +When viewing a list of issues, there is a button that is labeled `Add`. Given the context in the example, it is clearly referring to issues. If the context were not clear enough, the label could be `Add issue`. Clicking the button will bring you to the `Add issue` form. Other add flows should be similar. + +![Add issue button](img/copy-form-addissuebutton.png) + +The form should be titled `Add issue`. The submit button should be labeled `Save` or `Submit`. Do not use `Add`, `Create`, `New`, or `Save Changes`. The cancel button should be labeled `Cancel`. Do not use `Back`. + +![Add issue form](img/copy-form-addissueform.png) + +### Editing items + +When in context of an issue, the affordance to edit it is labeled `Edit`. If the context is not clear enough, `Edit issue` could be considered. Other edit flows should be similar. + +![Edit issue button](img/copy-form-editissuebutton.png) + +The form should be titled `Edit Issue`. The submit button should be labeled `Save`. Do not use `Edit`, `Update`, `New`, or `Save Changes`. The cancel button should be labeled `Cancel`. Do not use `Back`. + +![Edit issue form](img/copy-form-editissueform.png) + +--- + +## Terminology + +### Issues + +#### Adjectives (states) + +| Term | Use | +| ---- | --- | +| Open | Issue is active | +| Closed | Issue is no longer active | + +>**Example:** +Use `5 open issues` and do not use `5 pending issues`. +Only use the adjectives in the table above. + +#### Verbs (actions) + +| Term | Use | +| ---- | --- | +| Add | For adding an issue. Do not use `create` or `new` | +| View | View an issue | +| Edit | Edit an issue. Do not use `update` | +| Close | Closing an issue | +| Re-open | Re-open an issue. There should never be a need to use `open` as a verb | +| Delete | Deleting an issue. Do not use `remove` | \ No newline at end of file diff --git a/doc/development/ux_guide/img/copy-form-addissuebutton.png b/doc/development/ux_guide/img/copy-form-addissuebutton.png new file mode 100644 index 00000000000..18839d447e8 Binary files /dev/null and b/doc/development/ux_guide/img/copy-form-addissuebutton.png differ diff --git a/doc/development/ux_guide/img/copy-form-addissueform.png b/doc/development/ux_guide/img/copy-form-addissueform.png new file mode 100644 index 00000000000..e6838c06eca Binary files /dev/null and b/doc/development/ux_guide/img/copy-form-addissueform.png differ diff --git a/doc/development/ux_guide/img/copy-form-editissuebutton.png b/doc/development/ux_guide/img/copy-form-editissuebutton.png new file mode 100644 index 00000000000..2435820e14f Binary files /dev/null and b/doc/development/ux_guide/img/copy-form-editissuebutton.png differ diff --git a/doc/development/ux_guide/img/copy-form-editissueform.png b/doc/development/ux_guide/img/copy-form-editissueform.png new file mode 100644 index 00000000000..5ddeda33e68 Binary files /dev/null and b/doc/development/ux_guide/img/copy-form-editissueform.png differ diff --git a/doc/development/ux_guide/index.md b/doc/development/ux_guide/index.md index 1a61be4ed51..8aed11ebac3 100644 --- a/doc/development/ux_guide/index.md +++ b/doc/development/ux_guide/index.md @@ -26,6 +26,11 @@ The GitLab experience is broken apart into several surfaces. Each of these surfa --- +### [Copy](copy.md) +Conventions on text and messaging within labels, buttons, and other components. + +--- + ### [Features](features.md) The previous building blocks are combined into complete features in the GitLab UX. Examples include our navigation, filters, search results, and empty states. -- cgit v1.2.1 From 600282799606ed260a1149d8312494a2f6a83290 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=C3=A9my=20Coutable?= Date: Thu, 10 Nov 2016 15:24:23 +0100 Subject: Add a gotcha about FactoryGirl sequences MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Related to https://gitlab.com/gitlab-org/gitlab-ce/issues/24341 Signed-off-by: Rémy Coutable --- doc/development/gotchas.md | 89 ++++++++++++++++++++++++++++++++++++++++++++++ doc/development/testing.md | 1 + 2 files changed, 90 insertions(+) (limited to 'doc/development') diff --git a/doc/development/gotchas.md b/doc/development/gotchas.md index b25ce79e89f..7bfc9cb361f 100644 --- a/doc/development/gotchas.md +++ b/doc/development/gotchas.md @@ -32,6 +32,95 @@ spec/models/user_spec.rb|6 error| Failure/Error: u = described_class.new NoMeth Except for the top-level `describe` block, always provide a String argument to `describe`. +## Don't assert against the absolute value of a sequence-generated attribute + +Consider the following factory: + +```ruby +FactoryGirl.define do + factory :label do + sequence(:title) { |n| "label#{n}" } + end +end +``` + +Consider the following API spec: + +```ruby +require 'rails_helper' + +describe API::Labels do + it 'creates a first label' do + create(:label) + + get api("/projects/#{project.id}/labels", user) + + expect(response).to have_http_status(200) + expect(json_response.first['name']).to eq('label1') + end + + it 'creates a second label' do + create(:label) + + get api("/projects/#{project.id}/labels", user) + + expect(response).to have_http_status(200) + expect(json_response.first['name']).to eq('label1') + end +end +``` + +When run, this spec doesn't do what we might expect: + +```sh +1) API::API reproduce sequence issue creates a second label + Failure/Error: expect(json_response.first['name']).to eq('label1') + + expected: "label1" + got: "label2" + + (compared using ==) +``` + +That's because FactoryGirl sequences are not reseted for each example. + +Please remember that sequence-generated values exist only to avoid having to +explicitly set attributes that have a uniqueness constraint when using a factory. + +### Solution + +If you assert against a sequence-generated attribute's value, you should set it +explicitly. Also, the value you set shouldn't match the sequence pattern. + +For instance, using our `:label` factory, writing `create(:label, title: 'foo')` +is ok, but `create(:label, title: 'label1')` is not. + +Following is the fixed API spec: + +```ruby +require 'rails_helper' + +describe API::Labels do + it 'creates a first label' do + create(:label, title: 'foo') + + get api("/projects/#{project.id}/labels", user) + + expect(response).to have_http_status(200) + expect(json_response.first['name']).to eq('foo') + end + + it 'creates a second label' do + create(:label, title: 'bar') + + get api("/projects/#{project.id}/labels", user) + + expect(response).to have_http_status(200) + expect(json_response.first['name']).to eq('bar') + end +end +``` + ## Don't `rescue Exception` See ["Why is it bad style to `rescue Exception => e` in Ruby?"][Exception]. diff --git a/doc/development/testing.md b/doc/development/testing.md index b0b26ccf57a..4dc535fb359 100644 --- a/doc/development/testing.md +++ b/doc/development/testing.md @@ -64,6 +64,7 @@ the command line via `bundle exec teaspoon`, or via a web browser at methods. - Use `context` to test branching logic. - Don't `describe` symbols (see [Gotchas](gotchas.md#dont-describe-symbols)). +- Don't assert against the absolute value of a sequence-generated attribute (see [Gotchas](gotchas.md#dont-assert-against-the-absolute-value-of-a-sequence-generated-attribute)). - Don't supply the `:each` argument to hooks since it's the default. - Prefer `not_to` to `to_not` (_this is enforced by Rubocop_). - Try to match the ordering of tests to the ordering within the class. -- cgit v1.2.1 From 95d552b8dddf70bccd62e3e378264125504e80ec Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=C3=A9my=20Coutable?= Date: Wed, 2 Nov 2016 17:16:06 +0100 Subject: Start to document how to code for CE with EE in mind MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Rémy Coutable --- doc/development/README.md | 1 + doc/development/limit_ee_conflicts.md | 247 ++++++++++++++++++++++++++++++++++ 2 files changed, 248 insertions(+) create mode 100644 doc/development/limit_ee_conflicts.md (limited to 'doc/development') diff --git a/doc/development/README.md b/doc/development/README.md index f88456a7a7a..371bb55c127 100644 --- a/doc/development/README.md +++ b/doc/development/README.md @@ -22,6 +22,7 @@ ## Process - [Generate a changelog entry with `bin/changelog`](changelog.md) +- [Limit conflicts with EE when developing on CE](limit_ee_conflicts.md) - [Code review guidelines](code_review.md) for reviewing code and having code reviewed. - [Merge request performance guidelines](merge_request_performance_guidelines.md) for ensuring merge requests do not negatively impact GitLab performance diff --git a/doc/development/limit_ee_conflicts.md b/doc/development/limit_ee_conflicts.md new file mode 100644 index 00000000000..e8af1c6af7b --- /dev/null +++ b/doc/development/limit_ee_conflicts.md @@ -0,0 +1,247 @@ +# Limit conflicts with EE when developing on CE + +This guide contains best-practices for avoiding conflicts between CE and EE. + +## Context + +Usually, GitLab Community Edition is merged into the Enterprise Edition once a +week. During these merges, it's very common to get conflicts when some changes +in CE do not apply cleanly to EE. + +In this document, we will list the best practices to avoid such conflicts or to +make them easily solvable by the person who does the CE->EE merge. + +## Different type of conflicts + +### Models + +#### Common issues + +TODO + +#### Mitigations + +TODO + +### Services + +#### Common issues + +TODO + +#### Mitigations + +TODO + +### Controllers + +#### Common issues + +In controllers, the most common type of conflicts is either in a `before_action` +that has a list of actions in CE but EE adds some actions to that list. + +Same problems often occurs for `params.require` / `params.permit` calls. + +Other conflicts usually involve specific code for EE-specific features such as: + +- LDAP: + ```diff + def destroy + @key = current_user.keys.find(params[:id]) + - @key.destroy + + @key.destroy unless @key.is_a? LDAPKey + + respond_to do |format| + ``` +- Geo: + ```diff + def after_sign_out_path_for(resource) + - current_application_settings.after_sign_out_path.presence || new_user_session_path + + if Gitlab::Geo.secondary? + + Gitlab::Geo.primary_node.oauth_logout_url(@geo_logout_state) + + else + + current_application_settings.after_sign_out_path.presence || new_user_session_path + + end + end + ``` +- Audit log: + ```diff + def approve_access_request + - Members::ApproveAccessRequestService.new(membershipable, current_user, params).execute + + member = Members::ApproveAccessRequestService.new(membershipable, current_user, params).execute + + + + log_audit_event(member, action: :create) + + redirect_to polymorphic_url([membershipable, :members]) + end + ``` + +#### Mitigations + +Separate CE and EE actions/keywords. For instance for `params.require` in +`ProjectsController`: + +```ruby +def project_params + params.require(:project).permit(project_params_ce) + # On EE, this is always: + # params.require(:project).permit(project_params_ce + project_params_ee) +end + +# Always returns an array of symbols, created however best fits the use case. +# It _should_ be sorted alphabetically. +def project_params_ce + %i[ + description + name + path + ] +end + +# (On EE) +def project_params_ee + %i[ + approvals_before_merge + approver_group_ids + approver_ids + ... + ] +end +``` + +### Views + +#### Common issues + +A few issues often happen here: + +1. Indentation issue +1. A block of code added in CE conflicts because there is already another block + at the same place in EE + +#### Mitigations + +Blocks of code that are EE-specific should be moved to partials as much as +possible to avoid conflicts with big chunks of HAML code that that are not funny +to resolve when you add the indentation in the equation. + +For instance this kind of things: + +```haml +- if can?(current_user, :"admin_#{issuable.to_ability_name}", issuable.project) + - has_due_date = issuable.has_attribute?(:due_date) + %hr + .row + %div{ class: (has_due_date ? "col-lg-6" : "col-sm-12") } + .form-group.issue-assignee + = f.label :assignee_id, "Assignee", class: "control-label #{"col-lg-4" if has_due_date}" + .col-sm-10{ class: ("col-lg-8" if has_due_date) } + .issuable-form-select-holder + - if issuable.assignee_id + = f.hidden_field :assignee_id + = dropdown_tag(user_dropdown_label(issuable.assignee_id, "Assignee"), options: { toggle_class: "js-dropdown-keep-input js-user-search js-issuable-form-dropdown js-assignee-search", title: "Select assignee", filter: true, dropdown_class: "dropdown-menu-user dropdown-menu-selectable dropdown-menu-assignee js-filter-submit", + placeholder: "Search assignee", data: { first_user: current_user.try(:username), null_user: true, current_user: true, project_id: project.try(:id), selected: issuable.assignee_id, field_name: "#{issuable.class.model_name.param_key}[assignee_id]", default_label: "Assignee"} }) + .form-group.issue-milestone + = f.label :milestone_id, "Milestone", class: "control-label #{"col-lg-4" if has_due_date}" + .col-sm-10{ class: ("col-lg-8" if has_due_date) } + .issuable-form-select-holder + = render "shared/issuable/milestone_dropdown", selected: issuable.milestone, name: "#{issuable.class.model_name.param_key}[milestone_id]", show_any: false, show_upcoming: false, extra_class: "js-issuable-form-dropdown js-dropdown-keep-input", dropdown_title: "Select milestone" + .form-group + - has_labels = @labels && @labels.any? + = f.label :label_ids, "Labels", class: "control-label #{"col-lg-4" if has_due_date}" + = f.hidden_field :label_ids, multiple: true, value: '' + .col-sm-10{ class: "#{"col-lg-8" if has_due_date} #{'issuable-form-padding-top' if !has_labels}" } + .issuable-form-select-holder + = render "shared/issuable/label_dropdown", classes: ["js-issuable-form-dropdown"], selected: issuable.labels, data_options: { field_name: "#{issuable.class.model_name.param_key}[label_ids][]", show_any: false, show_menu_above: 'true' }, dropdown_title: "Select label" + + - if issuable.respond_to?(:weight) + .form-group + = f.label :label_ids, class: "control-label #{"col-lg-4" if has_due_date}" do + Weight + .col-sm-10{ class: ("col-lg-8" if has_due_date) } + = f.select :weight, issues_weight_options(issuable.weight, edit: true), { include_blank: true }, + { class: 'select2 js-select2', data: { placeholder: "Select weight" }} + + - if has_due_date + .col-lg-6 + .form-group + = f.label :due_date, "Due date", class: "control-label" + .col-sm-10 + .issuable-form-select-holder + = f.text_field :due_date, id: "issuable-due-date", class: "datepicker form-control", placeholder: "Select due date" +``` + +could be simplified by using partials: + +```haml += render 'metadata_form', issuable: issuable +``` + +and then the `_metadata_form.html.haml` could be as follows: + +```haml +- return unless can?(current_user, :"admin_#{issuable.to_ability_name}", issuable.project) + +- has_due_date = issuable.has_attribute?(:due_date) +%hr +.row + %div{ class: (has_due_date ? "col-lg-6" : "col-sm-12") } + .form-group.issue-assignee + = f.label :assignee_id, "Assignee", class: "control-label #{"col-lg-4" if has_due_date}" + .col-sm-10{ class: ("col-lg-8" if has_due_date) } + .issuable-form-select-holder + - if issuable.assignee_id + = f.hidden_field :assignee_id + = dropdown_tag(user_dropdown_label(issuable.assignee_id, "Assignee"), options: { toggle_class: "js-dropdown-keep-input js-user-search js-issuable-form-dropdown js-assignee-search", title: "Select assignee", filter: true, dropdown_class: "dropdown-menu-user dropdown-menu-selectable dropdown-menu-assignee js-filter-submit", + placeholder: "Search assignee", data: { first_user: current_user.try(:username), null_user: true, current_user: true, project_id: project.try(:id), selected: issuable.assignee_id, field_name: "#{issuable.class.model_name.param_key}[assignee_id]", default_label: "Assignee"} }) + .form-group.issue-milestone + = f.label :milestone_id, "Milestone", class: "control-label #{"col-lg-4" if has_due_date}" + .col-sm-10{ class: ("col-lg-8" if has_due_date) } + .issuable-form-select-holder + = render "shared/issuable/milestone_dropdown", selected: issuable.milestone, name: "#{issuable.class.model_name.param_key}[milestone_id]", show_any: false, show_upcoming: false, extra_class: "js-issuable-form-dropdown js-dropdown-keep-input", dropdown_title: "Select milestone" + .form-group + - has_labels = @labels && @labels.any? + = f.label :label_ids, "Labels", class: "control-label #{"col-lg-4" if has_due_date}" + = f.hidden_field :label_ids, multiple: true, value: '' + .col-sm-10{ class: "#{"col-lg-8" if has_due_date} #{'issuable-form-padding-top' if !has_labels}" } + .issuable-form-select-holder + = render "shared/issuable/label_dropdown", classes: ["js-issuable-form-dropdown"], selected: issuable.labels, data_options: { field_name: "#{issuable.class.model_name.param_key}[label_ids][]", show_any: false, show_menu_above: 'true' }, dropdown_title: "Select label" + + = render 'weight_form', issuable: issuable, has_due_date: has_due_date + + - if has_due_date + .col-lg-6 + .form-group + = f.label :due_date, "Due date", class: "control-label" + .col-sm-10 + .issuable-form-select-holder + = f.text_field :due_date, id: "issuable-due-date", class: "datepicker form-control", placeholder: "Select due date" +``` + +and then the `_weight_form.html.haml` could be as follows: + +```haml +- return unless issuable.respond_to?(:weight) + +- has_due_date = issuable.has_attribute?(:due_date) + +.form-group + = f.label :label_ids, class: "control-label #{"col-lg-4" if has_due_date}" do + Weight + .col-sm-10{ class: ("col-lg-8" if has_due_date) } + = f.select :weight, issues_weight_options(issuable.weight, edit: true), { include_blank: true }, + { class: 'select2 js-select2', data: { placeholder: "Select weight" }} +``` + +Note: + +- The safeguards at the top allows to get rid of an unneccessary indentation +level +- Here we only moved the 'Weight' code to a partial since this is the only + EE-specific code in that view, so it's the most likely to conflict, but you + are encouraged to use partials even for code that's in CE to logically split + big views into several smaller files. + +--- + +[Return to Development documentation](README.md) -- cgit v1.2.1 From 25c9c8ce732a59eb05f93b9004e12917b8a00407 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=C3=A9my=20Coutable?= Date: Wed, 16 Nov 2016 18:39:36 +0100 Subject: Document the `rake ee_compat_check` task MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Rémy Coutable --- doc/development/limit_ee_conflicts.md | 144 ++++++++++++++++++++-------------- 1 file changed, 85 insertions(+), 59 deletions(-) (limited to 'doc/development') diff --git a/doc/development/limit_ee_conflicts.md b/doc/development/limit_ee_conflicts.md index e8af1c6af7b..29299b0690b 100644 --- a/doc/development/limit_ee_conflicts.md +++ b/doc/development/limit_ee_conflicts.md @@ -8,75 +8,54 @@ Usually, GitLab Community Edition is merged into the Enterprise Edition once a week. During these merges, it's very common to get conflicts when some changes in CE do not apply cleanly to EE. -In this document, we will list the best practices to avoid such conflicts or to -make them easily solvable by the person who does the CE->EE merge. +There are a few things that can help you as a developer to: -## Different type of conflicts +- know when your merge request to CE will conflict when merged to EE +- avoid such conflicts in the first place +- ease future conflict resolutions if conflict is inevitable -### Models +## Check the `rake ee_compat_check` in your merge requests -#### Common issues +For each commit (except on `master`), the `rake ee_compat_check` CI job tries to +detect if the current branch's changes will conflict during the CE->EE merge. -TODO +The job reports what files are conflicting and how to setup a merge request +against EE. Here is roughly how it works: -#### Mitigations +1. Generates the diff between your branch and current CE `master` +1. Tries to apply it to current EE `master` +1. If it applies cleanly, the job succeeds, otherwise... +1. Detects a branch with the `-ee` suffix in EE +1. If it exists, generate the diff between this branch and current EE `master` +1. Tries to apply it to current EE `master` +1. If it applies cleanly, the job succeeds -TODO +In the case where the job fails, it means you should create a `-ee` +branch, push it to EE and open a merge request against EE `master`. At this +point if you retry the failing job in your CE merge request, it should now pass. -### Services +Notes: -#### Common issues +- This task is not a silver-bullet, its current goal is to bring awareness to + developers that their work needs to be ported to EE. +- Community contributors shouldn't submit merge requests against EE, but + reviewers should take actions by either creating such EE merge request or + asking a GitLab developer to do it once the merge request is merged. +- If you branch is more than 500 commits behind `master`, the job will fail and + you should rebase your branch upon latest `master`. -TODO - -#### Mitigations - -TODO +## Possible type of conflicts ### Controllers -#### Common issues +#### List or arrays are augmented in EE In controllers, the most common type of conflicts is either in a `before_action` that has a list of actions in CE but EE adds some actions to that list. Same problems often occurs for `params.require` / `params.permit` calls. -Other conflicts usually involve specific code for EE-specific features such as: - -- LDAP: - ```diff - def destroy - @key = current_user.keys.find(params[:id]) - - @key.destroy - + @key.destroy unless @key.is_a? LDAPKey - - respond_to do |format| - ``` -- Geo: - ```diff - def after_sign_out_path_for(resource) - - current_application_settings.after_sign_out_path.presence || new_user_session_path - + if Gitlab::Geo.secondary? - + Gitlab::Geo.primary_node.oauth_logout_url(@geo_logout_state) - + else - + current_application_settings.after_sign_out_path.presence || new_user_session_path - + end - end - ``` -- Audit log: - ```diff - def approve_access_request - - Members::ApproveAccessRequestService.new(membershipable, current_user, params).execute - + member = Members::ApproveAccessRequestService.new(membershipable, current_user, params).execute - + - + log_audit_event(member, action: :create) - - redirect_to polymorphic_url([membershipable, :members]) - end - ``` - -#### Mitigations +##### Mitigations Separate CE and EE actions/keywords. For instance for `params.require` in `ProjectsController`: @@ -109,20 +88,56 @@ def project_params_ee end ``` -### Views +#### Additional condition(s) in EE + +For instance for LDAP: + +```diff + def destroy + @key = current_user.keys.find(params[:id]) + - @key.destroy + + @key.destroy unless @key.is_a? LDAPKey + + respond_to do |format| +``` + +Or for Geo: -#### Common issues +```diff +def after_sign_out_path_for(resource) +- current_application_settings.after_sign_out_path.presence || new_user_session_path ++ if Gitlab::Geo.secondary? ++ Gitlab::Geo.primary_node.oauth_logout_url(@geo_logout_state) ++ else ++ current_application_settings.after_sign_out_path.presence || new_user_session_path ++ end +end +``` -A few issues often happen here: +Or even for audit log: -1. Indentation issue -1. A block of code added in CE conflicts because there is already another block - at the same place in EE +```diff +def approve_access_request +- Members::ApproveAccessRequestService.new(membershipable, current_user, params).execute ++ member = Members::ApproveAccessRequestService.new(membershipable, current_user, params).execute ++ ++ log_audit_event(member, action: :create) -#### Mitigations + redirect_to polymorphic_url([membershipable, :members]) +end +``` + +### Views + +#### Additional view code in EE + +A block of code added in CE conflicts because there is already another block +at the same place in EE + +##### Mitigations Blocks of code that are EE-specific should be moved to partials as much as -possible to avoid conflicts with big chunks of HAML code that that are not funny +possible to avoid conflicts with big chunks of HAML code that that are not fun to resolve when you add the indentation in the equation. For instance this kind of things: @@ -242,6 +257,17 @@ level are encouraged to use partials even for code that's in CE to logically split big views into several smaller files. +#### Indentation issue + +Sometimes a code block is indented more or less in EE because there's an +additional condition. + +##### Mitigations + +Blocks of code that are EE-specific should be moved to partials as much as +possible to avoid conflicts with big chunks of HAML code that that are not fun +to resolve when you add the indentation in the equation. + --- [Return to Development documentation](README.md) -- cgit v1.2.1 From 3fa5e73400548f38cbfec1d9e1f6bf22e38214cd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=C3=A9my=20Coutable?= Date: Thu, 17 Nov 2016 18:34:45 +0100 Subject: Fix typos MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Rémy Coutable --- doc/development/limit_ee_conflicts.md | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) (limited to 'doc/development') diff --git a/doc/development/limit_ee_conflicts.md b/doc/development/limit_ee_conflicts.md index 29299b0690b..b7e6387838e 100644 --- a/doc/development/limit_ee_conflicts.md +++ b/doc/development/limit_ee_conflicts.md @@ -50,10 +50,10 @@ Notes: #### List or arrays are augmented in EE -In controllers, the most common type of conflicts is either in a `before_action` -that has a list of actions in CE but EE adds some actions to that list. +In controllers, the most common type of conflict is with `before_action` that +has a list of actions in CE but EE adds some actions to that list. -Same problems often occurs for `params.require` / `params.permit` calls. +The same problem often occurs for `params.require` / `params.permit` calls. ##### Mitigations @@ -64,7 +64,7 @@ Separate CE and EE actions/keywords. For instance for `params.require` in def project_params params.require(:project).permit(project_params_ce) # On EE, this is always: - # params.require(:project).permit(project_params_ce + project_params_ee) + # params.require(:project).permit(project_params_ce << project_params_ee) end # Always returns an array of symbols, created however best fits the use case. @@ -138,9 +138,9 @@ at the same place in EE Blocks of code that are EE-specific should be moved to partials as much as possible to avoid conflicts with big chunks of HAML code that that are not fun -to resolve when you add the indentation in the equation. +to resolve when you add the indentation to the equation. -For instance this kind of things: +For instance this kind of thing: ```haml - if can?(current_user, :"admin_#{issuable.to_ability_name}", issuable.project) @@ -250,8 +250,7 @@ and then the `_weight_form.html.haml` could be as follows: Note: -- The safeguards at the top allows to get rid of an unneccessary indentation -level +- The safeguards at the top allow to get rid of an unneccessary indentation level - Here we only moved the 'Weight' code to a partial since this is the only EE-specific code in that view, so it's the most likely to conflict, but you are encouraged to use partials even for code that's in CE to logically split -- cgit v1.2.1 From cfabd5b5a9fb47b68210683c813efc36e9e1d921 Mon Sep 17 00:00:00 2001 From: Victor Wu Date: Wed, 16 Nov 2016 21:29:28 +0000 Subject: Update copy.md with issue guideline updates and merge request guidelines Update examples and labels to use sentence case. Update copy.md [ci skip] Update copy.md [ci skip] Update copy.md --- doc/development/ux_guide/copy.md | 73 ++++++++++++++++++++++++++-------------- 1 file changed, 47 insertions(+), 26 deletions(-) (limited to 'doc/development') diff --git a/doc/development/ux_guide/copy.md b/doc/development/ux_guide/copy.md index 03392a003ee..227b4fd3451 100644 --- a/doc/development/ux_guide/copy.md +++ b/doc/development/ux_guide/copy.md @@ -7,7 +7,7 @@ We are currently inconsistent with this guidance. Images below are created to il ## Contents * [Brevity](#brevity) -* [Forms](#forms) +* [Sentence case](#sentence-case) * [Terminology](#terminology) --- @@ -27,52 +27,73 @@ Preferrably use context and placement of controls to make it obvious what clicki --- -## Forms +## Sentence case +Use sentence case for all titles, headings, labels, menu items, and buttons. -### Adding items +--- + +## Terminology +Only use the terms in the tables below. + +### Issues + +#### Adjectives (states) + +| Term | +| ---- | +| Open | +| Closed | +| Deleted | + +>**Example:** +Use `5 open issues` and don't use `5 pending issues`. + +#### Verbs (actions) + +| Term | Use | Don't | +| ---- | --- | --- | +| Add | Add an issue | Don't use `create` or `new` | +| View | View an open or closed issue || +| Edit | Edit an open or closed issue | Don't use `update` | +| Close | Close an open issue || +| Re-open | Re-open a closed issue | There should never be a need to use `open` as a verb | +| Delete | Delete an open or closed issue || + +#### Add issue When viewing a list of issues, there is a button that is labeled `Add`. Given the context in the example, it is clearly referring to issues. If the context were not clear enough, the label could be `Add issue`. Clicking the button will bring you to the `Add issue` form. Other add flows should be similar. ![Add issue button](img/copy-form-addissuebutton.png) -The form should be titled `Add issue`. The submit button should be labeled `Save` or `Submit`. Do not use `Add`, `Create`, `New`, or `Save Changes`. The cancel button should be labeled `Cancel`. Do not use `Back`. +The form should be titled `Add issue`. The submit button should be labeled `Submit`. Don't use `Add`, `Create`, `New`, or `Save changes`. The cancel button should be labeled `Cancel`. Don't use `Back`. ![Add issue form](img/copy-form-addissueform.png) -### Editing items +#### Edit issue When in context of an issue, the affordance to edit it is labeled `Edit`. If the context is not clear enough, `Edit issue` could be considered. Other edit flows should be similar. ![Edit issue button](img/copy-form-editissuebutton.png) -The form should be titled `Edit Issue`. The submit button should be labeled `Save`. Do not use `Edit`, `Update`, `New`, or `Save Changes`. The cancel button should be labeled `Cancel`. Do not use `Back`. +The form should be titled `Edit issue`. The submit button should be labeled `Save`. Don't use `Edit`, `Update`, `Submit`, or `Save changes`. The cancel button should be labeled `Cancel`. Don't use `Back`. ![Edit issue form](img/copy-form-editissueform.png) ---- - -## Terminology -### Issues +### Merge requests #### Adjectives (states) -| Term | Use | -| ---- | --- | -| Open | Issue is active | -| Closed | Issue is no longer active | - ->**Example:** -Use `5 open issues` and do not use `5 pending issues`. -Only use the adjectives in the table above. +| Term | +| ---- | +| Open | +| Merged | #### Verbs (actions) -| Term | Use | -| ---- | --- | -| Add | For adding an issue. Do not use `create` or `new` | -| View | View an issue | -| Edit | Edit an issue. Do not use `update` | -| Close | Closing an issue | -| Re-open | Re-open an issue. There should never be a need to use `open` as a verb | -| Delete | Deleting an issue. Do not use `remove` | \ No newline at end of file +| Term | Use | Don't | +| ---- | --- | --- | +| Add | Add a merge request | Do not use `create` or `new` | +| View | View an open or merged merge request || +| Edit | Edit an open or merged merge request| Do not use `update` | +| Merge | Merge an open merge request || \ No newline at end of file -- cgit v1.2.1 From a2c397a7a12f207a9221b85003037f56b2d39d86 Mon Sep 17 00:00:00 2001 From: Victor Wu Date: Thu, 17 Nov 2016 22:28:44 +0000 Subject: Link to object state models [ci skip] --- doc/development/README.md | 1 + 1 file changed, 1 insertion(+) (limited to 'doc/development') diff --git a/doc/development/README.md b/doc/development/README.md index 371bb55c127..6f2ca7b8590 100644 --- a/doc/development/README.md +++ b/doc/development/README.md @@ -38,6 +38,7 @@ - [Rake tasks](rake_tasks.md) for development - [Shell commands](shell_commands.md) in the GitLab codebase - [Sidekiq debugging](sidekiq_debugging.md) +- [Object state models](object_state_models.md) ## Databases -- cgit v1.2.1 From 4c519730a24e68823ec08e1526bc80aed7fac352 Mon Sep 17 00:00:00 2001 From: Victor Wu Date: Thu, 17 Nov 2016 22:30:42 +0000 Subject: Add file [ci skip] --- doc/development/object_state_models.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) create mode 100644 doc/development/object_state_models.md (limited to 'doc/development') diff --git a/doc/development/object_state_models.md b/doc/development/object_state_models.md new file mode 100644 index 00000000000..e69de29bb2d -- cgit v1.2.1 From 1fb1d5dfa6562557d7ac920070f199934790594f Mon Sep 17 00:00:00 2001 From: Victor Wu Date: Thu, 17 Nov 2016 22:32:29 +0000 Subject: Add new directory [ci skip] --- doc/development/img/.gitkeep | 0 1 file changed, 0 insertions(+), 0 deletions(-) create mode 100644 doc/development/img/.gitkeep (limited to 'doc/development') diff --git a/doc/development/img/.gitkeep b/doc/development/img/.gitkeep new file mode 100644 index 00000000000..e69de29bb2d -- cgit v1.2.1 From 2eb42d7acbdb7ba178440f3d3618048d3ee01a5c Mon Sep 17 00:00:00 2001 From: Victor Wu Date: Thu, 17 Nov 2016 22:35:18 +0000 Subject: Upload new file [ci skip] --- doc/development/img/state-model-legend.png | Bin 0 -> 12412 bytes 1 file changed, 0 insertions(+), 0 deletions(-) create mode 100644 doc/development/img/state-model-legend.png (limited to 'doc/development') diff --git a/doc/development/img/state-model-legend.png b/doc/development/img/state-model-legend.png new file mode 100644 index 00000000000..088230bfc39 Binary files /dev/null and b/doc/development/img/state-model-legend.png differ -- cgit v1.2.1 From b14d840b9282879e2219666efe892d3ce2e8aafd Mon Sep 17 00:00:00 2001 From: Victor Wu Date: Thu, 17 Nov 2016 22:35:50 +0000 Subject: Upload new file [ci skip] --- doc/development/img/state-model-issue.png | Bin 0 -> 13334 bytes 1 file changed, 0 insertions(+), 0 deletions(-) create mode 100644 doc/development/img/state-model-issue.png (limited to 'doc/development') diff --git a/doc/development/img/state-model-issue.png b/doc/development/img/state-model-issue.png new file mode 100644 index 00000000000..9cb80507c40 Binary files /dev/null and b/doc/development/img/state-model-issue.png differ -- cgit v1.2.1 From d5d80cae2c04326c262fb499515b28ef14002b9c Mon Sep 17 00:00:00 2001 From: Victor Wu Date: Thu, 17 Nov 2016 22:36:20 +0000 Subject: Upload new file [ci skip] --- doc/development/img/state-model-merge-request.png | Bin 0 -> 22522 bytes 1 file changed, 0 insertions(+), 0 deletions(-) create mode 100644 doc/development/img/state-model-merge-request.png (limited to 'doc/development') diff --git a/doc/development/img/state-model-merge-request.png b/doc/development/img/state-model-merge-request.png new file mode 100644 index 00000000000..94e13edb4ce Binary files /dev/null and b/doc/development/img/state-model-merge-request.png differ -- cgit v1.2.1 From 32fc9d39db511d67ee077fe821294e8b9e3b6397 Mon Sep 17 00:00:00 2001 From: Victor Wu Date: Thu, 17 Nov 2016 22:36:42 +0000 Subject: Delete .gitkeep [ci skip] --- doc/development/img/.gitkeep | 0 1 file changed, 0 insertions(+), 0 deletions(-) delete mode 100644 doc/development/img/.gitkeep (limited to 'doc/development') diff --git a/doc/development/img/.gitkeep b/doc/development/img/.gitkeep deleted file mode 100644 index e69de29bb2d..00000000000 -- cgit v1.2.1 From 6314a51dcef7db646ae4cd86dd6fe96fde151a6a Mon Sep 17 00:00:00 2001 From: Victor Wu Date: Thu, 17 Nov 2016 22:54:29 +0000 Subject: Update object_state_models.md [ci skip] --- doc/development/object_state_models.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) (limited to 'doc/development') diff --git a/doc/development/object_state_models.md b/doc/development/object_state_models.md index e69de29bb2d..bb97b17e83f 100644 --- a/doc/development/object_state_models.md +++ b/doc/development/object_state_models.md @@ -0,0 +1,27 @@ +# Object state models + +## Contents +* [Diagrams](#diagrams) +* [Legend](#legend) +* [Issue](#issue) +* [Merge request](#merge-request) + +## Diagrams +[GitLab object state models](https://drive.google.com/drive/u/3/folders/0B5tDlHAM4iZINmpvYlJXcDVqMGc) + +--- + +## Legend +![legend](img/state-model-legend.png) + +--- + +## Issue +[`app/models/issue.rb`](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/app/models/issue.rb) +![issue](img/state-model-issue.png) + +--- + +## Merge request +[`app/models/merge_request.rb`](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/app/models/merge_request.rb) +![merge request](img/state-model-merge-request.png) \ No newline at end of file -- cgit v1.2.1 From 9c4e0d64451bd76b829e1bb66afab892e19926da Mon Sep 17 00:00:00 2001 From: Lin Jen-Shin Date: Fri, 18 Nov 2016 20:17:10 +0800 Subject: Use `Gitlab.config.gitlab.host` over `'localhost'` This would fix long standing failures running tests on my development machine, which set `Gitlab.config.gitlab.host` to another host because it's not my local computer. Now I finally cannot withstand it and decided to fix them once and for all. --- doc/development/testing.md | 1 + 1 file changed, 1 insertion(+) (limited to 'doc/development') diff --git a/doc/development/testing.md b/doc/development/testing.md index 4dc535fb359..6106e47daa0 100644 --- a/doc/development/testing.md +++ b/doc/development/testing.md @@ -70,6 +70,7 @@ the command line via `bundle exec teaspoon`, or via a web browser at - Try to match the ordering of tests to the ordering within the class. - Try to follow the [Four-Phase Test][four-phase-test] pattern, using newlines to separate phases. +- Try to use `Gitlab.config.gitlab.host` rather than hard coding `'localhost'` [four-phase-test]: https://robots.thoughtbot.com/four-phase-test -- cgit v1.2.1 From 709e590d3bcf62cdcd0081629d65098dbe7ac71d Mon Sep 17 00:00:00 2001 From: Victor Wu Date: Fri, 18 Nov 2016 17:59:43 +0000 Subject: Add spaces to conform to style guide [ci skip] --- doc/development/object_state_models.md | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'doc/development') diff --git a/doc/development/object_state_models.md b/doc/development/object_state_models.md index bb97b17e83f..ac215bdca38 100644 --- a/doc/development/object_state_models.md +++ b/doc/development/object_state_models.md @@ -1,27 +1,32 @@ # Object state models ## Contents + * [Diagrams](#diagrams) * [Legend](#legend) * [Issue](#issue) * [Merge request](#merge-request) ## Diagrams + [GitLab object state models](https://drive.google.com/drive/u/3/folders/0B5tDlHAM4iZINmpvYlJXcDVqMGc) --- ## Legend + ![legend](img/state-model-legend.png) --- ## Issue + [`app/models/issue.rb`](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/app/models/issue.rb) ![issue](img/state-model-issue.png) --- ## Merge request + [`app/models/merge_request.rb`](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/app/models/merge_request.rb) ![merge request](img/state-model-merge-request.png) \ No newline at end of file -- cgit v1.2.1 From bef75852a06c7a4174f92ced8ad8d244f5125f4c Mon Sep 17 00:00:00 2001 From: Victor Wu Date: Fri, 18 Nov 2016 21:03:49 +0000 Subject: Remove hyphen [ci skip] --- doc/development/img/state-model-issue.png | Bin 13334 -> 13256 bytes 1 file changed, 0 insertions(+), 0 deletions(-) (limited to 'doc/development') diff --git a/doc/development/img/state-model-issue.png b/doc/development/img/state-model-issue.png index 9cb80507c40..c85fffc2a3a 100644 Binary files a/doc/development/img/state-model-issue.png and b/doc/development/img/state-model-issue.png differ -- cgit v1.2.1 From 88cc283fd7b692f3dfb7cb1bb6df1f919256bab8 Mon Sep 17 00:00:00 2001 From: Victor Wu Date: Fri, 18 Nov 2016 21:04:21 +0000 Subject: Remove hyphen [ci skip] --- doc/development/img/state-model-merge-request.png | Bin 22522 -> 22484 bytes 1 file changed, 0 insertions(+), 0 deletions(-) (limited to 'doc/development') diff --git a/doc/development/img/state-model-merge-request.png b/doc/development/img/state-model-merge-request.png index 94e13edb4ce..0e7556784f4 100644 Binary files a/doc/development/img/state-model-merge-request.png and b/doc/development/img/state-model-merge-request.png differ -- cgit v1.2.1 From e887e96893f43a3a00429a1688c321ed131e5076 Mon Sep 17 00:00:00 2001 From: Victor Wu Date: Sun, 20 Nov 2016 15:44:21 +0000 Subject: Remove contents section since it's not necessary [ci skip] --- doc/development/object_state_models.md | 7 ------- 1 file changed, 7 deletions(-) (limited to 'doc/development') diff --git a/doc/development/object_state_models.md b/doc/development/object_state_models.md index ac215bdca38..623bbf143ef 100644 --- a/doc/development/object_state_models.md +++ b/doc/development/object_state_models.md @@ -1,12 +1,5 @@ # Object state models -## Contents - -* [Diagrams](#diagrams) -* [Legend](#legend) -* [Issue](#issue) -* [Merge request](#merge-request) - ## Diagrams [GitLab object state models](https://drive.google.com/drive/u/3/folders/0B5tDlHAM4iZINmpvYlJXcDVqMGc) -- cgit v1.2.1 From 4a411f2711be742b41dc347a0fa876bd9576a0ab Mon Sep 17 00:00:00 2001 From: awhildy Date: Mon, 21 Nov 2016 11:44:21 -0800 Subject: [ci skip] Add Approve and Remove Approval to UX Guide terminology table --- doc/development/ux_guide/copy.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'doc/development') diff --git a/doc/development/ux_guide/copy.md b/doc/development/ux_guide/copy.md index 227b4fd3451..b557fb47120 100644 --- a/doc/development/ux_guide/copy.md +++ b/doc/development/ux_guide/copy.md @@ -96,4 +96,6 @@ The form should be titled `Edit issue`. The submit button should be labeled `Sav | Add | Add a merge request | Do not use `create` or `new` | | View | View an open or merged merge request || | Edit | Edit an open or merged merge request| Do not use `update` | -| Merge | Merge an open merge request || \ No newline at end of file +| Approve | Approve an open merge request || +| Remove approval, unapproved | Remove approval of an open merge request | Do not use `unapprove` as that is not an English word| +| Merge | Merge an open merge request || -- cgit v1.2.1 From af1dabe805fa7ad6fcdccfdb792b07e00c3c42d2 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Tue, 22 Nov 2016 19:53:43 +0100 Subject: Reduce size of images from 25MB to 13MB using pngquant Took it from https://gitlab.com/gitlab-com/www-gitlab-com/merge_requests/3232 [ci skip] --- doc/development/gitlab_architecture_diagram.png | Bin 23831 -> 20339 bytes doc/development/img/state-model-issue.png | Bin 13256 -> 7713 bytes doc/development/img/state-model-legend.png | Bin 12412 -> 8496 bytes doc/development/img/state-model-merge-request.png | Bin 22484 -> 12459 bytes doc/development/ux_guide/img/button-primary.png | Bin 8410 -> 1550 bytes doc/development/ux_guide/img/button-secondary.png | Bin 11160 -> 2683 bytes doc/development/ux_guide/img/color-blue.png | Bin 3865 -> 2725 bytes doc/development/ux_guide/img/color-green.png | Bin 4127 -> 3008 bytes doc/development/ux_guide/img/color-orange.png | Bin 4698 -> 3470 bytes doc/development/ux_guide/img/color-red.png | Bin 3669 -> 2628 bytes doc/development/ux_guide/img/components-alerts.png | Bin 46785 -> 27342 bytes .../ux_guide/img/components-anchorlinks.png | Bin 36456 -> 19948 bytes .../ux_guide/img/components-contentblock.png | Bin 19841 -> 14190 bytes .../ux_guide/img/components-coverblock.png | Bin 15757 -> 10141 bytes .../ux_guide/img/components-dateexact.png | Bin 5609 -> 4161 bytes .../ux_guide/img/components-daterelative.png | Bin 5843 -> 4189 bytes .../ux_guide/img/components-dropdown.png | Bin 60448 -> 31760 bytes .../ux_guide/img/components-fileholder.png | Bin 4953 -> 3938 bytes .../ux_guide/img/components-horizontalform.png | Bin 5708 -> 4327 bytes .../ux_guide/img/components-listinsidepanel.png | Bin 3962 -> 3449 bytes .../ux_guide/img/components-listwithavatar.png | Bin 7952 -> 5749 bytes .../ux_guide/img/components-listwithhover.png | Bin 3313 -> 2860 bytes doc/development/ux_guide/img/components-panels.png | Bin 32886 -> 21822 bytes .../ux_guide/img/components-referencehover.png | Bin 11519 -> 6948 bytes .../ux_guide/img/components-referenceissues.png | Bin 14587 -> 10009 bytes .../ux_guide/img/components-referencelabels.png | Bin 4643 -> 4108 bytes .../ux_guide/img/components-referencemilestone.png | Bin 2468 -> 2417 bytes .../ux_guide/img/components-referencemrs.png | Bin 12646 -> 8859 bytes .../ux_guide/img/components-referencepeople.png | Bin 7214 -> 5607 bytes .../ux_guide/img/components-rowcontentblock.png | Bin 19730 -> 14315 bytes .../ux_guide/img/components-simplelist.png | Bin 3078 -> 2781 bytes doc/development/ux_guide/img/components-table.png | Bin 7668 -> 6081 bytes .../ux_guide/img/components-verticalform.png | Bin 6541 -> 4964 bytes .../ux_guide/img/copy-form-addissuebutton.png | Bin 26541 -> 16085 bytes .../ux_guide/img/copy-form-addissueform.png | Bin 38242 -> 25978 bytes .../ux_guide/img/copy-form-editissuebutton.png | Bin 16466 -> 11801 bytes .../ux_guide/img/copy-form-editissueform.png | Bin 40660 -> 25621 bytes .../ux_guide/img/features-contextualnav.png | Bin 8051 -> 5912 bytes .../ux_guide/img/features-emptystates.png | Bin 114540 -> 61664 bytes doc/development/ux_guide/img/features-filters.png | Bin 4529 -> 3924 bytes .../ux_guide/img/features-globalnav.png | Bin 8953 -> 5780 bytes .../ux_guide/img/surfaces-contentitemtitle.png | Bin 7463 -> 5142 bytes doc/development/ux_guide/img/surfaces-header.png | Bin 6103 -> 4095 bytes .../img/surfaces-systeminformationblock.png | Bin 15412 -> 10423 bytes doc/development/ux_guide/img/surfaces-ux.png | Bin 7673 -> 4029 bytes doc/development/ux_guide/img/tooltip-placement.png | Bin 2645 -> 2071 bytes doc/development/ux_guide/img/tooltip-usage.png | Bin 9160 -> 5994 bytes 47 files changed, 0 insertions(+), 0 deletions(-) (limited to 'doc/development') diff --git a/doc/development/gitlab_architecture_diagram.png b/doc/development/gitlab_architecture_diagram.png index 80e975718e0..cda5ce254ce 100644 Binary files a/doc/development/gitlab_architecture_diagram.png and b/doc/development/gitlab_architecture_diagram.png differ diff --git a/doc/development/img/state-model-issue.png b/doc/development/img/state-model-issue.png index c85fffc2a3a..ee33b6886c6 100644 Binary files a/doc/development/img/state-model-issue.png and b/doc/development/img/state-model-issue.png differ diff --git a/doc/development/img/state-model-legend.png b/doc/development/img/state-model-legend.png index 088230bfc39..1c121f2588c 100644 Binary files a/doc/development/img/state-model-legend.png and b/doc/development/img/state-model-legend.png differ diff --git a/doc/development/img/state-model-merge-request.png b/doc/development/img/state-model-merge-request.png index 0e7556784f4..e00da10cac2 100644 Binary files a/doc/development/img/state-model-merge-request.png and b/doc/development/img/state-model-merge-request.png differ diff --git a/doc/development/ux_guide/img/button-primary.png b/doc/development/ux_guide/img/button-primary.png index f4c673f5b88..eda5ed84aec 100644 Binary files a/doc/development/ux_guide/img/button-primary.png and b/doc/development/ux_guide/img/button-primary.png differ diff --git a/doc/development/ux_guide/img/button-secondary.png b/doc/development/ux_guide/img/button-secondary.png index 57fa65b247c..26d4e8cf43d 100644 Binary files a/doc/development/ux_guide/img/button-secondary.png and b/doc/development/ux_guide/img/button-secondary.png differ diff --git a/doc/development/ux_guide/img/color-blue.png b/doc/development/ux_guide/img/color-blue.png index 6449613eb16..2ca360173eb 100644 Binary files a/doc/development/ux_guide/img/color-blue.png and b/doc/development/ux_guide/img/color-blue.png differ diff --git a/doc/development/ux_guide/img/color-green.png b/doc/development/ux_guide/img/color-green.png index 15475b36f02..489db8f4343 100644 Binary files a/doc/development/ux_guide/img/color-green.png and b/doc/development/ux_guide/img/color-green.png differ diff --git a/doc/development/ux_guide/img/color-orange.png b/doc/development/ux_guide/img/color-orange.png index f4fc09b2d9b..4c4b772d438 100644 Binary files a/doc/development/ux_guide/img/color-orange.png and b/doc/development/ux_guide/img/color-orange.png differ diff --git a/doc/development/ux_guide/img/color-red.png b/doc/development/ux_guide/img/color-red.png index 6fbbf0a885d..3440ad48f05 100644 Binary files a/doc/development/ux_guide/img/color-red.png and b/doc/development/ux_guide/img/color-red.png differ diff --git a/doc/development/ux_guide/img/components-alerts.png b/doc/development/ux_guide/img/components-alerts.png index 0b2ecc16a5f..66a43ac69e1 100644 Binary files a/doc/development/ux_guide/img/components-alerts.png and b/doc/development/ux_guide/img/components-alerts.png differ diff --git a/doc/development/ux_guide/img/components-anchorlinks.png b/doc/development/ux_guide/img/components-anchorlinks.png index 950f348277d..7dd6a8a3876 100644 Binary files a/doc/development/ux_guide/img/components-anchorlinks.png and b/doc/development/ux_guide/img/components-anchorlinks.png differ diff --git a/doc/development/ux_guide/img/components-contentblock.png b/doc/development/ux_guide/img/components-contentblock.png index 31fc1eec9df..58d87729701 100644 Binary files a/doc/development/ux_guide/img/components-contentblock.png and b/doc/development/ux_guide/img/components-contentblock.png differ diff --git a/doc/development/ux_guide/img/components-coverblock.png b/doc/development/ux_guide/img/components-coverblock.png index c8f1f87a108..fb135f9648a 100644 Binary files a/doc/development/ux_guide/img/components-coverblock.png and b/doc/development/ux_guide/img/components-coverblock.png differ diff --git a/doc/development/ux_guide/img/components-dateexact.png b/doc/development/ux_guide/img/components-dateexact.png index 8c0c5c1be40..686ca727293 100644 Binary files a/doc/development/ux_guide/img/components-dateexact.png and b/doc/development/ux_guide/img/components-dateexact.png differ diff --git a/doc/development/ux_guide/img/components-daterelative.png b/doc/development/ux_guide/img/components-daterelative.png index 1dc6d89e4ef..4954dfb51b3 100644 Binary files a/doc/development/ux_guide/img/components-daterelative.png and b/doc/development/ux_guide/img/components-daterelative.png differ diff --git a/doc/development/ux_guide/img/components-dropdown.png b/doc/development/ux_guide/img/components-dropdown.png index 5770a393b37..7f9a701c089 100644 Binary files a/doc/development/ux_guide/img/components-dropdown.png and b/doc/development/ux_guide/img/components-dropdown.png differ diff --git a/doc/development/ux_guide/img/components-fileholder.png b/doc/development/ux_guide/img/components-fileholder.png index 4b8962905d6..ec2911a1232 100644 Binary files a/doc/development/ux_guide/img/components-fileholder.png and b/doc/development/ux_guide/img/components-fileholder.png differ diff --git a/doc/development/ux_guide/img/components-horizontalform.png b/doc/development/ux_guide/img/components-horizontalform.png index 92e28cf9afc..c57dceda43a 100644 Binary files a/doc/development/ux_guide/img/components-horizontalform.png and b/doc/development/ux_guide/img/components-horizontalform.png differ diff --git a/doc/development/ux_guide/img/components-listinsidepanel.png b/doc/development/ux_guide/img/components-listinsidepanel.png index 30ceb3eaa08..3a72d39bb5d 100644 Binary files a/doc/development/ux_guide/img/components-listinsidepanel.png and b/doc/development/ux_guide/img/components-listinsidepanel.png differ diff --git a/doc/development/ux_guide/img/components-listwithavatar.png b/doc/development/ux_guide/img/components-listwithavatar.png index d3cb0ebc02b..f6db575433c 100644 Binary files a/doc/development/ux_guide/img/components-listwithavatar.png and b/doc/development/ux_guide/img/components-listwithavatar.png differ diff --git a/doc/development/ux_guide/img/components-listwithhover.png b/doc/development/ux_guide/img/components-listwithhover.png index 1484ecba6a0..8521a8ad53e 100644 Binary files a/doc/development/ux_guide/img/components-listwithhover.png and b/doc/development/ux_guide/img/components-listwithhover.png differ diff --git a/doc/development/ux_guide/img/components-panels.png b/doc/development/ux_guide/img/components-panels.png index 6e71d0ad9c9..c1391ca07e5 100644 Binary files a/doc/development/ux_guide/img/components-panels.png and b/doc/development/ux_guide/img/components-panels.png differ diff --git a/doc/development/ux_guide/img/components-referencehover.png b/doc/development/ux_guide/img/components-referencehover.png index e9fb27e2aa9..f80564dbb16 100644 Binary files a/doc/development/ux_guide/img/components-referencehover.png and b/doc/development/ux_guide/img/components-referencehover.png differ diff --git a/doc/development/ux_guide/img/components-referenceissues.png b/doc/development/ux_guide/img/components-referenceissues.png index caf9477db38..51fb2cf3e43 100644 Binary files a/doc/development/ux_guide/img/components-referenceissues.png and b/doc/development/ux_guide/img/components-referenceissues.png differ diff --git a/doc/development/ux_guide/img/components-referencelabels.png b/doc/development/ux_guide/img/components-referencelabels.png index a122b45d1f1..aba450cc3ba 100644 Binary files a/doc/development/ux_guide/img/components-referencelabels.png and b/doc/development/ux_guide/img/components-referencelabels.png differ diff --git a/doc/development/ux_guide/img/components-referencemilestone.png b/doc/development/ux_guide/img/components-referencemilestone.png index 5aa9ecd1a78..adf2555ccf8 100644 Binary files a/doc/development/ux_guide/img/components-referencemilestone.png and b/doc/development/ux_guide/img/components-referencemilestone.png differ diff --git a/doc/development/ux_guide/img/components-referencemrs.png b/doc/development/ux_guide/img/components-referencemrs.png index 6280243859a..6c3375f1ea1 100644 Binary files a/doc/development/ux_guide/img/components-referencemrs.png and b/doc/development/ux_guide/img/components-referencemrs.png differ diff --git a/doc/development/ux_guide/img/components-referencepeople.png b/doc/development/ux_guide/img/components-referencepeople.png index 99772a539cf..b8dd431e2e6 100644 Binary files a/doc/development/ux_guide/img/components-referencepeople.png and b/doc/development/ux_guide/img/components-referencepeople.png differ diff --git a/doc/development/ux_guide/img/components-rowcontentblock.png b/doc/development/ux_guide/img/components-rowcontentblock.png index 1c2d7096955..c66a50f9564 100644 Binary files a/doc/development/ux_guide/img/components-rowcontentblock.png and b/doc/development/ux_guide/img/components-rowcontentblock.png differ diff --git a/doc/development/ux_guide/img/components-simplelist.png b/doc/development/ux_guide/img/components-simplelist.png index 892f507cfc2..858e5064c25 100644 Binary files a/doc/development/ux_guide/img/components-simplelist.png and b/doc/development/ux_guide/img/components-simplelist.png differ diff --git a/doc/development/ux_guide/img/components-table.png b/doc/development/ux_guide/img/components-table.png index 7e964c885cf..cedc55758a9 100644 Binary files a/doc/development/ux_guide/img/components-table.png and b/doc/development/ux_guide/img/components-table.png differ diff --git a/doc/development/ux_guide/img/components-verticalform.png b/doc/development/ux_guide/img/components-verticalform.png index 38863ad3c1c..489ae6f862f 100644 Binary files a/doc/development/ux_guide/img/components-verticalform.png and b/doc/development/ux_guide/img/components-verticalform.png differ diff --git a/doc/development/ux_guide/img/copy-form-addissuebutton.png b/doc/development/ux_guide/img/copy-form-addissuebutton.png index 18839d447e8..8457f0ab2ab 100644 Binary files a/doc/development/ux_guide/img/copy-form-addissuebutton.png and b/doc/development/ux_guide/img/copy-form-addissuebutton.png differ diff --git a/doc/development/ux_guide/img/copy-form-addissueform.png b/doc/development/ux_guide/img/copy-form-addissueform.png index e6838c06eca..89c6b4acdfb 100644 Binary files a/doc/development/ux_guide/img/copy-form-addissueform.png and b/doc/development/ux_guide/img/copy-form-addissueform.png differ diff --git a/doc/development/ux_guide/img/copy-form-editissuebutton.png b/doc/development/ux_guide/img/copy-form-editissuebutton.png index 2435820e14f..04bcc2bf831 100644 Binary files a/doc/development/ux_guide/img/copy-form-editissuebutton.png and b/doc/development/ux_guide/img/copy-form-editissuebutton.png differ diff --git a/doc/development/ux_guide/img/copy-form-editissueform.png b/doc/development/ux_guide/img/copy-form-editissueform.png index 5ddeda33e68..126ef34ea7e 100644 Binary files a/doc/development/ux_guide/img/copy-form-editissueform.png and b/doc/development/ux_guide/img/copy-form-editissueform.png differ diff --git a/doc/development/ux_guide/img/features-contextualnav.png b/doc/development/ux_guide/img/features-contextualnav.png index df157f54c84..f8466f28627 100644 Binary files a/doc/development/ux_guide/img/features-contextualnav.png and b/doc/development/ux_guide/img/features-contextualnav.png differ diff --git a/doc/development/ux_guide/img/features-emptystates.png b/doc/development/ux_guide/img/features-emptystates.png index 3befc14588e..51835a7080b 100644 Binary files a/doc/development/ux_guide/img/features-emptystates.png and b/doc/development/ux_guide/img/features-emptystates.png differ diff --git a/doc/development/ux_guide/img/features-filters.png b/doc/development/ux_guide/img/features-filters.png index 281e55d590c..41db76db938 100644 Binary files a/doc/development/ux_guide/img/features-filters.png and b/doc/development/ux_guide/img/features-filters.png differ diff --git a/doc/development/ux_guide/img/features-globalnav.png b/doc/development/ux_guide/img/features-globalnav.png index 3c0db2247ca..73294d1b524 100644 Binary files a/doc/development/ux_guide/img/features-globalnav.png and b/doc/development/ux_guide/img/features-globalnav.png differ diff --git a/doc/development/ux_guide/img/surfaces-contentitemtitle.png b/doc/development/ux_guide/img/surfaces-contentitemtitle.png index 2eb926c1c43..3af0b56c8fb 100644 Binary files a/doc/development/ux_guide/img/surfaces-contentitemtitle.png and b/doc/development/ux_guide/img/surfaces-contentitemtitle.png differ diff --git a/doc/development/ux_guide/img/surfaces-header.png b/doc/development/ux_guide/img/surfaces-header.png index ab44d4de696..ba616388003 100644 Binary files a/doc/development/ux_guide/img/surfaces-header.png and b/doc/development/ux_guide/img/surfaces-header.png differ diff --git a/doc/development/ux_guide/img/surfaces-systeminformationblock.png b/doc/development/ux_guide/img/surfaces-systeminformationblock.png index 5d91e993e24..9f42f1d4dd0 100644 Binary files a/doc/development/ux_guide/img/surfaces-systeminformationblock.png and b/doc/development/ux_guide/img/surfaces-systeminformationblock.png differ diff --git a/doc/development/ux_guide/img/surfaces-ux.png b/doc/development/ux_guide/img/surfaces-ux.png index e692c51e8c0..53208727c64 100644 Binary files a/doc/development/ux_guide/img/surfaces-ux.png and b/doc/development/ux_guide/img/surfaces-ux.png differ diff --git a/doc/development/ux_guide/img/tooltip-placement.png b/doc/development/ux_guide/img/tooltip-placement.png index 29a61c8400a..061f82e4df0 100644 Binary files a/doc/development/ux_guide/img/tooltip-placement.png and b/doc/development/ux_guide/img/tooltip-placement.png differ diff --git a/doc/development/ux_guide/img/tooltip-usage.png b/doc/development/ux_guide/img/tooltip-usage.png index e8e4c6ded91..40c4f051cd0 100644 Binary files a/doc/development/ux_guide/img/tooltip-usage.png and b/doc/development/ux_guide/img/tooltip-usage.png differ -- cgit v1.2.1 From 39378d0e976d9552e96b300cb7f43874424d13b3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=C3=A9my=20Coutable?= Date: Wed, 23 Nov 2016 12:58:16 +0100 Subject: Document that we always use `do...end` for `before` in RSpec MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit [ci skip] Signed-off-by: Rémy Coutable --- doc/development/testing.md | 2 ++ 1 file changed, 2 insertions(+) (limited to 'doc/development') diff --git a/doc/development/testing.md b/doc/development/testing.md index 6106e47daa0..dbea6b9c9aa 100644 --- a/doc/development/testing.md +++ b/doc/development/testing.md @@ -63,6 +63,8 @@ the command line via `bundle exec teaspoon`, or via a web browser at - Use `.method` to describe class methods and `#method` to describe instance methods. - Use `context` to test branching logic. +- Use multi-line `do...end` blocks for `before` and `after`, even when it would + fit on a single line. - Don't `describe` symbols (see [Gotchas](gotchas.md#dont-describe-symbols)). - Don't assert against the absolute value of a sequence-generated attribute (see [Gotchas](gotchas.md#dont-assert-against-the-absolute-value-of-a-sequence-generated-attribute)). - Don't supply the `:each` argument to hooks since it's the default. -- cgit v1.2.1