Reconcile the contirbuting doc with the development docs.

CONTRIBUTING.md

@@ -23,7 +23,7 @@ _This notice should stay as the first item in the CONTRIBUTING.md file._
 ## Definition of done
-The omnibus-gitlab project uses the [definition of done as noted in GitLab Community Edition (and Enterprise Edition)](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/CONTRIBUTING.md#definition-of-done).
+The omnibus-gitlab project uses the [definition of done as noted in GitLab Community Edition (and Enterprise Edition)](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/development/contributing/merge_request_workflow.md#definition-of-done).
 As this project is a wrapper around GitLab CE/EE, some additions to the definition apply:
@@ -46,6 +46,18 @@ If you are experiencing problems during GitLab package installation or have issu
 This can be the case when installation and `gitlab-ctl reconfigure` run went without issues but your GitLab instance is still giving 500 error page with an error in the log.
+## I want to contribute!
+
+If you want to contribute to GitLab Omnibus, issues with both the ~Accepting merge requests and ~For Scheduling labels 
+are issues that have been triaged as areas where where we are looking for contributors to help us out.
+
+See the [contributor issue issues list](https://gitlab.com/gitlab-org/omnibus-gitlab/issues?state=opened&label_name[]=Accepting%20merge%20requests&label_name[]=For%20Scheduling).
+
+If you have any questions or need help visit [Getting Help](https://about.gitlab.com/getting-help/#discussion) to
+learn how to communicate with GitLab. If you're looking for a Gitter or Slack channel
+please consider we favor
+[asynchronous communication](https://about.gitlab.com/handbook/communication/#internal-communication) over real time communication. Thanks for your contribution!
+
 ## Maintainer documentation
 Maintainers of this project will try to address issues in a timely manner.
@@ -108,58 +120,27 @@ suites where possible as part of the review process.
 ## Developer Guidelines
-### Setting up development environment
-
-Check [setting up development environment docs](doc/development/README.md) for
-instructions on setting up a environment for local development.
-
-### Writing tests
-
-Any change in the internal cookbook also requires specs. Apart from testing the
-specific feature/bug, it would be greatly appreciated if the submitted Merge
-Request includes more tests. This is to ensure that the test coverage grows with
-development.
-When in rush to fix something (eg. security issue, bug blocking the release),
-writing specs can be skipped. However, an issue to implement the tests
-**must be** created and assigned to the person who originally wrote the code.
-To run tests, execute the following command (you may have to run `bundle install` before running it)
-```
-bundle exec rspec
-```
-### Merge Request Guidelines
-If you are working on a new feature or an issue which doesn't have an entry on
-Omnibus GitLab's issue tracker, it is always a better idea to create an issue
-and mention that you will be working on it as this will help to prevent
-duplication of work. Also, others may be able to provide input regarding the
-issue, which can help you in your task.
-It is preferred to make your changes in a branch named \<issue
-number>-\<description> so that merging the request will automatically close the
-specified issue.
-
-A good Merge Request is expected to have the following components, based on
-their applicability:
- 1. Full Merge Request description explaining why this change was needed
- 2. Code for implementing feature/bugfix
- 3. Tests, as explained in [Writing Tests](#writing-tests)
- 4. Documentation explaining the change
- 5. If Merge Request introduces change in user facing configuration, update to [gitlab.rb template](files/gitlab-config-template/gitlab.rb.template)
- 6. Changelog entry to inform about the change, if necessary.
-**`Note:`** Ensure shared runners are enabled for your fork in order for our automated tests to run.[^1]
-[^1]:
-  1. Go to Settings -> CI/CD
-  1. Expand Runners settings
-  1. If shared runners are not enabled, click on the button labeled "Enable shared Runners"
-### Unofficial packaging point of contact
+### Developer Documentation
+See the [developer documentation](doc/development/README.md) for additional information.
+#### Setting up development environment
+See the [developer documentation](doc/development/README.md#setting-up-development-environment)
+#### Understanding the architecture
+See the [developer documentation](doc/development/README.md#understanding-the-architecture)
+### Writing tests
+See the [developer documentation](doc/development/README.md#writing tests)
+### Merge Request Guidelines
+See the [developer documentation](doc/development/README.md#merge-request-guidelines)
+## Unofficial packaging point of contact
 The omnibus-gitlab project is a project used for building official GitLab packages.
 There are multiple community driven projects for packaging, such as [GitLab CE unofficial Debian 9](https://packages.debian.org/stretch/gitlab) package.

doc/README.md

@@ -123,11 +123,4 @@ You can also use the docker images provided by GitLab to install and configure a
 ## Omnibus GitLab developer documentation
-- [Development Setup](development/README.md)
-- [Omnibus GitLab Architecture](architecture/README.md)
-- [Adding a new Service to Omnibus GitLab](development/new-services.md)
-- [Creating patches](development/creating-patches.md)
-- [Release process](release/README.md)
-- [Building your own package](build/README.md)
-- [Building a package from a custom branch](build/README.md#building-a-package-from-a-custom-branch)
-- [Adding deprecation messages](development/adding-deprecation-messages.md)
+See the [development documentation](development/README.md)

doc/architecture/README.md

@@ -4,6 +4,8 @@ Omnibus-GitLab is a customized fork of the Omnibus project from Chef, and it use
 ![Omnibus-GitLab Components](components.png)
+An in-depth video walkthrough of these components is available [on YouTube](https://www.youtube.com/watch?v=m89NHLhTMj4 )
+
 ## Software Definitions
 ### GitLab project definition file

doc/development/README.md

-# Setting up your development environment
-Development of Omnibus GitLab maybe done using an existing package available
-from [Downloads page](https://about.gitlab.com/downloads). To know how to setup
-a build environment to build these packages and use them, please read [Setting
-up a Build Environment](../build/prepare-build-environment.md).
- 1. Setup a VM
-    To provide isolation and to prevent rebuilding of the package for each and
-    every change, it is preferred to use a Virtual Machine for development. The
-    following example uses docker on a Debian host with a Debian Jessie image.
-    The steps are similar for other OSs; only the commands differ.
-    1. Install docker for your OS as per [official Docker installation docs](https://docs.docker.com/engine/installation).
-    2. Pulling a Debian Jessie image
-        ```
-        docker pull debian:jessie
-        ```
-    3. Running docker image with a shell prompt
-        ```
-        docker run -it debian:jessie bash
-        ```
-    This will cause the docker to run the jessie image and you will fall into a
-    bash prompt, where the following steps are applied to.
- 2. Install basic necessary tools
-    Basic tools used for developing Omnibus GitLab may be installed using the
-    following command
-    ```
-    sudo apt-get install git
-    ```
- 3. Getting GitLab CE nightly package and installing it
-    Get the latest GitLab CE nightly package (of the OS you are using) from
-    [Nightly Build repository](https://packages.gitlab.com/gitlab/nightly-builds)
-    and install it using the instructions given on that page. Once you configure
-    and start gitlab. Check if you can access it from your host browser on
-    \<ip address of host>
-    **`Note`**: Nightly packages versioning is incorrect which can cause a
-    confusion. This [issue is reported in #864](https://gitlab.com/gitlab-org/omnibus-gitlab/issues/864).
-    For the time being, consider the date of pushing (which is available next
-    to the package name in the repository page) to find the latest package version.
- 4. Getting source of Omnibus GitLab
-    Get the source code of Omnibus GitLab from the [repository on GitLab.com](https://gitlab.com/gitlab-org/omnibus-gitlab)
-    ```
-    git clone https://gitlab.com/gitlab-org/omnibus-gitlab.git ~/omnibus-gitlab
-    ```
-    We will be doing the development inside the `~/omnibus-gitlab` directory.
-
- 5. Instructing GitLab to apply the changes we make to the cookbooks.
-
-    During development, we need the changes we make to the cookbooks to be
-    applied immediately to the running GitLab instance. So, we have to instruct
-    GitLab to use those cookbooks instead of the ones shipped during
-    installation. This involves backing up of the existing cookbooks directory
-    and symlinking the directory where we make modifications to its location.
-
-    ```
-    sudo mv /opt/gitlab/embedded/cookbooks/gitlab /opt/gitlab/embedded/cookbooks/gitlab.$(date +%s)
-    sudo ln -s ~/omnibus-gitlab/files/gitlab-cookbooks/gitlab /opt/gitlab/embedded/cookbooks/gitlab
-    ```
-
-  6. Docker container specific items
-
-     Before running `reconfigure`, you need to start runsv.
-
-     ```
-     /opt/gitlab/embedded/bin/runsvdir-start &
-     ```
-
-     After running `reconfigure`, you may have sysctl errors. There is a workaround in the [common installation problems doc](../common_installation_problems/README.md#failed-to-modify-kernel-parameters-with-sysctl).
-
-Now, you can make necessary changes in the
-`~/omnibus-gitlab/files/gitlab-cookbooks/gitlab` folder and run `sudo gitlab-ctl reconfigure`
-for those changes to take effect.
-
-## Run GitLab QA Against Your Development Environment
-
-You can run [GitLab QA](https://gitlab.com/gitlab-org/gitlab-qa) tests against your development instance.
-
-This ensures that your new work is behaving as expected, and not breaking anything else. You can even add your own tests to QA to validate what you are working on.
-
-1. Create a user account on your development instance for GitLab QA to use
-
-   Then, from any machine that can reach your development instance:
-
-1. Clone the [GitLab EE](https://gitlab.com/gitlab-org/gitlab-ee) repository
-
-    ```
-    $ git clone git@gitlab.com:gitlab-org/gitlab-ee.git
-    ```
-
-1. Change to the `qa` directory
-
-    ```
-    $ cd gitlab-ee/qa
-    ```
-
-1. Install the required gems
-
-   ```
-   $ bundle install
-   ```
-
-1. Run the tests
-
-   ```
-   $ GITLAB_USERNAME=$USERNAME GITLAB_PASSWORD=$PASSWORD bundle exec bin/qa Test::Instance $DEV_INSTANCE_URL
-   ```
-
-## Openshift GitLab Development Setup
-
-See [openshift/README.md.](openshift/README.md#development-setup)
+# Omnibus GitLab developer documentation
+- [Development Setup](setup.md)
+- [Omnibus GitLab Architecture](../architecture/README.md)
+- [Adding a new Service to Omnibus GitLab](new-services.md)
+- [Creating patches](creating-patches.md)
+- [Release process](../release/README.md)
+- [Building your own package](../build/README.md)
+- [Building a package from a custom branch](../build/README.md#building-a-package-from-a-custom-branch)
+- [Adding deprecation messages](adding-deprecation-messages.md)
+## Setting up development environment
+Check [setting up development environment docs](setup.md) for
+instructions on setting up a environment for local development.
+## Understanding the architecture
+Check the [architecture documentation](../architecture/README.md) for an full description
+of the various components of this project, and how they work together.
+## Writing tests
+Any change in the internal cookbook also requires specs. Apart from testing the
+specific feature/bug, it would be greatly appreciated if the submitted Merge
+Request includes more tests. This is to ensure that the test coverage grows with
+development.
+When in rush to fix something (eg. security issue, bug blocking the release),
+writing specs can be skipped. However, an issue to implement the tests
+**must be** created and assigned to the person who originally wrote the code.
+To run tests, execute the following command (you may have to run `bundle install` before running it)
+```
+bundle exec rspec
+```
+## Merge Request Guidelines
+If you are working on a new feature or an issue which doesn't have an entry on
+Omnibus GitLab's issue tracker, it is always a better idea to create an issue
+and mention that you will be working on it as this will help to prevent
+duplication of work. Also, others may be able to provide input regarding the
+issue, which can help you in your task.
+It is preferred to make your changes in a branch named \<issue
+number>-\<description> so that merging the request will automatically close the
+specified issue.
+A good Merge Request is expected to have the following components, based on
+their applicability:
+ 1. Full Merge Request description explaining why this change was needed
+ 2. Code for implementing feature/bugfix
+ 3. Tests, as explained in [Writing Tests](#writing-tests)
+ 4. Documentation explaining the change
+ 5. If Merge Request introduces change in user facing configuration, update to [gitlab.rb template](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/files/gitlab-config-template/gitlab.rb.template)
+ 6. Changelog entry to inform about the change, if necessary.
+**`Note:`** Ensure shared runners are enabled for your fork in order for our automated tests to run.[^1]
+[^1]:
+  1. Go to Settings -> CI/CD
+  1. Expand Runners settings
+  1. If shared runners are not enabled, click on the button labeled "Enable shared Runners"

doc/development/setup.md

+# Setting up your development environment
+
+Development of Omnibus GitLab maybe done using an existing package available
+from [Downloads page](https://about.gitlab.com/downloads). To know how to setup
+a build environment to build these packages and use them, please read [Setting
+up a Build Environment](../build/prepare-build-environment.md).
+
+ 1. Setup a VM
+
+    To provide isolation and to prevent rebuilding of the package for each and
+    every change, it is preferred to use a Virtual Machine for development. The
+    following example uses docker on a Debian host with a Debian Jessie image.
+    The steps are similar for other OSs; only the commands differ.
+    1. Install docker for your OS as per [official Docker installation docs](https://docs.docker.com/engine/installation).
+
+    2. Pulling a Debian Jessie image
+
+        ```
+        docker pull debian:jessie
+        ```
+
+    3. Running docker image with a shell prompt
+
+        ```
+        docker run -it debian:jessie bash
+        ```
+    This will cause the docker to run the jessie image and you will fall into a
+    bash prompt, where the following steps are applied to.
+
+ 2. Install basic necessary tools
+
+    Basic tools used for developing Omnibus GitLab may be installed using the
+    following command
+
+    ```
+    sudo apt-get install git
+    ```
+
+ 3. Getting GitLab CE nightly package and installing it
+
+    Get the latest GitLab CE nightly package (of the OS you are using) from
+    [Nightly Build repository](https://packages.gitlab.com/gitlab/nightly-builds)
+    and install it using the instructions given on that page. Once you configure
+    and start gitlab. Check if you can access it from your host browser on
+    \<ip address of host>
+
+    **`Note`**: Nightly packages versioning is incorrect which can cause a
+    confusion. This [issue is reported in #864](https://gitlab.com/gitlab-org/omnibus-gitlab/issues/864).
+    For the time being, consider the date of pushing (which is available next
+    to the package name in the repository page) to find the latest package version.
+
+ 4. Getting source of Omnibus GitLab
+
+    Get the source code of Omnibus GitLab from the [repository on GitLab.com](https://gitlab.com/gitlab-org/omnibus-gitlab)
+
+    ```
+    git clone https://gitlab.com/gitlab-org/omnibus-gitlab.git ~/omnibus-gitlab
+    ```
+
+    We will be doing the development inside the `~/omnibus-gitlab` directory.
+
+ 5. Instructing GitLab to apply the changes we make to the cookbooks.
+
+    During development, we need the changes we make to the cookbooks to be
+    applied immediately to the running GitLab instance. So, we have to instruct
+    GitLab to use those cookbooks instead of the ones shipped during
+    installation. This involves backing up of the existing cookbooks directory
+    and symlinking the directory where we make modifications to its location.
+
+    ```
+    sudo mv /opt/gitlab/embedded/cookbooks/gitlab /opt/gitlab/embedded/cookbooks/gitlab.$(date +%s)
+    sudo ln -s ~/omnibus-gitlab/files/gitlab-cookbooks/gitlab /opt/gitlab/embedded/cookbooks/gitlab
+    ```
+
+  6. Docker container specific items
+
+     Before running `reconfigure`, you need to start runsv.
+
+     ```
+     /opt/gitlab/embedded/bin/runsvdir-start &
+     ```
+
+     After running `reconfigure`, you may have sysctl errors. There is a workaround in the [common installation problems doc](../common_installation_problems/README.md#failed-to-modify-kernel-parameters-with-sysctl).
+
+Now, you can make necessary changes in the
+`~/omnibus-gitlab/files/gitlab-cookbooks/gitlab` folder and run `sudo gitlab-ctl reconfigure`
+for those changes to take effect.
+
+## Run GitLab QA Against Your Development Environment
+
+You can run [GitLab QA](https://gitlab.com/gitlab-org/gitlab-qa) tests against your development instance.
+
+This ensures that your new work is behaving as expected, and not breaking anything else. You can even add your own tests to QA to validate what you are working on.
+
+1. Create a user account on your development instance for GitLab QA to use
+
+   Then, from any machine that can reach your development instance:
+
+1. Clone the [GitLab EE](https://gitlab.com/gitlab-org/gitlab-ee) repository
+
+    ```
+    $ git clone git@gitlab.com:gitlab-org/gitlab-ee.git
+    ```
+
+1. Change to the `qa` directory
+
+    ```
+    $ cd gitlab-ee/qa
+    ```
+
+1. Install the required gems
+
+   ```
+   $ bundle install
+   ```
+
+1. Run the tests
+
+   ```
+   $ GITLAB_USERNAME=$USERNAME GITLAB_PASSWORD=$PASSWORD bundle exec bin/qa Test::Instance $DEV_INSTANCE_URL
+   ```
+
+## Openshift GitLab Development Setup
+
+See [openshift/README.md.](openshift/README.md#development-setup)