.gitlab-ci.yml

@@ -62,7 +62,7 @@ review:
   dependencies:
     - build_branch
   variables:
-    GIT_STRATEGY: none
+    GIT_STRATEGY: fetch
   script:
     - rsync -avz --delete public ~/pages/$CI_COMMIT_REF_SLUG
   environment:
@@ -103,7 +103,7 @@ deploy:
   stage: deploy
   cache: {}
   variables:
-    GIT_STRATEGY: none
+    GIT_STRATEGY: fetch
   dependencies:
     - build_master
   before_script: []

.gitlab/merge_request_templates/Release-Post.md

@@ -24,6 +24,7 @@ Due date: MM/DD (6th working day before the 22nd)
 - [ ] Omnibus improvements
 - [ ] Deprecations
 - [ ] Documentation links
+- [ ] Add features to `data/features.yml`
 - [ ] Authorship (author's data)
 ### Review
@@ -49,6 +50,7 @@ Due date: MM/DD (2nd working day before the 22nd)
   - [ ] Title
   - [ ] Description
   - [ ] Grammar, spelling, clearness (body)
+- [ ] Marketing review (PMM, CMM)
 - [ ] Final review (Job)
 #### Structural Check

config.rb

@@ -84,7 +84,7 @@ org_chart = OrgChart.new
 proxy "/team/structure/index.html", "/team/structure/template.html", locals: { team_data_tree: org_chart.team_data_tree }, ignore: true
 # Proxy comparison PDF pages
-data.comparisons.comparisons.each do |key, comparison|
+data.features.comparisons.each do |key, comparison|
   file_name = key.dup.gsub(/_/, '-')
   proxy "/comparison/pdfs/#{file_name}.html", "/comparison/pdfs/template.html", locals: {
     comparison_block: comparison,

data/applications.yml

@@ -50,6 +50,13 @@
       links:
         - url: http://branchesapp.co
           title: branchesapp.co
+    - title: Zulip
+      content: Get notifications about your GitLab projects in Zulip. Zulip is the world's most productive group chat and the leading open source alternative to Slack. With Zulip, you don't have to choose between missing important conversations and wasting time reading irrelevant ones.
+      links:
+        - url: https://zulipchat.com/
+          title: About Zulip
+        - url: https://zulipchat.com/integrations/#gitlab
+          title: Zulip's GitLab integration
 - title: CLI Clients
   id: cli-clients
   applications:
@@ -389,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:
@@ -433,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/events.yml

@@ -177,4 +177,25 @@
                Learn more about inner workings of Git protocol and how you can use Go as a performant way to deliver Git to the masses. This talk will explore the work done in Gitlab Workhorse and as an experiment, migrate the Git Smart HTTP code to Caddy (a modular Go HTTP Server).
   location: São Paulo, Brazil
   social_tags: theconfbr
-  event_url: http://www.theconf.club
\ No newline at end of file
+  event_url: http://www.theconf.club
+  
+  
+- topic: USENIX LISA 2017
+  type: Training, Conference
+  date: October 29 - November 3 2017
+  date_ends: November 3, 2017 # Month DD, YYYY
+  description: |
+               Our partners at Vertical Sysadmin will be leading training courses on, "Git Foundations: Unlocking the Mysteries" and "Setting up CI/CD Pipelines." The CI/CD course will cover GitLab CI and Jenkins (the conference wanted a vendor-neutral approach).
+  location: San Francisco, CA USA
+  social_tags: LISA17
+  event_url: https://www.usenix.org/conference/lisa17
+  
+- topic: AWS Reinvent
+  type: Cloud, Conference
+  date: November 27 - December 1 2017
+  date_ends: December 1, 2017 # Month DD, YYYY
+  description: |
+               AWS re:Invent is a learning conference hosted for the global cloud computing community. The event features keynote announcements, training and certification opportunities.
+  location: Las Vegas, NV USA
+  social_tags: AWSreinvent
+  event_url: https://reinvent.awsevents.com/
\ No newline at end of file

data/gitlab_com.yml

 prices:
-  - title: Free Plan
+  free_plan:
+    title: Free Plan
     support: Unlimited private projects and collaborators
     monthly: Free
     description:
@@ -7,8 +8,8 @@ prices:
     features: Community Edition <a href="/products/#comparison">features</a>*
     link: https://gitlab.com/users/sign_in
     link_text: Sign Up
-  - title: Bronze Plan
-    support: Next business day support
+  bronze_plan:
+    title: Bronze Plan
     paid: true
     monthly: $4
     yearly: $48
@@ -16,9 +17,9 @@ prices:
       2,000 CI pipeline minutes per month
     features: Enterprise Edition Starter <a href="/products/#comparison">features</a>*
     link: https://customers.gitlab.com/subscriptions/new?plan_id=2c92a0ff5a840412015aa3cde86f2ba6
-    link_text: Buy now
-  - title: Silver Plan
-    support: Next business day support
+    link_text: Buy Now
+  silver_plan:
+    title: Silver Plan
     paid: true
     monthly: $19
     yearly: $228
@@ -27,8 +28,8 @@ prices:
     features: Enterprise Edition Premium <a href="/products/#comparison">features</a>*
     link: https://customers.gitlab.com/subscriptions/new?plan_id=2c92a0fd5a840403015aa6d9ea2c46d6
     link_text: Buy Now
-  - title: Gold Plan
-    support: 4-hour support response time
+  gold_plan:
+    title: Gold Plan
     paid: true
     monthly: $99
     yearly: $1188

data/installation_methods.yml

@@ -7,6 +7,10 @@ official:
     name: 'Kubernetes'
     logo: '/images/logos/kubernetes-logo.svg'
     desc: 'Official Helm repository'
+  - url: 'https://docs.gitlab.com/ee/install/google_cloud_platform/index.html'
+    name: 'Google Cloud Platform'
+    logo: '/images/logos/google-cloud-logo.svg'
+    desc: 'Official Google Cloud Launcher apps'
   - url: '/2016/06/28/get-started-with-openshift-origin-3-and-gitlab'
     name: 'RedHat OpenShift'
     logo: '/images/logos/openshift-logo.svg'
@@ -56,7 +60,7 @@ official:
     logo: '/images/logos/gitlab-logo.svg'
 community:
-  - url: 'http://packages.ubuntu.com/search?keywords=gitlab&searchon=names&suite=all&section=all'
+  - url: 'https://launchpad.net/ubuntu/+source/gitlab/'
     name: 'Ubuntu package'
     logo: '/images/logos/ubuntu-logo.svg'
     desc: 'by Masters of the Universe'
@@ -76,10 +80,6 @@ community:
     name: 'Ansible playbook'
     logo: '/images/logos/ansible-logo.svg'
     desc: 'by Ben Kochie'
-  - url: 'https://launchpad.net/ubuntu/+source/gitlab/'
-    name: 'Debian package'
-    logo: '/images/logos/debian-logo.svg'
-    desc: 'by Pirate Praveen'
   - url: 'http://www.freshports.org/www/gitlab'
     name: 'FreeBSD package'
     logo: '/images/logos/free-bsd-logo.svg'
@@ -92,10 +92,6 @@ community:
     name: 'Vagrant option'
     desc: 'by Tuomo Tanskanen'
     logo: '/images/logos/vagrant-logo.svg'
-  - url: 'https://gitlab.com/gitlab-org/gitlab-recipes/'
-    name: 'GitLab recipes'
-    desc: 'Using GitLab with different software'
-    logo: '/images/logos/gitlab-logo.svg'
   - url: 'https://jujucharms.com/u/spiculecharms/gitlab-server/1'
     name: 'GitLab Juju'
     desc: 'by Spicule IT Systems'
@@ -104,3 +100,7 @@ community:
     name: 'Fedora package'
     desc: 'Help contribute'
     logo: '/images/logos/fedora-logo.svg'
+  - url: 'https://gitlab.com/gitlab-org/gitlab-recipes/'
+    name: 'GitLab recipes'
+    desc: 'Using GitLab with different software'
+    logo: '/images/logos/gitlab-logo.svg'

data/jobs.yml

@@ -12,7 +12,7 @@
   open: false
-- title: "Recruiter"
+- title: "Junior Recruiter"
   description: /jobs/recruiter/
   apply: https://gitlab.workable.com/jobs/436821/candidates/new
   open: true
@@ -209,6 +209,12 @@
   apply:
   open: false
+- title: "Federal Solutions Architect"
+  description: /jobs/federal-solutions-architect/
+  salary: 129311
+  apply: https://gitlab.workable.com/jobs/514880/candidates/new
+  open: true
+
 # Ordered alphabetically **by job description URL**
 - title: "Field Marketing Manager"
@@ -263,12 +269,17 @@
 - title: "Performance Lead"
   description: /jobs/performance-lead
-  apply: https://gitlab.workable.com/jobs/398569/candidates/new
-  open: true
+  apply:
+  open: false
 - title: "Senior Product Marketing Manager"
   description: /jobs/senior-product-marketing-manager/
-  apply: https://gitlab.workable.com/jobs/202183/candidates/new
+  apply:
+  open: false
+
+- title: "Director of Product Marketing"
+  description: /jobs/director-product-marketing
+  apply: https://gitlab.workable.com/jobs/512970/candidates/new
   open: true
 - title: "Product Manager"
@@ -321,15 +332,23 @@
 - title: "Support Engineer - EMEA "
   description: /jobs/support-engineer/
   salary: 75500
-  apply:
-  open: false
-- title: "Solutions Architect (Customer Success)"
+  apply: https://gitlab.workable.com/jobs/87722/candidates/new
+  open: true
+
+- title: "Solutions Architect - Customer Success"
+  description: /jobs/solutions-architect/
+  salary: 129311
+  apply: https://gitlab.workable.com/jobs/242971/candidates/new
+  open: true
+- title: "Solutions Architect - Customer Success (EMEA)"
   description: /jobs/solutions-architect/
   salary: 129311
   apply: https://gitlab.workable.com/jobs/242971/candidates/new
   open: true
+
+
 # Ordered alphabetically **by job description URL**
 - title: "Support Lead"
@@ -361,6 +380,12 @@
   apply:
   open: false
+- title: "Technical Writing Lead"
+  description: /jobs/technical-writing-lead/
+  salary:
+  apply: https://gitlab.workable.com/jobs/515784/candidates/new
+  open: true
+
 - title: "UX Lead"
   description: /jobs/ux-lead/
   salary: 85843
@@ -389,7 +414,7 @@
   apply:
   open: false
-- title: "Senior Web/UX Designer"
+- title: "Web/UX Designer"
   description: /jobs/web-ux-designer/
   apply:
   open: false

data/platforms.yml

@@ -16,7 +16,6 @@
   install_commands: |
                     sudo apt-get install gitlab-ce
   install_commands_manual: |
-                    curl -LJO https://packages.gitlab.com/gitlab/gitlab-ce/packages/ubuntu/xenial/gitlab-ce-XXX.deb/download
                     dpkg -i gitlab-ce-XXX.deb
   dependency_commands: |
                     sudo apt-get install curl openssh-server ca-certificates postfix
@@ -37,7 +36,6 @@
   install_commands: |
                     sudo apt-get install gitlab-ce
   install_commands_manual: |
-                    curl -LJO https://packages.gitlab.com/gitlab/gitlab-ce/packages/debian/jessie/gitlab-ce-XXX.deb/download
                     dpkg -i gitlab-ce-XXX.deb
   dependency_commands: |
                     sudo apt-get install curl openssh-server ca-certificates postfix

data/press.yml

@@ -61,3 +61,7 @@
 - title: "GitLab adds Buddybuild to Global Partnership Program"
   link: https://about.gitlab.com/press/releases/2017-01-25-buddybuild-press-release.html
   date: 2017-01-25
+
+- title: "GitLab adds Creationline to Global Partnership Program"
+  link: 2017-06-26-creationline-press-release.html
+  date: 2017-06-26

data/projects.yml

@@ -23,6 +23,14 @@ gitlab-ee:
     GitLab EE requires a license key to be used.
+gitlab-elasticsearch-indexer:
+  name: GitLab Elasticsearch Indexer
+  path: gitlab-org/gitlab-elasticsearch-indexer
+  link: https://gitlab.com/gitlab-org/gitlab-elasticsearch-indexer
+  description: |
+    An Elasticsearch indexer for Git repositories. Used by GitLab EE to
+    implement Global Code Search.
+
 gitlab-shell:
   name: GitLab Shell
   path: gitlab-org/gitlab-shell
@@ -73,6 +81,13 @@ gitlab-com-runbooks:
     Describes system components, triage procedures, and commands to use in scenarios commonly faced
     by Gitlab.com production support engineers
+infrastructure:
+  name: Gitlab.com - infrastructure issue tracker
+  path: gitlab-com/infrastructure
+  link: https://gitlab.com/gitlab-com/infrastructure
+  description: |
+    Used to track the infrastructure work of GitLab.com itself
+
 gitlab-cookbooks:
   name: Gitlab.com - infrastructure node provisioning by role
   path: gitlab-cookbooks

data/promo.yml

-text: "Discover why CI/CD is at the core of modern software development. Download the white paper."
-link: 'http://get.gitlab.com/scaled-ci-cd/'
+text: "GitLab 9.3 Released with Code Quality, Multi-Project Pipeline Graphs, Improved Internationalization, and much more!"
+link: '/2017/06/22/gitlab-9-3-released/'

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
+
+All features are listed in a single yaml file
+([`/data/features.yml`](/data/features.yml)) under the `features` section.
+
+## Update the features page (under `/features`)
+
+The [`/features`](https://about.gitlab.com/features/) page grabs its content
+automatically from [`/data/features.yml`](/data/features.yml).
+
+The table below tries to describe the minimum values a feature that appears
+under the `/features` can have and how they should be used.
+
+| Features values | Description |
+| --------------- | ----------- |
+| `title` | The distinct title of a feature.  |
+| `description` | The description of the feature. Can include Markdown. |
+| `screenshot_url` | Relative URL of the feature screenshot if relevant. |
+| `link_description` | Below every feature usually a link appears pointing to the feature page or the documentation. This value is its description, e.g., `"Learn more about CI/CD"`. |
+| `link` | The link pointing either to the feature page or in the docs. |
+| `gitlab_ce`  | Set to true if the feature is in CE. |
+| `gitlab_ees` | Set to true if the feature is in EES. |
+| `gitlab_eep` | Set to true if the feature is in EEP. |
+| `not_on_gitlab_com` | Set to true for features which aren't relevant to GitLab.com, for example LDAP authentication. |
+| `feature_page` | Set to true for pages that have their own dedicated page under `/features`. If set to true, the `link` should point to the relevant feature page. All features that have this and `gitlab_ce` set to true, are shown on the Products page under CE (because CE has about as many features in the `features.yml` as EES, it made EES look less enticing, so we currently only show features that have a feature page). |
+
+Example:
+
+```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
+    gitlab_ce: true
+    gitlab_ees: true
+    gitlab_eep: true
+```
+
+## Update the products page (under `/products`)
+
+The [`/products`](https://about.gitlab.com/products/) page grabs its content
+automatically from [`/data/features.yml`](/data/features.yml).
+
+It works the same as the features description above.
+
+## Update the gitlab-com page (under `/gitlab-com`)
+
+The [`/gitlab-com`](https://about.gitlab.com/gitlab-com/) page grabs its content
+automatically from [`/data/features.yml`](/data/features.yml).
+
+It works the same as the features description above.
+
+## Create or update the comparison pages (under `/comparison`)
+
+The [comparison page][comp] grabs its content automatically from
+`data/features.yml`.
+
+There are 2 files in total which you need to create or update:
+
+- `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**).
+
+1. Edit `data/features.yml` (`competitors`, `comparisons` and `features`
+   sections):
+
+    ```yaml
+    competitors:
+      gitlab_com:
+        name: 'GitLab.com'
+        logo: '/images/comparison/gitlab-logo.svg'
+      github_com:
+        name: 'GitHub.com'
+        logo: '/images/comparison/github-logo.svg'
+
+    ...
+
+    comparisons:
+      gitlab_com_vs_github_com:
+        title: 'GitΗub.com vs. GitLab.com'
+        link: '/comparison/gitlab-com-vs-github-com.html'
+        product_one: 'gitlab_com'
+        product_two: 'github_com'
+        pdf: 'gitlabcom-vs-githubcom.pdf'
+
+    ...
+
+    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"
+        gitlab_com: true
+        github_com: true
+    ```
+
+      **Notes:**
+      - The `link` attribute is the relative link to the comparison page. It should
+        have the same name as the one we create in the next step.
+      - 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'`.
+      - The competitor's logo (`product_two`) can be `svg` or `png`. Save it in
+        `source/images/comparison/competitor-logo.svg`.
+      - In the features area, `product_one` is always GitLab, and `product_two`
+        is the competitor we are comparing against. Values for these two fields are
+        `true|false|sortof`.
+
+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
+   names of competitors:
+
+    ```yaml
+    ---
+    layout: comparison_page
+    trial_bar: true
+    suppress_header: true
+    title: "GitHub.com vs GitLab.com | GitLab compared to other tools"
+    image_title: '/images/comparison/title_image.png'
+    extra_css:
+      - compared.css
+    extra_js:
+      - comparison.js
+    ---
+
+    - competitors = data.features.competitors
+    = partial "includes/comparison_table", locals: { comparison_block: data.features.comparisons.gitlab_com_vs_github_com, product_one: competitors.gitlab_com, product_two: competitors.github_com, key_one: :gitlab_com, key_two: :github_com }
+    ```
+
+1. If you followed the above 2 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](pdf.md#comparison-pdfs).
+
+[comp]: https://about.gitlab.com/comparison/
+
+## Update the Return on Investment calculator page (under `/roi`)
+
+The [`/roi`](https://about.gitlab.com/roi/) page grabs its content
+automatically from [`/data/features.yml`](/data/features.yml).
+
+The table below tries to describe the minimum values a feature for the ROI
+calculator will need in order to appear under `/roi`.
+
+| Features values | Description |
+| --------------- | ----------- |
+| `title` | The distinct title of a feature. |
+| `link` | The link pointing either to the feature page or the docs. |
+| `shorthand` | This is the id that it's used for the url parameters so users can share their ROI calculations. It needs to have underscores (`_`) instead of spaces in order for it to work.  |
+| `hours_per_incident` | The number of hours that an incident will take before it's solved. It can be skipped but it will make the calculator return 0 for that feature. |
+| `incidents_per_year` | The number of times that an incident will happen in a year. It can be skipped but it will make the calculator return 0 for that feature. |
+| `roi_case` | The description of the case that makes use of the feature that's described on the title, if this is skipped the feature will not be considered for the roi features table. |