diff options
Diffstat (limited to 'doc/development')
| -rw-r--r-- | doc/development/README.md | 1 | ||||
| -rw-r--r-- | doc/development/contributing/issue_workflow.md | 12 | ||||
| -rw-r--r-- | doc/development/contributing/merge_request_workflow.md | 2 | ||||
| -rw-r--r-- | doc/development/documentation/index.md | 2 | ||||
| -rw-r--r-- | doc/development/documentation/structure.md | 43 | ||||
| -rw-r--r-- | doc/development/fe_guide/style_guide_js.md | 109 | ||||
| -rw-r--r-- | doc/development/feature_flags.md | 31 | ||||
| -rw-r--r-- | doc/development/rolling_out_changes_using_feature_flags.md | 24 |
8 files changed, 143 insertions, 81 deletions
diff --git a/doc/development/README.md b/doc/development/README.md index 43d3865da0e..d8604a4f3e5 100644 --- a/doc/development/README.md +++ b/doc/development/README.md @@ -50,6 +50,7 @@ description: 'Learn how to contribute to GitLab.' - [Permissions](permissions.md) - [Prometheus metrics](prometheus_metrics.md) - [Guidelines for reusing abstractions](reusing_abstractions.md) +- [DeclarativePolicy framework](policies.md) ## Performance guides diff --git a/doc/development/contributing/issue_workflow.md b/doc/development/contributing/issue_workflow.md index 2f06677bfec..1b25a5a2fb7 100644 --- a/doc/development/contributing/issue_workflow.md +++ b/doc/development/contributing/issue_workflow.md @@ -108,12 +108,12 @@ Priority labels help us define the time a ~bug fix should be completed. Priority If there are multiple defects, the priority decides which defect has to be fixed immediately versus later. This label documents the planned timeline & urgency which is used to measure against our actual SLA on delivering ~bug fixes. -| Label | Meaning | Estimate time to fix | -|-------|-----------------|------------------------------------------------------------------| -| ~P1 | Urgent Priority | The current release + potentially immediate hotfix to GitLab.com | -| ~P2 | High Priority | The next release | -| ~P3 | Medium Priority | Within the next 3 releases (approx one quarter) | -| ~P4 | Low Priority | Anything outside the next 3 releases (approx beyond one quarter) | +| Label | Meaning | Defect SLA (applies only to ~bug and ~security defects) | +|-------|-----------------|----------------------------------------------------------------------------| +| ~P1 | Urgent Priority | The current release + potentially immediate hotfix to GitLab.com (30 days) | +| ~P2 | High Priority | The next release (60 days) | +| ~P3 | Medium Priority | Within the next 3 releases (approx one quarter or 90 days) | +| ~P4 | Low Priority | Anything outside the next 3 releases (more than one quarter or 120 days) | ## Severity labels diff --git a/doc/development/contributing/merge_request_workflow.md b/doc/development/contributing/merge_request_workflow.md index a286e74908c..0d20e1a02dd 100644 --- a/doc/development/contributing/merge_request_workflow.md +++ b/doc/development/contributing/merge_request_workflow.md @@ -156,7 +156,7 @@ the feature you contribute through all of these steps. 1. Performance/scalability implications have been considered, addressed, and tested 1. [Documented][doc-guidelines] in the `/doc` directory 1. [Changelog entry added][changelog], if necessary -1. Reviewed and any concerns are addressed +1. Reviewed by UX/FE/BE and any concerns are addressed 1. Merged by a project maintainer 1. Added to the release blog article, if relevant 1. Added to [the website](https://gitlab.com/gitlab-com/www-gitlab-com/), if relevant diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md index 2db78e4a365..ce2424eca3b 100644 --- a/doc/development/documentation/index.md +++ b/doc/development/documentation/index.md @@ -321,7 +321,7 @@ The following sample `markdownlint` configuration modifies the available default } ``` -For [`markdownlint`](https://gitahub.com/DavidAnson/markdownlint/), this configuration must be +For [`markdownlint`](https://github.com/DavidAnson/markdownlint/), this configuration must be placed in a [valid location](https://github.com/igorshubovych/markdownlint-cli#configuration). For example, `~/.markdownlintrc`. diff --git a/doc/development/documentation/structure.md b/doc/development/documentation/structure.md index 1002836096a..01068e23082 100644 --- a/doc/development/documentation/structure.md +++ b/doc/development/documentation/structure.md @@ -21,21 +21,21 @@ Before getting started, read through the following docs: Every document should include the following content in the following sequence: - **Feature name**: defines an intuitive name for the feature that clearly -states what it is and is consistent with any relevant UI text. + states what it is and is consistent with any relevant UI text. - **Feature overview** and description: describe what it is, what it does, and in what context it should be used. - **Use cases**: describes real use case scenarios for that feature. - **Requirements**: describes what software and/or configuration is required to be able to -use the feature and, if applicable, prerequisite knowledge for being able to follow/implement the tutorial. -For example, familiarity with GitLab CI/CD, an account on a third-party service, dependencies installed, etc. -Link each one to its most relevant resource; i.e., where the reader can go to begin to fullfil that requirement. -(Another doc page, a third party application's site, etc.) + use the feature and, if applicable, prerequisite knowledge for being able to follow/implement the tutorial. + For example, familiarity with GitLab CI/CD, an account on a third-party service, dependencies installed, etc. + Link each one to its most relevant resource; i.e., where the reader can go to begin to fullfil that requirement. + (Another doc page, a third party application's site, etc.) - **Instructions**: clearly describes the steps to use the feature, leaving no gaps. - **Troubleshooting** guide (recommended but not required): if you know beforehand what issues -one might have when setting it up, or when something is changed, or on upgrading, it's -important to describe those too. Think of things that may go wrong and include them in the -docs. This is important to minimize requests for support, and to avoid doc comments with -questions that you know someone might ask. Answering them beforehand only makes your -document better and more approachable. + one might have when setting it up, or when something is changed, or on upgrading, it's + important to describe those too. Think of things that may go wrong and include them in the + docs. This is important to minimize requests for support, and to avoid doc comments with + questions that you know someone might ask. Answering them beforehand only makes your + document better and more approachable. For additional details, see the subsections below, as well as the [Documentation template for new docs](#Documentation-template-for-new-docs). @@ -55,10 +55,11 @@ You should answer this question: what can you do with this feature/change? Use c are examples of how this feature or change can be used in real life. Examples: -- CE and EE: [Issues](../user/project/issues/index.md#use-cases) -- CE and EE: [Merge Requests](../user/project/merge_requests/index.md#overview) -- EE-only: [Geo](https://docs.gitlab.com/ee/gitlab-geo/README.html#overview) -- EE-only: [Jenkins integration](https://docs.gitlab.com/ee/integration/jenkins.md#overview) + +- CE and EE: [Issues](../../user/project/issues/index.md#use-cases) +- CE and EE: [Merge Requests](../../user/project/merge_requests/index.md) +- EE-only: [Geo](https://docs.gitlab.com/ee/administration/geo/replication/index.html) +- EE-only: [Jenkins integration](https://docs.gitlab.com/ee/integration/jenkins.html) Note that if you don't have anything to add between the doc title (`<h1>`) and the header `## Overview`, you can omit the header, but keep the content of the @@ -72,14 +73,14 @@ and for every **major** feature present in Community Edition. Your new document will be discoverable by the user only if: - Crosslinked from the higher-level index (e.g., Issue Boards docs -should be linked from Issues; Prometheus docs should be linked from -Monitoring; CI/CD tutorials should be linked from CI/CD examples). + should be linked from Issues; Prometheus docs should be linked from + Monitoring; CI/CD tutorials should be linked from CI/CD examples). - When referencing other GitLab products and features, link to their -respective docs; when referencing third-party products or technologies, -link out to their external sites, documentation, and resources. + respective docs; when referencing third-party products or technologies, + link out to their external sites, documentation, and resources. - The headings are clear. E.g., "App testing" is a bad heading, "Testing -an application with GitLab CI/CD" is much better. Think of something -someone will search for and use these keywords in the headings. + an application with GitLab CI/CD" is much better. Think of something + someone will search for and use these keywords in the headings. ## Documentation template for new docs @@ -133,7 +134,7 @@ is simple and the document is short. - Be clear, concise, and stick to the goal of the doc: explain how to use that feature. - Use inclusive language and avoid jargons, as well as uncommon and -fancy words. The docs should be clear and very easy to understand. +fancy words. The docs should be clear and easy to understand. - Write in the 3rd person (use "we", "you", "us", "one", instead of "I" or "me"). - Always provide internal and external reference links. - Always link the doc from its higher-level index. diff --git a/doc/development/fe_guide/style_guide_js.md b/doc/development/fe_guide/style_guide_js.md index 656ddd868cd..1e0529262ad 100644 --- a/doc/development/fe_guide/style_guide_js.md +++ b/doc/development/fe_guide/style_guide_js.md @@ -1,11 +1,13 @@ # Style guides and linting + See the relevant style guides for our guidelines and for information on linting: ## JavaScript + We defer to [Airbnb][airbnb-js-style-guide] on most style-related conventions and enforce them with eslint. -See [our current .eslintrc][eslintrc] for specific rules and patterns. +See [our current .eslintrc](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/.eslintrc.yml) for specific rules and patterns. ### Common @@ -21,10 +23,10 @@ refactor an existing one, you should abide by the eslint rules. ```javascript // bad /* eslint-disable */ - + // better /* eslint-disable some-rule, some-other-rule */ - + // best // nothing :) ``` @@ -34,14 +36,14 @@ refactor an existing one, you should abide by the eslint rules. ```javascript // bad /* eslint-disable no-new */ - + import Foo from 'foo'; - + new Foo(); - + // better import Foo from 'foo'; - + // eslint-disable-next-line no-new new Foo(); ``` @@ -58,11 +60,11 @@ followed by any global declarations, then a blank newline prior to any imports o /* global Foo */ /* eslint-disable no-new */ import Bar from './bar'; - + // good /* eslint-disable no-new */ /* global Foo */ - + import Bar from './bar'; ``` @@ -73,7 +75,7 @@ followed by any global declarations, then a blank newline prior to any imports o ```javascript // bad /* globals Flash, Cookies, jQuery */ - + // good /* global Flash */ /* global Cookies */ @@ -85,7 +87,7 @@ followed by any global declarations, then a blank newline prior to any imports o ```javascript // bad fn(p1, p2, p3, p4) {} - + // good fn(options) {} ``` @@ -191,28 +193,28 @@ Do not use them anymore and feel free to remove them when refactoring legacy cod ```javascript // bad const values = {foo: 1}; - + function impureFunction(items) { const bar = 1; - + items.foo = items.a * bar + 2; - + return items.a; } - + const c = impureFunction(values); - + // good var values = {foo: 1}; - + function pureFunction (foo) { var bar = 1; - + foo = foo * bar + 2; - + return foo; } - + var c = pureFunction(values.foo); ``` @@ -231,10 +233,10 @@ Do not use them anymore and feel free to remove them when refactoring legacy cod document.addEventListener('click', this.handleCallback) }, handleCallback() { - + } } - + // Good export class Foo { constructor() { @@ -253,12 +255,12 @@ Do not use them anymore and feel free to remove them when refactoring legacy cod ```javascript const users = [ { name: 'Foo' }, { name: 'Bar' } ]; - + // bad users.forEach((user, index) => { user.id = index; }); - + // good const usersWithId = users.map((user, index) => { return Object.assign({}, user, { id: index }); @@ -272,10 +274,10 @@ Do not use them anymore and feel free to remove them when refactoring legacy cod ```javascript // bad +'10' // 10 - + // good Number('10') // 10 - + // better parseInt('10', 10); ``` @@ -289,7 +291,7 @@ Do not use them anymore and feel free to remove them when refactoring legacy cod <button class="add-user"> Add User </button> - + // good <button class="js-add-user"> Add User @@ -299,10 +301,12 @@ Do not use them anymore and feel free to remove them when refactoring legacy cod ### Vue.js #### `eslint-vue-plugin` + We default to [eslint-vue-plugin][eslint-plugin-vue], with the `plugin:vue/recommended`. Please check this [rules][eslint-plugin-vue-rules] for more documentation. #### Basic Rules + 1. The service has it's own file 1. The store has it's own file 1. Use a function in the bundle file to instantiate the Vue component: @@ -314,7 +318,7 @@ Please check this [rules][eslint-plugin-vue-rules] for more documentation. new Component({}) } } - + // good document.addEventListener('DOMContentLoaded', () => new Vue({ el: '#element', @@ -336,7 +340,7 @@ Please check this [rules][eslint-plugin-vue-rules] for more documentation. } } } - + // good class Store { constructor() { @@ -354,14 +358,14 @@ Please check this [rules][eslint-plugin-vue-rules] for more documentation. ```javascript // bad import cardBoard from 'cardBoard.vue' - + components: { cardBoard, }; - + // good import CardBoard from 'cardBoard.vue' - + components: { CardBoard, }; @@ -373,13 +377,13 @@ Please check this [rules][eslint-plugin-vue-rules] for more documentation. ```javascript // bad <component class="btn"> - + // good <component css-class="btn"> - + // bad <component myProp="prop" /> - + // good <component my-prop="prop" /> ``` @@ -387,6 +391,7 @@ Please check this [rules][eslint-plugin-vue-rules] for more documentation. [#34371]: https://gitlab.com/gitlab-org/gitlab-ce/issues/34371 #### Alignment + 1. Follow these alignment styles for the template method: 1. With more than one attribute, all attributes should be on a new line: @@ -395,31 +400,31 @@ Please check this [rules][eslint-plugin-vue-rules] for more documentation. // bad <component v-if="bar" param="baz" /> - + <button class="btn">Click me</button> - + // good <component v-if="bar" param="baz" /> - + <button class="btn"> Click me </button> ``` - + 1. The tag can be inline if there is only one attribute: ```javascript // good <component bar="bar" /> - + // good <component bar="bar" /> - + // bad <component bar="bar" /> @@ -434,7 +439,7 @@ Please check this [rules][eslint-plugin-vue-rules] for more documentation. template: ` <button :class='style'>Button</button> ` - + // good template: ` <button :class="style">Button</button> @@ -447,7 +452,7 @@ Please check this [rules][eslint-plugin-vue-rules] for more documentation. ```javascript // bad props: ['foo'] - + // good props: { foo: { @@ -467,7 +472,7 @@ Please check this [rules][eslint-plugin-vue-rules] for more documentation. type: String, } } - + // good props: { foo: { @@ -490,7 +495,7 @@ On those a default key should not be provided. required: false, } } - + // good props: { foo: { @@ -499,7 +504,7 @@ On those a default key should not be provided. default: 'bar' } } - + // good props: { foo: { @@ -534,7 +539,7 @@ On those a default key should not be provided. ```javascript // bad <component v-on:click="eventHandler"/> - + // good <component @click="eventHandler"/> ``` @@ -544,7 +549,7 @@ On those a default key should not be provided. ```javascript // bad <component v-bind:class="btn"/> - + // good <component :class="btsn"/> ``` @@ -556,7 +561,7 @@ On those a default key should not be provided. ```javascript // bad <component></component> - + // good <component /> ``` @@ -650,7 +655,7 @@ Useful links: title="Some tooltip text"> Text </span> - + // good <span v-tooltip @@ -666,10 +671,10 @@ Useful links: ```javascript // bad <span data-original-title="tooltip text">Foo</span> - + // good <span title="tooltip text">Foo</span> - + $('span').tooltip('_fixTitle'); ``` diff --git a/doc/development/feature_flags.md b/doc/development/feature_flags.md index 417298205f5..0f1f079bdb4 100644 --- a/doc/development/feature_flags.md +++ b/doc/development/feature_flags.md @@ -69,6 +69,37 @@ For more information about rolling out changes using feature flags, refer to the [Rolling out changes using feature flags](rolling_out_changes_using_feature_flags.md) guide. +### Frontend + +For frontend code you can use the method `push_frontend_feature_flag`, which is +available to all controllers that inherit from `ApplicationController`. Using +this method you can expose the state of a feature flag as follows: + +```ruby +before_action do + push_frontend_feature_flag(:vim_bindings) +end + +def index + # ... +end + +def edit + # ... +end +``` + +You can then check for the state of the feature flag in JavaScript as follows: + +```javascript +if ( gon.features.vimBindings ) { + // ... +} +``` + +The name of the feature flag in JavaScript will always be camelCased, meaning +that checking for `gon.features.vim_bindings` would not work. + ### Specs In the test environment `Feature.enabled?` is stubbed to always respond to `true`, diff --git a/doc/development/rolling_out_changes_using_feature_flags.md b/doc/development/rolling_out_changes_using_feature_flags.md index 905aa26a40b..dada59ce242 100644 --- a/doc/development/rolling_out_changes_using_feature_flags.md +++ b/doc/development/rolling_out_changes_using_feature_flags.md @@ -151,3 +151,27 @@ most cases this will translate to a feature (with a feature flag) being shipped in RC1, followed by the feature flag being removed in RC2. This in turn means the feature will be stable by the time we publish a stable package around the 22nd of the month. + +## Undefined feature flags default to "on" + +By default, the [`Project#feature_available?`][project-fa], +[`Namespace#feature_available?`][namespace-fa] (EE), and +[`License.feature_available?`][license-fa] (EE) methods will check if the +specified feature is behind a feature flag. Unless the feature is explicitly +disabled or limited to a percentage of users, the feature flag check will +default to `true`. + +As an example, if you were to ship the backend half of a feature behind a flag, +you'd want to explicitly disable that flag until the frontend half is also ready +to be shipped. You can do this via ChatOps: + +``` +/chatops run feature set some_feature 0 +``` + +Note that you can do this at any time, even before the merge request using the +flag has been merged! + +[project-fa]: https://gitlab.com/gitlab-org/gitlab-ee/blob/4cc1c62918aa4c31750cb21dfb1a6c3492d71080/app/models/project_feature.rb#L63-68 +[namespace-fa]: https://gitlab.com/gitlab-org/gitlab-ee/blob/4cc1c62918aa4c31750cb21dfb1a6c3492d71080/ee/app/models/ee/namespace.rb#L71-85 +[license-fa]: https://gitlab.com/gitlab-org/gitlab-ee/blob/4cc1c62918aa4c31750cb21dfb1a6c3492d71080/ee/app/models/license.rb#L293-300 |