README.md

@@ -4,123 +4,10 @@ This is the source for the https://about.gitlab.com/ site. For a guide on how to
 ## Local development
-```sh
-bundle install
-
-bundle exec middleman
-```
-
-Once the Middleman server is running, you can visit
-[http://localhost:4567](http://localhost:4567) in your browser to see a live,
-local preview of the site. Any changes to files in the `source` directory will
-be detected automatically, and your browser will even reload the page if necessary.
-
-PDF files are not available in development mode. See below for more information.
-
-See the [Middleman docs](https://middlemanapp.com/basics/development_cycle/) for
-more information.
-
-### Enable livereloading
-
-When running middleman with the livereload option enabled, it watches your
-repo for changes and reloads the site automatically.
-
-Livereload can result to [slow server response times][gh-livereload], so it is
-disabled by default. That means you need to manually refresh the webpage if you
-make any changes to the source files. To enable it, just set the environment
-variable `ENABLE_LIVERELOAD=1` before running middleman:
-
-```
-ENABLE_LIVERELOAD=1 bundle exec middleman
-```
-
-You can verify that it's enabled from the following line:
-
-```
-== LiveReload accepting connections from ws://192.168.0.12:35729
-```
-
-To permanently have livereload enabled without typing the environment variable,
-just export its value in your shell's configuration file:
-
-```
-# Open your rc file (replace editor with vim, emacs, nano, atom, etc.)
-editor ~/.bashrc
-
-# Export the livereload variable
-export ENABLE_LIVERELOAD=1
-```
-
->**Note:**
-You need to logout and login in order for the changes to take effect. To
-temporarily use the changes, run `source ~/.bashrc`.
-
-Next time you login, livereload will be always enabled and you can just run
-`middleman` to start the local server to preview the changes.
+[Read how to preview any changes locally.](doc/development.md)
 ## Contributing
-### Blog posts
-
-Please read through the [Blog Handbook] before you begin.
-
-A new blog post likely needs to be reviewed by others before being published, so
-it's best to use our standard [feature branch workflow](http://docs.gitlab.com/ee/workflow/workflow.html)
-and to open a Merge Request. If you're not yet comfortable using the Git command
-line, you can [create a branch in the GitLab UI](http://docs.gitlab.com/ee/gitlab-basics/create-branch.html).
-
-Blog posts go in [`source/posts/`](./source/posts/) and **must be named to
-match the following format:** `yyyy-mm-dd-the-post-title.html.md`.
-
-Because the formatting of the filename is important and specific, it's best to
-generate the file for a new blog post interactively in your terminal by using
-the `new_post` Rake task:
-
-```shell
-bundle exec rake new_post
-```
-
-When prompted, enter the blog post title, _without a date_, and press
-<kbd>Enter</kbd>. A message will be printed to tell you the path to the new
-file.
-
-Open the file in your text editor of choice. The file will be empty except for a
-few lines at the top, surrounded by a pair of three hyphens (`---`). These lines
-are called [**Frontmatter**](https://middlemanapp.com/basics/frontmatter/).
-
-The `title` attribute has already been filled out by the `new_post` Rake task.
-Fill in the others as needed, or remove any that aren't applicable to your post
-(not every post needs an `image`, for example).
-
-If you need more fine-grained control over blog post ordering, or publication
-time, add a `date` attribute to the frontmatter with a UTC-based time. For
-example:
-
-```yaml
----
-title: "Example Blog Post"
-date: 2017-04-01 15:45
----
-```
-
-If no `date` attribute is supplied, it will be inferred from the filename.
-
-When adding timestamps to blog posts, **be warned:** setting it too far into the
-future will cause the post to not be published until that time has passed.
-Because builds are only triggered on new commits to `master`, you might set a
-blog post to publish in a few hours, but it might not be published for days if
-no one makes a new commit after that time has passed.
-
-When in doubt, either don't give it a timestamp, or set it to a time that has
-already passed.
-
-Fill in the post's content using [Markdown][mkd-guide]. To preview your post locally
-before publishing, see [**Local development**](#local-development) for
-instructions.
-
-[Blog Handbook]: https://about.gitlab.com/handbook/marketing/blog/
-[mkd-guide]: https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/
-
 ### Adding yourself to the team page
 Edit [`data/team.yml`](./data/team.yml) and add a new entry for yourself (or
@@ -134,55 +21,13 @@ Edit [`data/pets.yml`](./data/pets.yml) and add a new entry.
 Images should be uploaded to [`source/images/team/pets`](./source/images/team/pets).
-### Adding an application to the applications page
-
-#### Adding a new application
-
-Edit [`data/applications.yml`](./data/applications.yml) and add a new entry within
-the correct categories `applications` list.
-
-Please  add a `.png` image to [`source/images/applications/apps`](./source/images/applications/apps),
-the name of the image should be the same as the title, but with underscores instead of spaces.
-
-Example:
-
-```yaml
-...
-  - title: My new application
-    content: My new application description.
-    links:
-      - url: https://my-new-application.io
-        title: my-new-application.io
-      - ...
-...
-```
-
-The image should be located in `source/images/applications/apps/my_new_application.png`.
-
-The application `content` string will be truncated to 100 characters. Please do not include any HTML tags.
-
-The application `links` list will be truncated to 3 links.
-
-#### Adding a new category
-
-If you **need** to create a new category, you can do so.
-Please  add an `.svg` image to [`source/images/applications/categories`](./source/images/applications/categories),
-the name of the image should be the same as the category id, but with underscores instead of hyphens.
-Example:
-```yaml
-...
-- title: My new category
-  id: my-new-category
-  applications:
-    - ...
-    - ...
-...
-```
-
-The image should be located in `source/images/applications/categories/my_new_category.svg`.
+### Blog posts
+[Read how to add a blog post.](doc/blog-posts.md)
+### Adding an application to the applications page (under `/applications`)
+[How to add an application.](doc/applications.md)
 ### Updating the promotion link
@@ -192,317 +37,29 @@ versions or upcoming events.
 Edit [`data/promo.yml`](./data/promo.yml) to update the `link` and `text`
 properties.
-### Press releases page
-
-The [press releases] page follows the same principle like the [blog archives].
-It is automatically populated by the data fed into [`data/press.yml`](/data/press.yml).
-
-As you can see, there are three values, `title`, `link` and `date`. Here's a
-short explanation what each does.
-
-| Value | Description |
-| ----- | ----------- |
-| `title` | The headline of the article, make sure to include it inside double quotes and remove the trailing period if any. |
-| `link` | The URL that links back to the article. If a press release is hosted on our website, you must first create a blog post with the press release. Create it like any other blog post and make sure to include the `categories: press` in the [frontmatter]. The category is essential if you want the post to appear in the [press category]. That way we can have a list of press posts hosted on our website. |
-| `date` | The date should be in ISO format as stated in the handbooks's [Writing Style Guidelines][] (see bullet 4). Make sure to make this right as this value is used make the links listed in descending order (newest to oldest). |
-
-#### Create a new press release page under `/press/releases`
-
-There are two ways to create a new press release page that will be hosted under
-`/press/releases`. You can use the automatic way using the command line or
-edit the files manually with your text editor.
-
-#### Using the raketask to create a new press release page
-
-Assuming you have cloned the repository, you have Ruby installed and have ran
-`bundle install`, here are the steps needed to create a new press release page
-automatically:
-
-1. Go to the root directory of `www-gitlab-com`
-1. Create a new branch: `git checkout -b press-release-branch`
-1. Run the following:
-
-    ```
-    rake new_press
-    ```
-
-    You will be asked two questions, 1) the `date` of the press release in ISO
-    format, 2) the `title` of the press release.
-
-    These data will be used to automatically create a new file
-    `source/press/releases/{date}-{title}.html.md` and will also populate
-    `data/press.yml` with the right information.
-
-1. Add content to the new press release file according to our [Markdown guide][md].
-1. Add the changed files and commit the changes:
-
-    ```
-    git add data press
-    git commit -m "New press release"
-    git push origin press-release-branch
-    ```
-
-1. Create a new merge request.
-
-#### Manually create a new press release page
-
-You need to do 2 things:
-
-1. Create a new file under `source/press/releases/` with its filename ending
-   in `.html.md`. An example of such a page would be
-   `source/press/releases/2016-01-01-new-press-release.html.md`. Its contents
-   should always start with the following block:
-
-    ```
-    ---
-    layout: markdown_page
-    title: "New press release!"
-    ---
-    ```
-
-    The only thing you may change to your liking is the title. Leave everything
-    else as-is. Once you have created that block you may add the content
-    according to our [Markdown guide][md].
-
-1. Follow the steps outlined in the section [Add an internal URL to the press
-   releases archive manually](#add-an-internal-url-to-the-press-releases-archive-manually)
-
-#### Add an existing URL to the press releases archive using the raketask
-
-1. Go to the root directory of `www-gitlab-com`
-1. Create a new branch: `git checkout -b press-release-branch`
-1. Run the following:
-
-    ```
-    rake add_press
-    ```
-
-    You will be asked three questions, 1) the `date` of the press release in ISO
-    format, 2) the `title` of the press release, and 3) the URL of the press
-    release.
-
-    These data will be used to automatically populate `data/press.yml` with the
-    right information.
-
-1. Add the changed file and commit the changes:
-
-    ```
-    git add data
-    git commit -m "New press release"
-    git push origin press-release-branch
-    ```
-
-1. Create a new merge request.
-
-#### Add an existing URL to the press releases archive manually
-
-To add an existing URL under `about.gitlab.com` in the press releases page,
-follow the steps below:
-
-1. Open `data/press.yml` with an editor (do **not** use Microsoft Word).
-1. Copy paste the previous block leaving a newline between.
-1. Add your own `title`, `date` and `link`.
-1. Visit <http://localhost:4567/press/releases/> and make sure it appears in
-   the list.
-1. When ready, commit the changes, push to the repository and open a MR for
-   review.
-
-[frontmatter]: https://about.gitlab.com/handbook/marketing/blog/#frontmatter
-[Writing Style Guidelines]: https://about.gitlab.com/handbook/communication/#writing-style-guidelines
-[press releases]: https://about.gitlab.com/press/releases/
-[press category]: https://about.gitlab.com/blog/categories/press
-[blog archives]: https://about.gitlab.com/blog/archives.html
-[md]: https://about.gitlab.com/handbook/product/technical-writing/markdown-guide
-
 ### Update the features page (under `/features`)
-The feature page grabs its content automatically from the file
-`/data/features.yml`.
+[How to update the features page.](doc/features.md#update-the-features-page-under-features)
 ### Create or update the comparison pages (under `/comparison`)
-The [comparison page][comp] grabs its content automatically from
-`data/features.yml`.
-
-There are 3 files in total which you need to create or edit:
-
-- `data/features.yml`: Update for new comparisons. Comparisons are automatically generated from the contents of this file.
-- `source/comparison/gitlab-vs-competitor.html.haml`: Create for new comparisons.
-  Every comparison page has its own html file. **Use dashes**
-- `source/includes/comparison_table.html.haml`: Edit for new or existing
-  comparisons.
-
----
-
-**Step 1**
-
-Add a new yaml file named after the comparison using underscores:
-`data/comparisons/gitlab_vs_competitor.yml`. You can start by copying an
-existing one and then changing its content. Yaml files are sensitive to
-indentation, so be extra careful. Make sure that you follow the structure below:
-
-```yaml
-title: "Competitor vs GitLab"
-pdf: gitlab-vs-competitor.pdf
-competitor_one:
-  name: 'GitLab'
-  logo: '/images/comparison/gitlab-logo.svg'
-competitor_two:
-  name: 'Competitor'
-  logo: '/images/comparison/competitor-logo.svg'
-last_updated: 'May 5, 2017'
-features:
-  - title: "Briefly explain the feature"
-    description: |
-      Describe the differences in detail. This text can span in multiple
-      lines without interfering with its structure. It will always appear
-      as one paragraph.
-    link_description: "Learn more about Feature Name."
-    link: "link to GitLab's feature page documentation or blog post"
-    competitor_one: true
-    competitor_two: true
-```
-
-Notes:
-
-- Although the file is named with GitLab being first, the title should have the
-  competitor name first.
-- The `pdf` name should be similar to the yaml file name, but with dashes. In
-  short, it has to match the HTML page name in step 2. If you want to omit the
-  PDF link altogether, set its value to `null`, like: `pdf: 'null'`.
-- Remember to update the date every time you make a change.
-- The competitor's logo (`competitor_two`) can be `svg` or `png`. Save it in
-  `source/images/comparison/competitor-logo.svg`.
-- In the features area, `competitor_one` is always GitLab, and `competitor_two`
-  is the competitor we are compared against. Values for these two fields are
-  `true|false|sortof`.
-
-**Step 2**
-
-Add a new haml file named after the comparison using dashes:
-`source/comparison/gitlab-vs-competitor.html.haml`. You can start by copying an
-existing one and then editing it. The only change you need to make is the
-name of the yaml file you created above:
-
-```yaml
----
-layout: comparison_page
-trial_bar: true
-title: GitLab compared to other tools
-suppress_header: true
-image_title: '/images/comparison/title_image.png'
-extra_css:
-  - compared.css
-extra_js:
-  - comparison.js
----
-
-- data.features.gitlab_vs_competitor do |comparison_block|
-  = partial "includes/comparison_table", locals: { comparison_block: comparison_block }
-```
-
-**Step 3**
-
-As a last step, you need to add the new page in the dropdown menu. To do that,
-open `source/includes/comparison_table.html.haml` and add an entry of your newly
-added comparison page. Again, you can copy one of the entries you'll find inside
-and just change its content. Haml files are sensitive to indentation, so be
-extra careful:
-
-```haml
-%li
-  = highlight_active_nav_link("Competitor vs. GitLab", "/comparison/gitlab-vs-competitor.html#dropdown")
-```
-
-**Step 4**
-
-If you followed the above 3 steps, the new comparison page should be reachable
-under `/comparison/gitlab-vs-competitor.html` and you should see it in the
-dropdown menu. The last thing you need to do is create the PDF. Follow the
-info in [creating comparison PDFs](#comparison-pdfs).
-
-[comp]: https://about.gitlab.com/comparison/
+[How to update the comparison pages.](doc/features.md#create-or-update-the-comparison-pages-under-comparison)
 ### Update the release list page (under `/release-list`)
-The release list page grabs its content automatically by crawling the blog and
-retrieving the headers from the blog post.
-
-Edit `/generators/release_list.rb` and modify two elements:
-
-1. Add the new version to the table listing the versions
-    ```
-    VERSIONS = [
-      "8.11", "8.10", "8.9", "8.8", "8.7", "8.6", "8.5", "8.4", "8.3","8.2","8.1","8.0","7.14","7.13","7.12","7.11","7.10",
-      "7.9","7.8"
-    ]
-    ```
-
-2. Update the year and month according to the current date. Note that you should
-only indicate a month for which we already have a public blog post announcing the
-release. That means, if we are on Sept 19th and the next release scheduled for
-the 22th is 8.12, the month should be 8 (i.e August for 8.11), not 9.
-
-    ```
-    year = 2016
-    month = 8
-    ```
-
-3. Commit the changes.
-
-The release-list page will be updated after `bundle exec rake build`.
+[How to update the release list page.](doc/release-list.md)
 ### Update the projects page (under `/handbook/engineering/projects`)
-GitLab Engineering Projects page is generated using information stored in
-`data/projects.yml` and `data/team.yml` files. Edit these files to add a
-project and assign product owners / maintainers / reviewers.
-
-* Typically, product owner is a Product Team member whose responsibilities
-include having a vision of a project's development, scheduling a work and
-allocating required resources.
-
-* Maintainer is usually a team member who is responsible for the final review
-and has ability to merge changes into the `master` branch / default branch.
-
-* A reviewer is a team member who is responsible for reviewing changes and
-providing a quick feedback during multiple review iterations.
-
-To assign someone to a project it is necessary to add a `projects` section to
-team member's entry in `data/team.yml`. See an example below.
-
-```yaml
-- name: Full Name
-  locality: Some City
-  # [...]
-  gitlab: gitlab-com-handle
-  projects:
-    some-project: owner
-    gitlab-ce: maintainer backend
-    gitlab-ee: maintainer backend
-    gitlab-shell: reviewer
-  story: Bio that appears on the team page.
-```
-
-Note that each project, that user is involved in, is referenced by a key.
-The key needs to be defined in `data/projects.yml` as well.
-```yaml
-gitlab-ce:
-  name: GitLab Community Edition (CE)
-  path: gitlab-org/gitlab-ce
-  # [...]
-```
-If corresponding key does not exist in `data/projects.yml` then CI pipeline
-will fail and an appropriate RSpec failure will inform you which key is
-missing.
-Supported roles are only `owner`, `maintainer` and `reviewer`. A text provided
-after a role name is an arbitrary description, that will appear next to a
-team member's gitlab.com handle on a generated page.
-See [Engineering Projects Page](https://about.gitlab.com/handbook/engineering/projects) in the Handbook.
+[How to update the projects page.](doc/projects.md)
+### Press releases page
+[How to add a press release page.](doc/press.md)
+## PDF files
+[How to work with PDFs.](doc/pdf.md)
 ## Production build
@@ -520,109 +77,6 @@ bundle exec rake pdfs
 The above command builds the static files and PDFs into the folder `public`.
-## PDF files
-
-This site includes some dynamically generated PDF files. For example,
-`terms/print/gitlab_subscription_terms.pdf`. Each of these files is
-derived from a corresponding 'printable' HTML file, such as
-`terms/print/gitlab_subscription_terms.html`.
-
-The PDF files are generated by [pandoc](http://pandoc.org/) using
-[LaTeX/XeTeX](http://xetex.sourceforge.net/). Global PDF parameters such
-as page margins are configured in `pdf_template.tex`.
-
-### Install PDF dependencies
-
-There are two kinds of PDFs created: the comparison pages ones and all the others.
-
----
-
-For the comparison PDFs you will need to install [wkhtmltopdf].
-
-On macOS:
-
-```
-brew cask install wkhtmltopdf
-```
-
----
-
-For all the others you need [pandoc](http://pandoc.org/installing.html). On
-macOS run:
-
-```
-brew install pandoc
-```
-
-Then, install [Basic TeX](https://tug.org/mactex/morepackages.html).
-
-[wkhtmltopdf]: https://wkhtmltopdf.org/downloads.html
-
-### PDF development
-
-You can tweak the 'printable HTML' files in Middleman's development
-mode if you enter the correct URL in your browser (e.g.
-`http://localhost:4567/terms/print/gitlab_subscription_terms.html`).
-If you want to tweak pdf_template.tex run `rake build` once, and
-`rake pdfs` as often as needed.
-
-If you want to tweak the source HAML/Markdown/HTML and see the changes
-in the final PDF you have to run `rake build pdfs` after each source
-change.
-
-To remove the generated PDFs run:
-
-```
-rake rm_pdfs
-```
-
-### Add a new PDF file
-
-In order to make a page be saved as pdf at a location reachable through the
-website, you have to:
-
-1. Open [Rakefile](./Rakefile) with your editor and add the location of the
-   generated PDF file (prepend with `public/`) under the `PDFS = %w{` section.
-   Save the file and exit.
-
-1. Make sure the file exists locally in the location you chose the pdf to be
-   saved. For example, a page in `source/my-page/page.html.haml` should have an
-   entry of `public/my-page/page.pdf` in the `Rakefile` (previous step).
-
-1. The file to be printed must have the `print` layout set in the yaml frontmatter.
-   For example:
-
-    ```
-    ---
-    layout: print
-    title: "The title of the page"
-    ---
-    ```
-
-### Comparison PDFs
-
->**Notes:**
-- Before creating the PDF for a new comparison page, you need to have
-  [created the page](#create-or-update-the-comparison-pages-under-comparison)
-  beforehand.
-- Make sure you have all [PDF dependencies installed](#install-pdf-dependencies).
-
-The comparison PDFs are generated in a slightly different way and require a
-different command to be run. Before the PDFs can be generated the website
-needs to be built locally by running the following:
-
-```
-bundle exec middleman build
-```
-
-After running that you can now run the following to generate the PDFs:
-
-```
-bundle exec rake comparison_pdfs
-```
-
-Once you have done that you are free to commit and push these to GitLab.com.
-
 ## Custom Generators
 There are a few custom, static generators specified in `config.rb`. For

data/applications.yml

@@ -396,6 +396,11 @@
       links:
         - url: /features/gitlab-ci-cd/
           title: GitLab CI
+    - title: Bitrise
+      content: Hosted Continuous Integration and Delivery service for mobile apps. Craft powerful workflows to automate build, testing, deployment and feedback cycles to have more time for actual coding, while having constant overview about the state of your app.
+      links:
+        - url: https://www.bitrise.io
+          title: Bitrise.io
     - title: BuildKite
       content: BuildKite runs builds on GitLab commits, either on self-hosted GitLab repositories or GitLab.com.
       links:
@@ -440,7 +445,7 @@
         - url: https://www.buddybuild.com/blog/buddybuild-gitlab-integration
           title: buddybuild
     - title: Terraform
-      content: HashiCorp Terraform Enterprise provides integration with version control systems (VCS) to facilitate collaboration on infrastructure as code. 
+      content: HashiCorp Terraform Enterprise provides integration with version control systems (VCS) to facilitate collaboration on infrastructure as code.
       links:
         - url: https://www.hashicorp.com/blog/announcing-terraform-enterprise-integration-for-gitlab/
           title: Terraform

data/team.yml

@@ -1302,12 +1302,18 @@
   role: <a href="https://about.gitlab.com/jobs/frontend-engineer/">Frontend Engineer</a>
   reports_to: Frontend DC Lead
   picture: bryce-johnson.jpg
-  twitter:
   gitlab: brycepj
+  projects:
+    gitlab-ce: reviewer frontend
+    gitlab-ee: reviewer frontend
   expertise: |
              <li><a href="https://docs.gitlab.com/ee/workflow/time_tracking.html">Time Tracking <a href="/jobs/expert/">expert</a></li>
   story:  |
-    Bryce's primary addictions are programming in JavaScript and adding to his .vimrc file. Before discovering code in 2011, he wrote content for websites and advertisements you most assuredly never read, and now puts his writing skills to good use obsessing about variable names. Outside of code, Bryce enjoys hanging out with his wife and their two cats, playing ping pong, hiking in the Blue Ridge mountains, and trying out new pizza restaurants.
+    Bryce's primary addictions are programming in JavaScript and adding to his .vimrc file. Before 
+    discovering code in 2011, he wrote content for websites and advertisements you most assuredly 
+    never read, and now puts his writing skills to use obsessing about variable names. Outside 
+    of work, Bryce enjoys hanging out with his wife, daughter, and their two cats, playing ping pong, 
+    hiking in the Blue Ridge mountains, and trying out new pizza restaurants.
 - name: Mike Greiling
   locality: Minneapolis, MN
@@ -1439,8 +1445,8 @@
 - name: Elsje Smart
   locality: Marazion
   country: United Kingdom
-  role: <a href="https://about.gitlab.com/jobs/business-development-representative/">Business Development Representative</a>
-  reports_to: BDR Manager
+  role: <a href="https://about.gitlab.com/jobs/sales-development-representative/">Sales Development Representative</a>
+  reports_to: Sales Development Representative Lead
   picture: elsje.jpg
   twitter:
   gitlab: elsje

doc/applications.md

+# Adding a new application to `/applications`
+
+Edit [`data/applications.yml`](../data/applications.yml) and add a new entry within
+the correct categories `applications` list.
+
+Please  add a `.png` image to [`source/images/applications/apps`](../source/images/applications/apps),
+the name of the image should be the same as the title, but with underscores instead of spaces.
+
+Example:
+
+```yaml
+...
+  - title: My new application
+    content: My new application description.
+    links:
+      - url: https://my-new-application.io
+        title: my-new-application.io
+      - ...
+...
+```
+
+- The image should be located in `source/images/applications/apps/my_new_application.png`.
+- The application `content` string will be truncated to 100 characters. Please do not include any HTML tags.
+- The application `links` list will be truncated to 3 links.
+
+## Adding a new category
+
+If you **need** to create a new category, you can do so.
+
+Please  add an `.svg` image to [`source/images/applications/categories`](../source/images/applications/categories),
+the name of the image should be the same as the category id, but with underscores instead of hyphens.
+
+Example:
+
+```yaml
+...
+- title: My new category
+  id: my-new-category
+  applications:
+    - ...
+    - ...
+...
+```
+
+The image should be located in `source/images/applications/categories/my_new_category.svg`.

doc/blog-posts.md

+# Adding a blog post
+
+Please read through the [Blog Handbook] before you begin.
+
+A new blog post likely needs to be reviewed by others before being published, so
+it's best to use our standard [feature branch workflow](http://docs.gitlab.com/ee/workflow/workflow.html)
+and to open a Merge Request. If you're not yet comfortable using the Git command
+line, you can [create a branch in the GitLab UI](http://docs.gitlab.com/ee/gitlab-basics/create-branch.html).
+
+Blog posts go in [`source/posts/`](./source/posts/) and **must be named to
+match the following format:** `yyyy-mm-dd-the-post-title.html.md`.
+
+Because the formatting of the filename is important and specific, it's best to
+generate the file for a new blog post interactively in your terminal by using
+the `new_post` Rake task:
+
+```shell
+bundle exec rake new_post
+```
+
+When prompted, enter the blog post title, _without a date_, and press
+<kbd>Enter</kbd>. A message will be printed to tell you the path to the new
+file.
+
+Open the file in your text editor of choice. The file will be empty except for a
+few lines at the top, surrounded by a pair of three hyphens (`---`). These lines
+are called [**Frontmatter**](https://middlemanapp.com/basics/frontmatter/).
+
+The `title` attribute has already been filled out by the `new_post` Rake task.
+Fill in the others as needed, or remove any that aren't applicable to your post
+(not every post needs an `image`, for example).
+
+If you need more fine-grained control over blog post ordering, or publication
+time, add a `date` attribute to the frontmatter with a UTC-based time. For
+example:
+
+```yaml
+---
+title: "Example Blog Post"
+date: 2017-04-01 15:45
+---
+```
+
+If no `date` attribute is supplied, it will be inferred from the filename.
+
+When adding timestamps to blog posts, **be warned:** setting it too far into the
+future will cause the post to not be published until that time has passed.
+Because builds are only triggered on new commits to `master`, you might set a
+blog post to publish in a few hours, but it might not be published for days if
+no one makes a new commit after that time has passed.
+
+When in doubt, either don't give it a timestamp, or set it to a time that has
+already passed.
+
+Fill in the post's content using [Markdown][mkd-guide]. To preview your post locally
+before publishing, see [**Local development**](local-development.md) for
+instructions.
+
+[Blog Handbook]: https://about.gitlab.com/handbook/marketing/blog/
+[mkd-guide]: https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/

doc/development.md

+# Local development
+
+```sh
+bundle install
+
+bundle exec middleman
+```
+
+Once the Middleman server is running, you can visit
+[http://localhost:4567](http://localhost:4567) in your browser to see a live,
+local preview of the site. Any changes to files in the `source` directory will
+be detected automatically, and your browser will even reload the page if necessary.
+
+PDF files are not available in development mode. See below for more information.
+
+See the [Middleman docs](https://middlemanapp.com/basics/development_cycle/) for
+more information.
+
+## Enable livereloading
+
+When running middleman with the livereload option enabled, it watches your
+repo for changes and reloads the site automatically.
+
+Livereload can result to [slow server response times][gh-livereload], so it is
+disabled by default. That means you need to manually refresh the webpage if you
+make any changes to the source files. To enable it, just set the environment
+variable `ENABLE_LIVERELOAD=1` before running middleman:
+
+```
+ENABLE_LIVERELOAD=1 bundle exec middleman
+```
+
+You can verify that it's enabled from the following line:
+
+```
+== LiveReload accepting connections from ws://192.168.0.12:35729
+```
+
+To permanently have livereload enabled without typing the environment variable,
+just export its value in your shell's configuration file:
+
+```
+# Open your rc file (replace editor with vim, emacs, nano, atom, etc.)
+editor ~/.bashrc
+
+# Export the livereload variable
+export ENABLE_LIVERELOAD=1
+```
+
+>**Note:**
+You need to logout and login in order for the changes to take effect. To
+temporarily use the changes, run `source ~/.bashrc`.

doc/features.md

+# Update the features
+
+## Update the features page (under `/features`)
+
+The feature page grabs its content automatically from the file
+[`/data/features.yml`](/data/features.yml).
+
+The minimal info required to add a new feature is:
+
+```yaml
+  - title: "Distinct feature name"
+    description: "Feature description"
+    screenshot_url: "images/feature_page/screenshots/09-gitlab-ci.png"
+    link_description: "Learn more about feature name"
+    link: link to docs or feature page
+    feature_page: true
+    gitlab_com: true
+    gitlab_ce: true
+    gitlab_ees: true
+    gitlab_eep: true
+```
+
+## Create or update the comparison pages (under `/comparison`)
+
+The [comparison page][comp] grabs its content automatically from
+`data/features.yml`.
+
+There are 3 files in total which you need to create or edit:
+
+- `data/features.yml`: Update for new comparisons. Comparisons are automatically generated from the contents of this file.
+- `source/comparison/gitlab-vs-competitor.html.haml`: Create for new comparisons.
+  Every comparison page has its own html file. **Use dashes**
+- `source/includes/comparison_table.html.haml`: Edit for new or existing
+  comparisons.
+
+---
+
+**Step 1**
+
+Add a new yaml file named after the comparison using underscores:
+`data/comparisons/gitlab_vs_competitor.yml`. You can start by copying an
+existing one and then changing its content. Yaml files are sensitive to
+indentation, so be extra careful. Make sure that you follow the structure below:
+
+```yaml
+title: "Competitor vs GitLab"
+pdf: gitlab-vs-competitor.pdf
+competitor_one:
+  name: 'GitLab'
+  logo: '/images/comparison/gitlab-logo.svg'
+competitor_two:
+  name: 'Competitor'
+  logo: '/images/comparison/competitor-logo.svg'
+last_updated: 'May 5, 2017'
+features:
+  - title: "Briefly explain the feature"
+    description: |
+      Describe the differences in detail. This text can span in multiple
+      lines without interfering with its structure. It will always appear
+      as one paragraph.
+    link_description: "Learn more about Feature Name."
+    link: "link to GitLab's feature page documentation or blog post"
+    competitor_one: true
+    competitor_two: true
+```
+
+Notes:
+
+- Although the file is named with GitLab being first, the title should have the
+  competitor name first.
+- The `pdf` name should be similar to the yaml file name, but with dashes. In
+  short, it has to match the HTML page name in step 2. If you want to omit the
+  PDF link altogether, set its value to `null`, like: `pdf: 'null'`.
+- Remember to update the date every time you make a change.
+- The competitor's logo (`competitor_two`) can be `svg` or `png`. Save it in
+  `source/images/comparison/competitor-logo.svg`.
+- In the features area, `competitor_one` is always GitLab, and `competitor_two`
+  is the competitor we are compared against. Values for these two fields are
+  `true|false|sortof`.
+
+**Step 2**
+
+Add a new haml file named after the comparison using dashes:
+`source/comparison/gitlab-vs-competitor.html.haml`. You can start by copying an
+existing one and then editing it. The only change you need to make is the
+name of the yaml file you created above:
+
+```yaml
+---
+layout: comparison_page
+trial_bar: true
+title: GitLab compared to other tools
+suppress_header: true
+image_title: '/images/comparison/title_image.png'
+extra_css:
+  - compared.css
+extra_js:
+  - comparison.js
+---
+
+- data.features.gitlab_vs_competitor do |comparison_block|
+  = partial "includes/comparison_table", locals: { comparison_block: comparison_block }
+```
+
+**Step 3**
+
+As a last step, you need to add the new page in the dropdown menu. To do that,
+open `source/includes/comparison_table.html.haml` and add an entry of your newly
+added comparison page. Again, you can copy one of the entries you'll find inside
+and just change its content. Haml files are sensitive to indentation, so be
+extra careful:
+
+```haml
+%li
+  = highlight_active_nav_link("Competitor vs. GitLab", "/comparison/gitlab-vs-competitor.html#dropdown")
+```
+
+**Step 4**
+
+If you followed the above 3 steps, the new comparison page should be reachable
+under `/comparison/gitlab-vs-competitor.html` and you should see it in the
+dropdown menu. The last thing you need to do is create the PDF. Follow the
+info in [creating comparison PDFs](#comparison-pdfs).
+
+[comp]: https://about.gitlab.com/comparison/
+
+## Update the gitlab-com features (under `/gitlab-com`)
+

doc/pdf.md

+# PDF files
+
+This site includes some dynamically generated PDF files. For example,
+`terms/print/gitlab_subscription_terms.pdf`. Each of these files is
+derived from a corresponding 'printable' HTML file, such as
+`terms/print/gitlab_subscription_terms.html`.
+
+The PDF files are generated by [pandoc](http://pandoc.org/) using
+[LaTeX/XeTeX](http://xetex.sourceforge.net/). Global PDF parameters such
+as page margins are configured in `pdf_template.tex`.
+
+## Install PDF dependencies
+
+There are two kinds of PDFs created: the comparison pages ones and all the others.
+
+---
+
+For the comparison PDFs you will need to install [wkhtmltopdf].
+
+On macOS:
+
+```
+brew cask install wkhtmltopdf
+```
+
+---
+
+For all the others you need [pandoc](http://pandoc.org/installing.html). On
+macOS run:
+
+```
+brew install pandoc
+```
+
+Then, install [Basic TeX](https://tug.org/mactex/morepackages.html).
+
+[wkhtmltopdf]: https://wkhtmltopdf.org/downloads.html
+
+## PDF development
+
+You can tweak the 'printable HTML' files in Middleman's development
+mode if you enter the correct URL in your browser (e.g.
+`http://localhost:4567/terms/print/gitlab_subscription_terms.html`).
+If you want to tweak pdf_template.tex run `rake build` once, and
+`rake pdfs` as often as needed.
+
+If you want to tweak the source HAML/Markdown/HTML and see the changes
+in the final PDF you have to run `rake build pdfs` after each source
+change.
+
+To remove the generated PDFs run:
+
+```
+rake rm_pdfs
+```
+
+## Add a new PDF file
+
+In order to make a page be saved as pdf at a location reachable through the
+website, you have to:
+
+1. Open [Rakefile](/Rakefile) with your editor and add the location of the
+   generated PDF file (prepend with `public/`) under the `PDFS = %w{` section.
+   Save the file and exit.
+
+1. Make sure the file exists locally in the location you chose the pdf to be
+   saved. For example, a page in `source/my-page/page.html.haml` should have an
+   entry of `public/my-page/page.pdf` in the `Rakefile` (previous step).
+
+1. The file to be printed must have the `print` layout set in the yaml frontmatter.
+   For example:
+
+    ```
+    ---
+    layout: print
+    title: "The title of the page"
+    ---
+    ```
+
+## Comparison PDFs
+
+>**Notes:**
+- Before creating the PDF for a new comparison page, you need to have
+  [created the page](features.md#create-or-update-the-comparison-pages-under-comparison)
+  beforehand.
+- Make sure you have all [PDF dependencies installed](#install-pdf-dependencies).
+
+The comparison PDFs are generated in a slightly different way and require a
+different command to be run. Before the PDFs can be generated the website
+needs to be built locally by running the following:
+
+```
+bundle exec middleman build
+```
+
+After running that you can now run the following to generate the PDFs:
+
+```
+bundle exec rake comparison_pdfs
+```
+
+Once you have done that you are free to commit and push these to GitLab.com.

doc/press.md

+# Adding a press release page
+
+The [press releases] page follows the same principle like the [blog archives].
+It is automatically populated by the data fed into [`data/press.yml`](/data/press.yml).
+
+As you can see, there are three values, `title`, `link` and `date`. Here's a
+short explanation what each does.
+
+| Value | Description |
+| ----- | ----------- |
+| `title` | The headline of the article, make sure to include it inside double quotes and remove the trailing period if any. |
+| `link` | The URL that links back to the article. If a press release is hosted on our website, you must first create a blog post with the press release. Create it like any other blog post and make sure to include the `categories: press` in the [frontmatter]. The category is essential if you want the post to appear in the [press category]. That way we can have a list of press posts hosted on our website. |
+| `date` | The date should be in ISO format as stated in the handbooks's [Writing Style Guidelines][] (see bullet 4). Make sure to make this right as this value is used make the links listed in descending order (newest to oldest). |
+
+## Create a new press release page under `/press/releases`
+
+There are two ways to create a new press release page that will be hosted under
+`/press/releases`. You can use the automatic way using the command line or
+edit the files manually with your text editor.
+
+### Using the raketask to create a new press release page
+
+Assuming you have cloned the repository, you have Ruby installed and have ran
+`bundle install`, here are the steps needed to create a new press release page
+automatically:
+
+1. Go to the root directory of `www-gitlab-com`
+1. Create a new branch: `git checkout -b press-release-branch`
+1. Run the following:
+
+    ```
+    rake new_press
+    ```
+
+    You will be asked two questions, 1) the `date` of the press release in ISO
+    format, 2) the `title` of the press release.
+
+    These data will be used to automatically create a new file
+    `source/press/releases/{date}-{title}.html.md` and will also populate
+    `data/press.yml` with the right information.
+
+1. Add content to the new press release file according to our [Markdown guide][md].
+1. Add the changed files and commit the changes:
+
+    ```
+    git add data press
+    git commit -m "New press release"
+    git push origin press-release-branch
+    ```
+
+1. Create a new merge request.
+
+### Manually create a new press release page
+
+You need to do 2 things:
+
+1. Create a new file under `source/press/releases/` with its filename ending
+   in `.html.md`. An example of such a page would be
+   `source/press/releases/2016-01-01-new-press-release.html.md`. Its contents
+   should always start with the following block:
+
+    ```
+    ---
+    layout: markdown_page
+    title: "New press release!"
+    ---
+    ```
+
+    The only thing you may change to your liking is the title. Leave everything
+    else as-is. Once you have created that block you may add the content
+    according to our [Markdown guide][md].
+
+1. Follow the steps outlined in the section [Add an internal URL to the press
+   releases archive manually](#add-an-internal-url-to-the-press-releases-archive-manually)
+
+## Add an existing URL to the press releases archive using the raketask
+
+1. Go to the root directory of `www-gitlab-com`
+1. Create a new branch: `git checkout -b press-release-branch`
+1. Run the following:
+
+    ```
+    rake add_press
+    ```
+
+    You will be asked three questions, 1) the `date` of the press release in ISO
+    format, 2) the `title` of the press release, and 3) the URL of the press
+    release.
+
+    These data will be used to automatically populate `data/press.yml` with the
+    right information.
+
+1. Add the changed file and commit the changes:
+
+    ```
+    git add data
+    git commit -m "New press release"
+    git push origin press-release-branch
+    ```
+
+1. Create a new merge request.
+
+## Add an existing URL to the press releases archive manually
+
+To add an existing URL under `about.gitlab.com` in the press releases page,
+follow the steps below:
+
+1. Open `data/press.yml` with an editor (do **not** use Microsoft Word).
+1. Copy paste the previous block leaving a newline between.
+1. Add your own `title`, `date` and `link`.
+1. Visit <http://localhost:4567/press/releases/> and make sure it appears in
+   the list.
+1. When ready, commit the changes, push to the repository and open a MR for
+   review.
+
+[frontmatter]: https://about.gitlab.com/handbook/marketing/blog/#frontmatter
+[Writing Style Guidelines]: https://about.gitlab.com/handbook/communication/#writing-style-guidelines
+[press releases]: https://about.gitlab.com/press/releases/
+[press category]: https://about.gitlab.com/blog/categories/press
+[blog archives]: https://about.gitlab.com/blog/archives.html
+[md]: https://about.gitlab.com/handbook/product/technical-writing/markdown-guide

doc/projects.md

+# Update the projects page (under `/handbook/engineering/projects`)
+
+GitLab Engineering Projects page is generated using information stored in
+`data/projects.yml` and `data/team.yml` files. Edit these files to add a
+project and assign product owners / maintainers / reviewers.
+
+* Typically, product owner is a Product Team member whose responsibilities
+include having a vision of a project's development, scheduling a work and
+allocating required resources.
+
+* Maintainer is usually a team member who is responsible for the final review
+and has ability to merge changes into the `master` branch / default branch.
+
+* A reviewer is a team member who is responsible for reviewing changes and
+providing a quick feedback during multiple review iterations.
+
+To assign someone to a project it is necessary to add a `projects` section to
+team member's entry in `data/team.yml`. See an example below.
+
+```yaml
+- name: Full Name
+  locality: Some City
+  # [...]
+  gitlab: gitlab-com-handle
+  projects:
+    some-project: owner
+    gitlab-ce: maintainer backend
+    gitlab-ee: maintainer backend
+    gitlab-shell: reviewer
+  story: Bio that appears on the team page.
+```
+
+Note that each project, that user is involved in, is referenced by a key.
+The key needs to be defined in `data/projects.yml` as well.
+
+```yaml
+gitlab-ce:
+  name: GitLab Community Edition (CE)
+  path: gitlab-org/gitlab-ce
+  # [...]
+```
+
+If corresponding key does not exist in `data/projects.yml` then CI pipeline
+will fail and an appropriate RSpec failure will inform you which key is
+missing.
+
+Supported roles are only `owner`, `maintainer` and `reviewer`. A text provided
+after a role name is an arbitrary description, that will appear next to a
+team member's gitlab.com handle on a generated page.
+
+See [Engineering Projects Page](https://about.gitlab.com/handbook/engineering/projects) in the Handbook.

doc/release-list.md

+# Update the release list page (under `/release-list`)
+
+The release list page grabs its content automatically by crawling the blog and
+retrieving the headers from the blog post.
+
+Edit `/generators/release_list.rb` and modify two elements:
+
+1. Add the new version to the table listing the versions
+    ```
+    VERSIONS = [
+      "8.11", "8.10", "8.9", "8.8", "8.7", "8.6", "8.5", "8.4", "8.3","8.2","8.1","8.0","7.14","7.13","7.12","7.11","7.10",
+      "7.9","7.8"
+    ]
+    ```
+
+2. Update the year and month according to the current date. Note that you should
+only indicate a month for which we already have a public blog post announcing the
+release. That means, if we are on Sept 19th and the next release scheduled for
+the 22th is 8.12, the month should be 8 (i.e August for 8.11), not 9.
+
+    ```
+    year = 2016
+    month = 8
+    ```
+
+3. Commit the changes.
+
+The release-list page will be updated after `bundle exec rake build`.

generators/direction.rb

@@ -58,7 +58,7 @@ class GitLabProject
    def tier_issues(tier)
      result = @instance.call("/projects/#{@id}/issues", "?labels=direction,#{tier}&state=opened&per_page=100&sort=asc")
-     result = result.select { |issue| issue["milestone"] && issue["milestone"]["due_date"] }
+     #result = result.select { |issue| issue["milestone"] && issue["milestone"]["due_date"] }
    end
    def name
@@ -89,7 +89,7 @@ end
 def tier_bullet(issue)
   output = "- [#{issue["title"]}](#{issue["web_url"]})"
-  output << " <kbd>#{issue["milestone"]["title"]}</kbd>"
+  output << " <kbd>#{issue["milestone"]["title"]}</kbd>" if issue["milestone"]
   output << "\n"
   output
 end
@@ -103,14 +103,11 @@ def generate_direction
     milestones = project.milestones
     milestones.each do |ms|
-      print ms["title"]
       if ms["due_date"] && Date.parse(ms["due_date"]) >= Date.today
         issues += project.milestone_direction_issues(ms["title"])
       end
     end
   end
-  print issues[0]
-  print issues.group_by{|issue| issue["milestone"]["title"]}.keys
   issues.group_by{|issue| issue["milestone"]["title"]}.each do |title, group|
     direction_output << "#### #{title} \n\n"
@@ -160,7 +157,11 @@ def tier_list(label)
     issues += project.tier_issues(label)
   end
   issues.sort_by! do |issue|
-    Date.parse issue["milestone"]["due_date"]
+    if issue["milestone"] && issue["milestone"]["due_date"]
+      Date.parse issue["milestone"]["due_date"]
+    else
+      Date.new(2050,1,1)
+    end
   end
   issues.each do |issue|
     output << tier_bullet(issue)

source/about/index.html.md

@@ -3,6 +3,9 @@ layout: markdown_page
 title: About Us
 ---
+- TOC
+{:toc}
+
 ## GitLab Inc.
 GitLab Inc. is a company based on the [GitLab open-source project](https://gitlab.com/gitlab-org/gitlab-ce/).
@@ -105,7 +108,8 @@ We promise that:
 ### What features are EE only
-When we make new features we ask ourselves, is this feature **more relevant for organizations that have more than 100 potential users**?
+If the wider community contributes a new feature they get to choose if it goes into CE or EE by sending the merge request to the repository they prefer (most go to CE). If the wider community contributes a feature already in EE to CE we use the process linked in [Contributing an EE only feature to CE
+](#contributing-an-ee-only-feature-to-ce). When GitLab Inc. makes a new features we ask ourselves, is this feature **more relevant for organizations that have more than 100 potential users**?
 If the answer is yes the feature is likely to be exclusive to EE.
 There are no features that are only useful to larger organizations, so for every EE features there will be smaller organizations that also need it. We're not saying that there are no small organizations that need the EE feature, just that we think that larger organizations are more likely to need it.
@@ -178,17 +182,12 @@ If you have time to give please help spread the word about GitLab by mentioning
 If you would like to give money please <a href="http://railsgirlssummerofcode.org/campaign/">donate to Rails Girls Summer of Code</a> in our name.
 ## Location
-GitLab is a community project with people participating from all over the world.
-GitLab Inc. has people in three continents to serve our customers better.
-Most of our customers are in the United States.
-
-Most of our team is distributed. We're proud to be [working remotely](https://about.gitlab.com/2014/07/03/how-gitlab-works-remotely/),
-using GitLab Issues to coordinate. We have a [Remote Manifesto](https://about.gitlab.com/2015/04/08/the-remote-manifesto/),
-our team members have shared their [experiences](https://about.gitlab.com/2015/06/17/highlights-to-my-first-remote-job/)
-in our blog and did a Q&A for [Remote.co](https://remote.co/company/gitlab/). You can taste a bit of the GitLab team culture by visiting
+GitLab is an open source project with [more than 1500 people](http://contributors.gitlab.com/) contributing from all over the world.
+GitLab Inc. has people in [more than 35 countries](https://about.gitlab.com/team/).
+We're proud to be [remote only](http://www.remoteonly.org/).
+You can taste a bit of the GitLab team culture by visiting
 our <a href="https://about.gitlab.com/culture/">culture page</a>.
-
 [This commit]: https://gitlab.com/gitlab-org/gitlab-ce/commit/0f43e98ef8c2da8908b1107f75b67cda2572c2c4
 [first version of GitLab CI]: https://gitlab.com/gitlab-org/gitlab-ci/commit/52cd500ee64a4a82b9ff6752ee85028cd419fcbe
 [GitLab Enterprise Edition]: https://about.gitlab.com/2013/08/22/introducing-gitlab-6-0-enterprise-edition/

source/handbook/engineering/index.html.md

@@ -28,9 +28,10 @@ GitLab consists of many subprojects. A curated list of GitLab Repositories
 can be found at the [GitLab Engineering Projects](/handbook/engineering/projects) page.
 When adding a repository please follow these steps:
+1. Ensure the project is under the gitlab-org namespace for anything related to the application or gitlab-com for anything strictly company related.
 1. [Add the project to the list of GitLab Repositories](https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/README.md#update-the-projects-page-under-handbookengineeringprojects)
-1. Add MIT license to the repository. See [MIT License Example] (https://gitlab.com/gitlab-org/gitlab-ce/blob/master/LICENSE).
-1. Add Contribution Guide. See [Contribution Example] (https://gitlab.com/gitlab-org/gitlab-ce/blob/master/CONTRIBUTING.md).
+1. Add MIT license to the repository. See [MIT License Example](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/LICENSE).
+1. Add Contribution Guide. See [Contribution Example](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/CONTRIBUTING.md).
 ## Engineering Groups

source/handbook/engineering/performance/index.html.md

@@ -160,6 +160,51 @@ revision, new revision, and ref (e.g. tag or branch) name.
 1. Sidekiq updates PostgreSQL
 1. Unicorn can now query PostgreSQL.
+
+## Availability and Performance Priority Labels
+{: #performance-labels}
+
+To clarify the priority of issues that relate to GitLab.com's availability and
+performance consider adding an _Availability and Performance Priority Label_,
+`~AP1` through `~AP3`. This is similar to what is in use in the Support and
+Security teams, they use `~SP` and `~SL` labels respectively to indicate
+priority.
+
+Use the following as a guideline to determine which Availability and Performance
+Priority label to use for bugs and feature proposals. Consider the _likelihood_
+and _urgency_  of the "scenario" that could result from this issue (not) being
+resolved.
+
+- **Urgency:**  _Examples_
+ - U1
+    - Outage likely within a month.
+    - Affects many team members and/or many GitLab.com users
+ - U2
+    - Outage likely within three months.
+    - Affects some team members and/or a few GitLab.com users
+ - U3
+    - Outage can happen, but not likely in next three months.
+    - Affects some team members but no GitLab.com users
+
+- **Impact:** _Examples_
+ - I1
+    - Outage of >= 25 minutes.
+    - Performance improvement (or avoiding degradation) of >= 100 ms expected.
+ - I2
+    - Outage of 5 - 25 minutes.
+    - Performance improvement (or avoiding degradation) of 10-100 ms expected.
+ - I3
+    - Outage of 0 - 5 minutes.
+    - Performance improvement (or avoiding degradation) of <= 10 ms expected.
+
+
+| **Urgency \ Impact**          | **I1 - High** | **I2 - Medium**  | **I3 - Low**   |
+|----------------------------|---------------|------------------|----------------|
+| **U1 - High**              | `AP1`         | `AP1`            | `AP2`          |
+| **U2 - Medium**            | `AP1`         | `AP2`            | `AP3`          |
+| **U3 - Low**               | `AP2`         | `AP3`            | `AP3`          |
+
+
 ## Database Performance
 Some general notes about parameters that affect database performance, at a very

source/handbook/infrastructure/index.html.md

@@ -28,6 +28,7 @@ title: "Infrastructure"
 - [GitLab.com architecture](production-architecture/)
 - [Monitoring GitLab.com](monitoring/)
+- [Performance of GitLab.com](/handbook/engineering/performance)
 - [Database team handbook](database/)
 - [Gitaly team handbook](gitaly/)
 - [Production team handbook](production/)
@@ -46,7 +47,7 @@ infrastructure team works on
      is in fact the first issue in the gitlab-ce issue tracker; for more on
      pingdom see the [monitoring page](/handbook/infrastructure/monitoring/)),
      measured per calendar month, and as recorded on
-      [pingdom](http://stats.pingdom.com/81vpf8jyr1h9/1902794/history). 
+      [pingdom](http://stats.pingdom.com/81vpf8jyr1h9/1902794/history).
 1. GitLab.com's performance.
    - Current goal: [99% of user requests < 1 second](https://performance.gitlab.net/dashboard/db/transaction-overview?panelId=2&fullscreen&orgId=1)
    - Latency here is _currently_ measured via the "Transaction Timings"
@@ -270,6 +271,7 @@ in the invite, or get in touch in the production chat channel to ask.
 Any team or individual can initiate a change to GitLab.com by following this checklist. Create an issue in the infrastructure [issue
  tracker](https://gitlab.com/gitlab-com/infrastructure/issues) and select the `change_checklist` template
+
 ## Make GitLab.com settings the default
 As said in the [production engineer job description](jobs/production-engineer/index.html)