Merge branch 'docs/make-ci-run-only-for-doc-changes' into 'master'

Skip irrelevant jobs for documentation only changes

Closes #30853

See merge request !10961

.gitlab-ci.yml

@@ -68,6 +68,13 @@ stages:
     - //@gitlab-org/gitlab-ee
     - //@gitlab/gitlab-ee
 
+# Skip all jobs except the ones that begin with 'docs/'.
+# Used for commits including ONLY documentation changes.
+# https://docs.gitlab.com/ce/development/writing_documentation.html#testing
+.except-docs: &except-docs
+  except:
+    - /^docs\/.*/
+
 .rspec-knapsack: &rspec-knapsack
   stage: test
   <<: *dedicated-runner
@@ -91,11 +98,13 @@ stages:
 .rspec-knapsack-pg: &rspec-knapsack-pg
   <<: *rspec-knapsack
   <<: *use-pg
+  <<: *except-docs
 
 .rspec-knapsack-mysql: &rspec-knapsack-mysql
   <<: *rspec-knapsack
   <<: *use-mysql
   <<: *only-master-and-ee-or-mysql
+  <<: *except-docs
 
 .spinach-knapsack: &spinach-knapsack
   stage: test
@@ -120,16 +129,19 @@ stages:
 .spinach-knapsack-pg: &spinach-knapsack-pg
   <<: *spinach-knapsack
   <<: *use-pg
+  <<: *except-docs
 
 .spinach-knapsack-mysql: &spinach-knapsack-mysql
   <<: *spinach-knapsack
   <<: *use-mysql
   <<: *only-master-and-ee-or-mysql
+  <<: *except-docs
 
 # Prepare and merge knapsack tests
 knapsack:
   <<: *knapsack-state
   <<: *dedicated-runner
+  <<: *except-docs
   stage: prepare
   script:
     - mkdir -p knapsack/${CI_PROJECT_NAME}/
@@ -156,6 +168,7 @@ update-knapsack:
 setup-test-env:
   <<: *use-pg
   <<: *dedicated-runner
+  <<: *except-docs
   stage: prepare
   script:
     - node --version
@@ -243,6 +256,7 @@ spinach mysql 9 10: *spinach-knapsack-mysql
 .exec: &exec
   <<: *ruby-static-analysis
   <<: *dedicated-runner
+  <<: *except-docs
   stage: test
   script:
     - bundle exec $CI_JOB_NAME
@@ -250,6 +264,7 @@ spinach mysql 9 10: *spinach-knapsack-mysql
 rubocop:
   <<: *ruby-static-analysis
   <<: *dedicated-runner
+  <<: *except-docs
   stage: test
   script:
     - bundle exec "rubocop --require rubocop-rspec"
@@ -266,6 +281,7 @@ rake downtime_check:
     - master
     - tags
     - /^[\d-]+-stable(-ee)?$/
+    - /^docs\/*/
 
 rake ee_compat_check:
   <<: *exec
@@ -296,10 +312,12 @@ rake ee_compat_check:
 rake pg db:migrate:reset:
   <<: *db-migrate-reset
   <<: *use-pg
+  <<: *except-docs
 
 rake mysql db:migrate:reset:
   <<: *db-migrate-reset
   <<: *use-mysql
+  <<: *except-docs
 
 .db-rollback: &db-rollback
   stage: test
@@ -311,10 +329,12 @@ rake mysql db:migrate:reset:
 rake pg db:rollback:
   <<: *db-rollback
   <<: *use-pg
+  <<: *except-docs
 
 rake mysql db:rollback:
   <<: *db-rollback
   <<: *use-mysql
+  <<: *except-docs
 
 .db-seed_fu: &db-seed_fu
   stage: test
@@ -336,14 +356,17 @@ rake mysql db:rollback:
 rake pg db:seed_fu:
   <<: *db-seed_fu
   <<: *use-pg
+  <<: *except-docs
 
 rake mysql db:seed_fu:
   <<: *db-seed_fu
   <<: *use-mysql
+  <<: *except-docs
 
 rake gitlab:assets:compile:
   stage: test
   <<: *dedicated-runner
+  <<: *except-docs
   dependencies: []
   variables:
     NODE_ENV: "production"
@@ -367,6 +390,7 @@ rake karma:
   stage: test
   <<: *use-pg
   <<: *dedicated-runner
+  <<: *except-docs
   variables:
     BABEL_ENV: "coverage"
   script:
@@ -447,6 +471,7 @@ coverage:
   stage: post-test
   services: []
   <<: *dedicated-runner
+  <<: *except-docs
   variables:
     SETUP_DB: "false"
     USE_BUNDLE_INSTALL: "true"
@@ -462,6 +487,7 @@ coverage:
 
 lint:javascript:
   <<: *dedicated-runner
+  <<: *except-docs
   stage: test
   before_script: []
   script:
@@ -469,6 +495,7 @@ lint:javascript:
 
 lint:javascript:report:
   <<: *dedicated-runner
+  <<: *except-docs
   stage: post-test
   before_script: []
   script:

doc/development/writing_documentation.md

@@ -70,3 +70,27 @@ All the docs follow the same [styleguide](doc_styleguide.md).
 ### Markdown
 
 Currently GitLab docs use Redcarpet as [markdown](../user/markdown.md) engine, but there's an [open discussion](https://gitlab.com/gitlab-com/gitlab-docs/issues/50) for implementing Kramdown in the near future.
+
+## Testing
+
+We try to treat documentation as code, thus have implemented some testing.
+Currently, the following tests are in place:
+
+1. `docs:check:links`: Check that all internal (relative) links work correctly
+1. `docs:check:apilint`: Check that the API docs follow some conventions
+
+If your contribution contains **only** documentation changes, you can speed up
+the CI process by prepending to the name of your branch: `docs/`. For example,
+a valid name would be `docs/update-api-issues` and it will run only the docs
+tests. If the name is `docs-update-api-issues`, the whole test suite will run
+(including docs).
+
+---
+
+When you submit a merge request to GitLab Community Edition (CE), there is an
+additional job called `rake ee_compat_check` that runs against Enterprise
+Edition (EE) and checks if your changes can apply cleanly to the EE codebase.
+If that job fails, read the instructions in the job log for what to do next.
+Contributors do not need to submit their changes to EE, GitLab Inc. employees
+on the other hand need to make sure that their changes apply cleanly to both
+CE and EE.