Merge branch 'zj-update-documentation' into 'master'

Update documentation and add a index

See merge request gitlab-org/gitaly!1111

4 files changed, 63 insertions, 39 deletions

diff --git a/README.md b/README.md
index df31e18da..11dab7ce1 100644
--- a/README.md
+++ b/README.md
@@ -1,13 +1,11 @@
 # ![Gitaly](https://gitlab.com/gitlab-org/gitaly/uploads/509123ed56bd51247996038c858db006/gitaly-wordmark-small.png)
 
-[![Pipeline status](https://gitlab.com/gitlab-org/gitaly/badges/master/pipeline.svg)](https://gitlab.com/gitlab-org/gitaly/commits/master) [![coverage report](https://gitlab.com/gitlab-org/gitaly/badges/master/coverage.svg)](https://codecov.io/gl/gitlab-org/gitaly)
-
 **Quick Links**:
-  [**Roadmap**](https://gitlab.com/groups/gitlab-org/-/roadmap?label_name%5B%5D=Gitaly&scope=all&sort=start_date_asc&state=opened) |
+  [**Roadmap**][roadmap] |
   [Want to Contribute?](https://gitlab.com/gitlab-org/gitaly/issues?scope=all&utf8=%E2%9C%93&state=opened&label_name[]=Accepting%20merge%20requests) |
   [GitLab Gitaly Issues](https://gitlab.com/groups/gitlab-org/-/issues?scope=all&state=opened&utf8=%E2%9C%93&label_name%5B%5D=Gitaly) |
   [GitLab Gitaly Merge Requests](https://gitlab.com/groups/gitlab-org/-/merge_requests?label_name%5B%5D=Gitaly) |
-  [gitlab.com monitoring dashboard](https://dashboards.gitlab.com/d/000000176/gitaly) |
+  [GitLab.com Monitoring Dashboard][dashboards]
 
 --------------------------------------------
 
@@ -33,17 +31,16 @@ longer uses direct disk access to touch Git repositories; the [NFS
 mounts have been
 removed](https://about.gitlab.com/2018/09/12/the-road-to-gitaly-1-0/).
 
-The last feature that remains to be migrated is the [Elasticsearch
-indexer](https://gitlab.com/gitlab-org/gitaly/issues/760). Once that is
-done we can conclude the migration project by [removing the Git
-repository storage paths from gitlab-rails's
+For performance reasons some RPCs can be performed through NFS still. An
+effort is made to mitigate performance issues by removing [Gitaly N+1](https://gitlab.com/groups/gitlab-org/-/epics/827).
+Once that is no longer neccesairy we can conclude the migration project by 
+[removing the Git repository storage paths from gitlab-rails's
 configuration](https://gitlab.com/gitlab-org/gitaly/issues/1282).
 
-In the meantime we are building features according to our
-[roadmap](https://gitlab.com/groups/gitlab-org/-/roadmap?label_name%5B%5D=Gitaly&scope=all&sort=start_date_asc&state=opened).
+In the meantime we are building features according to our [roadmap][roadmap].
 
 If you're interested in seeing how well Gitaly is performing on
-GitLab.com, we have dashboards!
+GitLab.com, we have [dashboards][dashboards]!
 
 ##### Overall
 
@@ -111,6 +108,10 @@ use library code from the
 [gitlab.com/gitlab-org/gitaly/client](https://gitlab.com/gitlab-org/gitaly/tree/master/client)
 package.
 
+## Further reading
+
+More about the project, and its processes is [accumulated in the docs](doc/index.md).
+
 ## Distributed Tracing
 
 Gitaly supports distributed tracing through [LabKit](https://gitlab.com/gitlab-org/labkit/) using [OpenTracing APIs](https://opentracing.io).
@@ -144,3 +145,6 @@ GITLAB_TRACING=opentracing://jaeger ./gitaly config.toml
 - [Infrastructure Team Update 2017-05-11](https://about.gitlab.com/2017/05/11/functional-group-updates/#infrastructure-team)
 - [Gitaly Basics, 2017-05-01](https://docs.google.com/presentation/d/1cLslUbXVkniOaeJ-r3s5AYF0kQep8VeNfvs0XSGrpA0/edit#slide=id.g1c73db867d_0_0)
 - [Git Paris meetup, 2017-02-22](https://docs.google.com/presentation/d/19OZUalFMIDM8WujXrrIyCuVb_oVeaUzpb-UdGThOvAo/edit?usp=sharing) a high-level overview of what our plans are and where we are.
+
+[dashboards]: https://dashboards.gitlab.com/d/000000176/gitaly
+[roadmap]: https://gitlab.com/groups/gitlab-org/-/roadmap?label_name%5B%5D=Gitaly&scope=all&sort=start_date_asc&state=opened
diff --git a/doc/PROCESS.md b/doc/PROCESS.md
index ebf866c3c..b68bc7a68 100644
--- a/doc/PROCESS.md
+++ b/doc/PROCESS.md
@@ -1,14 +1,10 @@
-## Plan
-
-We use our issues board for keeping our work in progress up to date in a single place. Please refer to it to see the current status of the project.
-
 ## Gitaly Team Process
 
 ### Gitaly Releases
 
 Gitaly uses [SemVer](https://semver.org) version numbering.
 
-## Branching Model
+#### Branching Model
 
 All `vX.Y.0` tags get created on the `master` branch. We only make patch
 releases when targeting a GitLab stable branch. Patch releases
@@ -19,3 +15,27 @@ There should be **no patch releases on `master`**. Gitaly patch releases should
 only be used for GitLab stable branches. If the release is not for a
 GitLab stable branch, just increment the minor (or major) version
 counter.
+
+#### Creating a release
+
+- Pick a release number (x.y.z)
+- Check out the master branch on your local machine
+- run `_support/release x.y.z`
+
+Where x.y.z is a semver-compliant version number.
+
+- To automatically create a merge-request in Gitlab CE to update that
+  project to the latest tag, run
+
+```shell
+GITLAB_TOKEN=$(cat /path/to/gitlab-token) _support/update-downstream-server-version
+```
+
+- This will create a merge-request (with changelog) and assign it to you. Once the build has
+  completed successfully, assign it to a maintainer for review.
+
+## Experimental builds
+
+Push the release tag to dev.gitlab.org/gitlab/gitaly. After the
+passing the test suite, the tag will automatically be built and
+published in https://packages.gitlab.com/gitlab/unstable.
diff --git a/doc/README.md b/doc/README.md
new file mode 100644
index 000000000..8a56249f0
--- /dev/null
+++ b/doc/README.md
@@ -0,0 +1,23 @@
+## Gitaly documentation
+
+The historical reasons for the inception of Gitaly and our design decisions are
+written in [the design doc](doc/DESIGN.md).
+
+#### Configuring Gitaly
+
+Running Gitaly requires it to be configured correctly, options are described in
+the [configuration documentation](doc/configuration/README.md).
+
+#### Developing Gitaly
+
+- When new to Gitaly development, start by reading the [beginners guide](docs/beginners_guid.md).
+- When developing on Gitaly-Ruby, read the [Gitaly-Ruby doc](doc/ruby_endpoint.md)
+- The Gitaly release process is descripted in [our process doc](doc/PROCESS.md)
+- Tests use Git repositories too, [read more about them](doc/test_repos.md)
+
+#### Gitaly HA
+
+Gitaly does not replicate any data. If a Gitaly server goes down, any of its
+clients can't read or write to the repositories stored on that server. This
+means that Gitaly is not highly available. How this will be solved is described
+[in the HA design document](doc/design_ha.md)
diff --git a/doc/release.md b/doc/release.md
deleted file mode 100644
index 7986d21cf..000000000
--- a/doc/release.md
+++ /dev/null
@@ -1,23 +0,0 @@
-# Gitaly release process
-
-- Pick a release number (x.y.z)
-- Check out the master branch on your local machine
-- run `_support/release x.y.z`
-
-Where x.y.z is a semver-compliant version number.
-
-- To automatically create a merge-request in Gitlab CE to update that
-  project to the latest tag, run
-
-```shell
-GITLAB_TOKEN=$(cat /path/to/gitlab-token) _support/update-downstream-server-version
-```
-
-- This will create a merge-request (with changelog) and assign it to you. Once the build has
-  completed successfully, assign it to a maintainer for review.
-
-## Experimental builds
-
-Push the release tag to dev.gitlab.org/gitlab/gitaly. After the
-passing the test suite, the tag will automatically be built and
-published in https://packages.gitlab.com/gitlab/unstable.