Write `Starting with GitLab QA` documentation

Documentation

It is quite difficult to start writing high-quality GitLab QA specs now. After a few weeks of reviewing merge requests, I think we should make it easier for developers to start working with GitLab QA.

Proposal

Add CONTRIBUTING.md documentation that will cover most important end-to-end testing principles for someone who is just starting writing QA specs.

We already do have some docs, but we need one single document that will document most important things.

Some ideas about what it should cover:

  1. Explain what GitLab QA is, link to existing documentation, architecture diagram etc.
  2. Explain why we are using Page Objects, and why this concept is important, link to existing docs in qa/qa/page/README.md.
  3. Link to existing docs about development on MacOS.
  4. Why we should have black-box / user-oriented approach (why having 100 lines of JavaScript with page.evaluate_script in specs is usually not a good idea)
  5. When it is helpful and needed to extend the GitLab QA framework itself, encourage developers to dive into the framework too. Provide examples.
  6. Write a few stories about writing complex test scenarios (for example for Geo) and how we approached it.
  7. Write docs about using Factories ➡ #156 (closed)
  8. Document we should not assert on selectors in _spec.rb files, assert only on page objects instead
  9. Document using qa/ qa- prefixes / suffixes to limit amount of jobs being run in a pipeline.
  10. Why we should focus on using tools that users are going to use instead of bundling Ruby gems that are supposed to replace tools (git, ssh).
  11. Explain why we are using Docker extensively and why it is sometimes difficult to contribute when your are not using Linux.

/cc @rymai @bjgopinath

Edited by Bj Gopinath