Merge pull request #284 from digidentity/add-howto-to-readme

Add howto to readme and convert roadmap into limitations

README.md

@@ -9,30 +9,37 @@
 
 ### Requirements
 
-GitLab CI is designed for the Linux operating system.
-
 GitLab CI officially supports (recent versions of) these Linux distributions:
 
 * Ubuntu Linux
 * Debian/GNU Linux
 
 Additionally GitLab CI requires:
 
+* GitLab 6.0+
 * ruby 1.9.3
 * MySQL or PostgreSQL
 
-This version (3.x) is designed for GitLab 5.3+.
+__If you want to use GitLab CI without GitLab or with older versions of GitLab you need to use [2-2-stable](https://github.com/gitlabhq/gitlab-ci/tree/2-2-stable#gitlab-ci-is-an-open-source-continuous-integration-server)__
+
+### Limitations
 
-__If you want to use GitLab CI without GitLab or with older versions you need to use [2-2-stable](https://github.com/gitlabhq/gitlab-ci/tree/2-2-stable#gitlab-ci-is-an-open-source-continuous-integration-server)__
+The following features are not in GitLab CI but merge requests are very welcome:
 
-### How it works
+* Email notification
+* API documentation
+* Increase test coverage (the goal is to be above 85%)
+* Build artifacts access
+* Build pipeline / build promotion actions
 
-__GitLab CI__ is a web application with API and connect to db. 
-It manage projects/builds and provide a nice user interface. 
-It uses GitLab application to authenticate users.
+### Architecture
 
-__GitLab CI Runner__ is a pure ruby application which process builds.
-It can be deployed separately and work with GitLab CI through API.
+__GitLab CI__ is a web application with an API and it connect to the db.
+It manage projects/builds and provides a nice user interface.
+It uses the GitLab application API to authenticate users.
+
+__GitLab CI Runner__ is a pure ruby application which processes builds.
+It can be deployed separately and works with GitLab CI through an API.
 
 In order to run tests you need at least 1 __GitLab CI__ instance and 1 __GitLab CI Runner__.
 However, for running several builds at the same time you may want to setup more than one __GitLab CI Runner__.
@@ -45,18 +52,36 @@ Possible Cases:
 
 ![screen](https://raw.github.com/gitlabhq/gitlab-ci/master/app/assets/images/arch.jpg)
 
-The runner runs the line below and then runs the commands in your projects settings
-
-    cd /gitlab-ci-runner/tmp/builds && git clone git@gitlab_server_fqdn:group/project.git project-1 && cd project-1 && git checkout master
-
 For more information see:
 [Announcing GitLab CI 3.0](http://blog.gitlab.org/announcing-gitlab-ci-3.0/)
 and
 [Integrating GitLab CI With GitLab to Enable Distributed Builds](http://blog.gitlab.org/integrating-gitlab-ci-with-gitlab/)
 
 ### Installation
 
-* [Installation and setup guide](https://github.com/gitlabhq/gitlab-ci/blob/master/doc/installation.md)
+* [Installation guide](https://github.com/gitlabhq/gitlab-ci/blob/master/doc/installation.md)
+
+### How to add a new project to GitLab CI
+
+1. Log in the GitLab CI web interface
+2. Press the 'Sync now' button
+3. Select your project with the 'Add' button
+4. Go the the Integration page and do the 'Complete (as service)' steps
+5. Go to the settings page to add a build script (see below for an example)
+6. Push a new commit to the project
+7. If the build fails then adjust the build script and press the 'Retry' button on the build page
+8. If the build is green you are done, all new commits will be tested and you see the status of merge requests builds within GitLab
+
+For your information, the runner runs the line below before it runs the commands in your build script:
+
+    cd /gitlab-ci-runner/tmp/builds && git clone git@gitlab_server_fqdn:group/project.git project-1 && cd project-1 && git checkout master
+
+Build script example:
+
+    bundle install
+    bundle exec rake db:create RAILS_ENV=test
+    bundle exec rake db:migrate RAILS_ENV=test
+    script/run_all_tests
 
 ### Getting help
 

doc/installation.md

@@ -1,7 +1,3 @@
-# Requirements:
-
-* GitLab 5.3+
-
 # Setup: 
 
 ## 1. Packages / Dependencies