You can also use the `uml::` directive for compatibility with [sphinxcontrib-plantuml](https://pypi.python.org/pypi/sphinxcontrib-plantuml), but please note that we currently only support the `caption` option.
- Prometheus and the various exporters listed in this page are bundled in the
Omnibus GitLab package. Check each exporter's documentation for the timeline
they got added. For installations from source you will have to install them
yourself. Over subsequent releases additional GitLab metrics will be captured.
- Prometheus services are on by default with GitLab 9.0.
- Prometheus and its exporters do not authenticate users, and will be available
to anyone who can access them.
>**Notes:**
> - Prometheus and the various exporters listed in this page are bundled in the
> Omnibus GitLab package. Check each exporter's documentation for the timeline
> they got added. For installations from source you will have to install them
> yourself. Over subsequent releases additional GitLab metrics will be captured.
> - Prometheus services are on by default with GitLab 9.0.
> - Prometheus and its exporters do not authenticate users, and will be available
> to anyone who can access them.
[Prometheus] is a powerful time-series monitoring service, providing a flexible
platform for monitoring GitLab and other software products.
...
...
@@ -107,7 +107,7 @@ Sample Prometheus queries:
> Introduced in GitLab 9.0.
> Pod monitoring introduced in GitLab 9.4.
If your GitLab server is running within Kubernetes, Prometheus will collect metrics from the Nodes and [annotated Pods](https://prometheus.io/docs/operating/configuration/#<kubernetes_sd_config>) in the cluster, including performance data on each container. This is particularly helpful if your CI/CD environments run in the same cluster, as you can use the [Prometheus project integration][] to monitor them.
If your GitLab server is running within Kubernetes, Prometheus will collect metrics from the Nodes and [annotated Pods](https://prometheus.io/docs/operating/configuration/#kubernetes_sd_config) in the cluster, including performance data on each container. This is particularly helpful if your CI/CD environments run in the same cluster, as you can use the [Prometheus project integration][] to monitor them.
@@ -119,8 +120,8 @@ If you are using AWS IAM profiles, be sure to omit the AWS access key and secret
1. Save the file and [reconfigure GitLab][] for the changes to take effect.
1. Migrate any existing local uploads to the object storage:
>**Notes:**
These task complies with the `BATCH` environment variable to process uploads in batch (200 by default). All of the processing will be done in a background worker and requires **no downtime**.
> **Notes:**
> These task complies with the `BATCH` environment variable to process uploads in batch (200 by default). All of the processing will be done in a background worker and requires **no downtime**.
@@ -167,11 +168,9 @@ _The uploads are stored by default in
1. Save the file and [restart GitLab][] for the changes to take effect.
1. Migrate any existing local uploads to the object storage:
>**Notes:**
- These task comply with the `BATCH` environment variable to process uploads in batch (200 by default). All of the processing will be done in a background worker and requires **no downtime**.
- To migrate in production use `RAILS_ENV=production` environment variable.
> **Notes:**
> - These task comply with the `BATCH` environment variable to process uploads in batch (200 by default). All of the processing will be done in a background worker and requires **no downtime**.
> - To migrate in production use `RAILS_ENV=production` environment variable.
@@ -76,8 +76,8 @@ Below are the changes made between V3 and V4.
- Simplify project payload exposed on Environment endpoints [!9675](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9675)
- API uses merge request `IID`s (internal ID, as in the web UI) rather than `ID`s. This affects the merge requests, award emoji, todos, and time tracking APIs. [!9530](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9530)
- API uses issue `IID`s (internal ID, as in the web UI) rather than `ID`s. This affects the issues, award emoji, todos, and time tracking APIs. [!9530](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9530)
- Change initial page from `0` to `1` on `GET /projects/:id/repository/commits` (like on the rest of the API) [!9679](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9679)
- Return correct `Link` header data for `GET /projects/:id/repository/commits` [!9679](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9679)
- Change initial page from `0` to `1` on `GET /projects/:id/repository/commits` (like on the rest of the API) [!9679](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9679)
- Return correct `Link` header data for `GET /projects/:id/repository/commits`[!9679](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9679)
- Update endpoints for repository files [!9637](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9637)
- Moved `GET /projects/:id/repository/files?file_path=:file_path` to `GET /projects/:id/repository/files/:file_path` (`:file_path` should be URL-encoded)
-`GET /projects/:id/repository/blobs/:sha` now returns JSON attributes for the blob identified by `:sha`, instead of finding the commit identified by `:sha` and returning the raw content of the blob in that commit identified by the required `?filepath=:filepath`
@@ -87,18 +87,18 @@ will later see, is exposed in various places within GitLab. Each time a job that
has an environment specified and succeeds, a deployment is recorded, remembering
the Git SHA and environment name.
>**Note:**
Starting with GitLab 8.15, the environment name is exposed to the Runner in
two forms: `$CI_ENVIRONMENT_NAME`, and `$CI_ENVIRONMENT_SLUG`. The first is
the name given in `.gitlab-ci.yml` (with any variables expanded), while the
second is a "cleaned-up" version of the name, suitable for use in URLs, DNS,
etc.
>**Note:**
Starting with GitLab 9.3, the environment URL is exposed to the Runner via
`$CI_ENVIRONMENT_URL`. The URL would be expanded from `.gitlab-ci.yml`, or if
the URL was not defined there, the external URL from the environment would be
used.
>**Note:**
> Starting with GitLab 8.15, the environment name is exposed to the Runner in
> two forms: `$CI_ENVIRONMENT_NAME`, and `$CI_ENVIRONMENT_SLUG`. The first is
> the name given in `.gitlab-ci.yml` (with any variables expanded), while the
> second is a "cleaned-up" version of the name, suitable for use in URLs, DNS,
> etc.
>
>**Note:**
> Starting with GitLab 9.3, the environment URL is exposed to the Runner via
> `$CI_ENVIRONMENT_URL`. The URL would be expanded from `.gitlab-ci.yml`, or if
> the URL was not defined there, the external URL from the environment would be
> used.
To sum up, with the above `.gitlab-ci.yml` we have achieved that:
...
...
@@ -134,14 +134,15 @@ There's a bunch of information there, specifically you can see:
- A button that re-deploys the latest deployment, meaning it runs the job
defined by the environment name for that specific commit
>**Notes:**
- While you can create environments manually in the web interface, we recommend
that you define your environments in `.gitlab-ci.yml` first. They will
be automatically created for you after the first deploy.
- The environments page can only be viewed by Reporters and above. For more
information on the permissions, see the [permissions documentation][permissions].
- Only deploys that happen after your `.gitlab-ci.yml` is properly configured
will show up in the "Environment" and "Last deployment" lists.
> **Notes:**
>
> - While you can create environments manually in the web interface, we recommend
> that you define your environments in `.gitlab-ci.yml` first. They will
> be automatically created for you after the first deploy.
> - The environments page can only be viewed by Reporters and above. For more
> information on the permissions, see the [permissions documentation][permissions].
> - Only deploys that happen after your `.gitlab-ci.yml` is properly configured
> will show up in the "Environment" and "Last deployment" lists.
The information shown in the Environments page is limited to the latest
deployments, but as you may have guessed an environment can have multiple
...
...
@@ -563,13 +564,13 @@ exist, you should see something like:
## Monitoring environments
>**Notes:**
>**Notes:**
>
- For the monitoring dashboard to appear, you need to:
- Have enabled the [Prometheus integration][prom]
- Configured Prometheus to collect at least one [supported metric](../user/project/integrations/prometheus_library/metrics.md)
- With GitLab 9.2, all deployments to an environment are shown directly on the
monitoring dashboard
> - For the monitoring dashboard to appear, you need to:
> - Have enabled the [Prometheus integration][prom]
> - Configured Prometheus to collect at least one [supported metric](../user/project/integrations/prometheus_library/metrics.md)
> - With GitLab 9.2, all deployments to an environment are shown directly on the
> monitoring dashboard
If you have enabled [Prometheus for monitoring system and response metrics](https://docs.gitlab.com/ee/user/project/integrations/prometheus.html), you can monitor the performance behavior of your app running in each environment.
@@ -250,7 +250,7 @@ code snippet right after your description in a new line: `~"feature proposal"`.
Please keep feature proposals as small and simple as possible, complex ones
might be edited to make them small and simple.
Please submit Feature Proposals using the ['Feature Proposal' issue template](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/.gitlab/issue_templates/FeatureProposal.md) provided on the issue tracker.
Please submit Feature Proposals using the ['Feature Proposal' issue template](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/.gitlab/issue_templates/Feature%20Proposal.md) provided on the issue tracker.
For changes in the interface, it is helpful to include a mockup. Issues that add to, or change, the interface should
be given the ~"UX" label. This will allow the UX team to provide input and guidance. You may
@@ -17,6 +17,7 @@ at the top, but legacy files are a special case. Any time you develop a new fea
refactor an existing one, you should abide by the eslint rules.
1.**Never Ever EVER** disable eslint globally for a file
```javascript
// bad
/* eslint-disable */
...
...
@@ -29,6 +30,7 @@ refactor an existing one, you should abide by the eslint rules.
```
1. If you do need to disable a rule for a single violation, try to do it as locally as possible
```javascript
// bad
/* eslint-disable no-new */
...
...
@@ -43,12 +45,14 @@ refactor an existing one, you should abide by the eslint rules.
// eslint-disable-next-line no-new
new Foo();
```
1. There are few rules that we need to disable due to technical debt. Which are:
1. [no-new][eslint-new]
1. [class-methods-use-this][eslint-this]
1. When they are needed _always_ place ESlint directive comment blocks on the first line of a script,
followed by any global declarations, then a blank newline prior to any imports or code.
```javascript
// bad
/* global Foo */
...
...
@@ -65,6 +69,7 @@ followed by any global declarations, then a blank newline prior to any imports o
1. **Never** disable the `no-undef` rule. Declare globals with `/* global Foo */` instead.
1. When declaring multiple globals, always use one `/* global [name] */` line per variable.
```javascript
// bad
/* globals Flash, Cookies, jQuery */
...
...
@@ -76,6 +81,7 @@ followed by any global declarations, then a blank newline prior to any imports o
```
1. Use up to 3 parameters for a function or class. If you need more accept an Object instead.
```javascript
// bad
fn(p1, p2, p3, p4) {}
...
...
@@ -85,6 +91,7 @@ followed by any global declarations, then a blank newline prior to any imports o
```
#### Modules, Imports, and Exports
1. Use ES module syntax to import modules
```javascript
// bad
...
...
@@ -178,7 +185,9 @@ Do not use them anymore and feel free to remove them when refactoring legacy cod
```
#### Data Mutation and Pure functions
1. Strive to write many small pure functions, and minimize where mutations occur.
```javascript
// bad
const values = {foo: 1};
...
...
@@ -208,13 +217,13 @@ Do not use them anymore and feel free to remove them when refactoring legacy cod
```
1. Avoid constructors with side-effects.
Although we aim for code without side-effects we need some side-effects for our code to run.
Although we aim for code without side-effects we need some side-effects for our code to run.
If the class won't do anything if we only instantiate it, it's ok to add side effects into the constructor (_Note:_ The following is just an example. If the only purpose of the class is to add an event listener and handle the callback a function will be more suitable.)
If the class won't do anything if we only instantiate it, it's ok to add side effects into the constructor (_Note:_ The following is just an example. If the only purpose of the class is to add an event listener and handle the callback a function will be more suitable.)
```javascript
// Bad
exportclassFoo{
```javascript
// Bad
export class Foo {
constructor() {
this.init();
}
...
...
@@ -224,23 +233,24 @@ export class Foo {
handleCallback() {
}
}
}
// Good
exportclassFoo{
// Good
export class Foo {
constructor() {
document.addEventListener()
}
handleCallback() {
}
}
```
}
```
On the other hand, if a class only needs to extend a third party/add event listeners in some specific cases, they should be initialized outside of the constructor.
On the other hand, if a class only needs to extend a third party/add event listeners in some specific cases, they should be initialized outside of the constructor.
1. Prefer `.map`, `.reduce` or `.filter` over `.forEach`
A forEach will most likely cause side effects, it will be mutating the array being iterated. Prefer using `.map`,
`.reduce` or `.filter`
A forEach will most likely cause side effects, it will be mutating the array being iterated. Prefer using `.map`,
@@ -256,7 +266,9 @@ A forEach will most likely cause side effects, it will be mutating the array bei
```
#### Parse Strings into Numbers
1. `parseInt()` is preferable over `Number()` or `+`
```javascript
// bad
+'10' // 10
...
...
@@ -269,7 +281,9 @@ A forEach will most likely cause side effects, it will be mutating the array bei
```
#### CSS classes used for JavaScript
1. If the class is being used in Javascript it needs to be prepend with `js-`
```html
// bad
<buttonclass="add-user">
...
...
@@ -292,6 +306,7 @@ Please check this [rules][eslint-plugin-vue-rules] for more documentation.
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:
```javascript
// bad
class {
...
...
@@ -311,6 +326,7 @@ Please check this [rules][eslint-plugin-vue-rules] for more documentation.
```
1. Do not use a singleton for the service or the store
```javascript
// bad
class Store {
...
...
@@ -334,6 +350,7 @@ Please check this [rules][eslint-plugin-vue-rules] for more documentation.
1. **Extensions**: Use `.vue` extension for Vue components. Do not use `.js` as file extension ([#34371]).
1. **Reference Naming**: Use PascalCase for their instances:
```javascript
// bad
import cardBoard from 'cardBoard.vue'
...
...
@@ -352,6 +369,7 @@ Please check this [rules][eslint-plugin-vue-rules] for more documentation.
1. **Props Naming:** Avoid using DOM component prop names.
1. **Props Naming:** Use kebab-case instead of camelCase to provide props in templates.
```javascript
// bad
<componentclass="btn">
...
...
@@ -370,7 +388,9 @@ Please check this [rules][eslint-plugin-vue-rules] for more documentation.
#### Alignment
1. Follow these alignment styles for the template method:
1. With more than one attribute, all attributes should be on a new line:
```javascript
// bad
<component v-if="bar"
...
...
@@ -388,7 +408,9 @@ Please check this [rules][eslint-plugin-vue-rules] for more documentation.
Click me
</button>
```
1. The tag can be inline if there is only one attribute:
```javascript
// good
<component bar="bar" />
...
...
@@ -404,7 +426,9 @@ Please check this [rules][eslint-plugin-vue-rules] for more documentation.
```
#### Quotes
1. Always use double quotes `"` inside templates and single quotes `'` for all other JS.
```javascript
// bad
template: `
...
...
@@ -418,6 +442,7 @@ Please check this [rules][eslint-plugin-vue-rules] for more documentation.
```
#### Props
1. Props should be declared as an object
```javascript
// bad
...
...
@@ -434,6 +459,7 @@ Please check this [rules][eslint-plugin-vue-rules] for more documentation.
```
1. Required key should always be provided when declaring a prop
```javascript
// bad
props: {
...
...
@@ -455,6 +481,7 @@ Please check this [rules][eslint-plugin-vue-rules] for more documentation.
1. Default key should be provided if the prop is not required.
_Note:_ There are some scenarios where we need to check for the existence of the property.
On those a default key should not be provided.
```javascript
// good
props: {
...
...
@@ -483,6 +510,7 @@ On those a default key should not be provided.
```
#### Data
1. `data` method should always be a function
```javascript
...
...
@@ -502,27 +530,29 @@ On those a default key should not be provided.
#### Directives
1. Shorthand `@` is preferable over `v-on`
```javascript
// bad
<component v-on:click="eventHandler"/>
// good
<component@click="eventHandler"/>
```
1. Shorthand `:` is preferable over `v-bind`
```javascript
// bad
<componentv-bind:class="btn"/>
// good
<component:class="btn"/>
<component:class="btsn"/>
```
#### Closing tags
1. Prefer self closing component tags
```javascript
// bad
<component></component>
...
...
@@ -534,6 +564,7 @@ On those a default key should not be provided.
#### Ordering
1. Tag order in `.vue` file
```
<script>
// ...
...
...
@@ -553,9 +584,11 @@ On those a default key should not be provided.
Check [order of properties in components rule][vue-order].
#### `:key`
When using `v-for` you need to provide a *unique*`:key` attribute for each item.
1. If the elements of the array being iterated have an unique `id` it is advised to use it:
```html
<div
v-for="item in items"
...
...
@@ -566,6 +599,7 @@ When using `v-for` you need to provide a *unique* `:key` attribute for each item
```
1. When the elements being iterated don't have a unique id, you can use the array index as the `:key` attribute
```html
<div
v-for="(item, index) in items"
...
...
@@ -575,8 +609,8 @@ When using `v-for` you need to provide a *unique* `:key` attribute for each item
</div>
```
1. When using `v-for` with `template` and there is more than one child element, the `:key` values must be unique. It's advised to use `kebab-case` namespaces.
```html
<template v-for="(item, index) in items">
<span :key="`span-${index}`"></span>
...
...
@@ -585,6 +619,7 @@ When using `v-for` you need to provide a *unique* `:key` attribute for each item
```
1. When dealing with nested `v-for` use the same guidelines as above.
```html
<div
v-for="item in items"
...
...
@@ -599,13 +634,15 @@ When using `v-for` you need to provide a *unique* `:key` attribute for each item
The goal of this accord is to make sure we are all on the same page.
1. When writing Vue, you may not use jQuery in your application.
...
...
@@ -650,6 +689,7 @@ The goal of this accord is to make sure we are all on the same page.
1. Once you have chosen a centralized state management solution you must use it for your entire application. i.e. Don't mix and match your state management solutions.
1. Do not call a mutation directly. Always use an action to commit a mutation. Doing so will keep consistency throughout the application. From Vuex docs:
> why don't we just call store.commit('action') directly? Well, remember that mutations must be synchronous? Actions aren't. We can perform asynchronous operations inside an action.
@@ -12,34 +12,34 @@ You can run eslint locally by running `yarn eslint`
<aname="avoid-foreach"></a><aname="1.1"></a>
-[1.1](#avoid-foreach)**Avoid ForEach when mutating data** Use `map`, `reduce` or `filter` instead of `forEach` when mutating data. This will minimize mutations in functions ([which is aligned with Airbnb's style guide][airbnb-minimize-mutations])
```
// bad
users.forEach((user, index) => {
```
// bad
users.forEach((user, index) => {
user.id = index;
});
});
// good
const usersWithId = users.map((user, index) => {
// good
const usersWithId = users.map((user, index) => {
return Object.assign({}, user, { id: index });
});
```
});
```
## Functions
<aname="limit-params"></a><aname="2.1"></a>
-[2.1](#limit-params)**Limit number of parameters** If your function or method has more than 3 parameters, use an object as a parameter instead.
- [3.2](#avoid-classes-to-handle-dom-events) **Avoid classes to handle DOM events** If the only purpose of the class is to bind a DOM event and handle the callback, prefer using a function.
- [3.3](#element-container) **Pass element container to constructor** When your class manipulates the DOM, receive the element container as a parameter.
This is more maintainable and performant.
```
// bad
class a {
```
// bad
class a {
constructor() {
document.querySelector('.b');
}
}
}
// good
class a {
// good
class a {
constructor(options) {
options.container.querySelector('.b');
}
}
```
}
```
## Type Casting & Coercion
<a name="use-parseint"></a><a name="4.1"></a>
- [4.1](#use-parseint) **Use ParseInt** Use `ParseInt` when converting a numeric string into a number.
```
// bad
Number('10')
```
// bad
Number('10')
// good
parseInt('10', 10);
```
// good
parseInt('10', 10);
```
## CSS Selectors
<a name="use-js-prefix"></a><a name="5.1"></a>
- [5.1](#use-js-prefix) **Use js prefix** If a CSS class is only being used in JavaScript as a reference to the element, prefix the class name with `js-`
- [6.2](#use-relative-paths) **Use relative paths for distant modules** If the module you are importing is two or more levels up, use a relative path instead of an absolute path.
```
// bad
import GitLabStyleGuide from '../../../guides/GitLabStyleGuide';
```
// bad
import GitLabStyleGuide from '../../../guides/GitLabStyleGuide';
// good
import GitLabStyleGuide from '~/GitLabStyleGuide';
```
// good
import GitLabStyleGuide from '~/GitLabStyleGuide';
```
<a name="global-namespace"></a><a name="6.3"></a>
- [6.3](#global-namespace) **Do not add to global namespace**
@@ -146,10 +146,12 @@ Congrats, your GitLab database uses the right InnoDB tablespace format.
However, you must still ensure that any **future tables** created by GitLab will still use the right format:
- If `SELECT @@innodb_file_per_table` returned **1** previously, your server is running correctly.
> It's however a requirement to check *now* that this setting is indeed persisted in your [my.cnf](https://dev.mysql.com/doc/refman/5.7/en/tablespace-enabling.html) file!
> It's however a requirement to check *now* that this setting is indeed persisted in your [my.cnf](https://dev.mysql.com/doc/refman/5.7/en/tablespace-enabling.html) file!
- If `SELECT @@innodb_file_per_table` returned **0** previously, your server is not running correctly.
> [Enable innodb_file_per_table](https://dev.mysql.com/doc/refman/5.7/en/tablespace-enabling.html) by running in a MySQL session as root the command `SET GLOBAL innodb_file_per_table=1, innodb_file_format=Barracuda;` and persist the two settings in your [my.cnf](https://dev.mysql.com/doc/refman/5.7/en/tablespace-enabling.html) file
> [Enable innodb_file_per_table](https://dev.mysql.com/doc/refman/5.7/en/tablespace-enabling.html) by running in a MySQL session as root the command `SET GLOBAL innodb_file_per_table=1, innodb_file_format=Barracuda;` and persist the two settings in your [my.cnf](https://dev.mysql.com/doc/refman/5.7/en/tablespace-enabling.html) file
Now, if you have a **different result** returned by the 2 commands above, it means you have a **mix of tables format** uses in your GitLab database. This can happen if your MySQL server had different values for `innodb_file_per_table` in its life and you updated GitLab at different moments with those inconsistent values. So keep reading.
To enable the Microsoft Azure OAuth2 OmniAuth provider you must register your application with Azure. Azure will generate a client ID and secret key for you to use.
1. Sign in to the [Azure Management Portal](https://manage.windowsazure.com>).
1. Sign in to the [Azure Management Portal](https://manage.windowsazure.com).
1. Select "Active Directory" on the left and choose the directory you want to use to register GitLab.
