Skip to content
Snippets Groups Projects
Unverified Commit 30a33c62 authored by Balasankar C's avatar Balasankar C
Browse files

Expanding documentation 

Expanding documentation on how to contribute effectively to GitLab and
how to setup a development environment.
parent 9fd1fe7d
No related branches found
No related tags found
1 merge request!1117Expand documentation for development contributors
Hide whitespace changes
Inline Side-by-side
CONTRIBUTING.md
+ 41
− 7
View file @ 30a33c62
These are the contributing guidelines for omnibus-gitlab issues and merge
requests.
 
## General guidelines
## General issue guidelines
 
If you are experiencing problems during GitLab package installation or have issues with package configuration please create an issue that includes the following:
 
@@ -16,12 +16,6 @@ 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.
 
## Merge request guidelines
- Please add a CHANGELOG entry for your contribution
- Have a look at the [development tips and tricks](doc/development/README.md)
## Maintainer documentation
 
### Issue description templates
@@ -63,3 +57,43 @@ problem is fixed or is no longer valid. If you still experience the same problem
try upgrading to the latest version. If the issue persists, reopen this issue
with the relevant information.
```
## 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.
### 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.
doc/build/README.md
+ 2
− 65
View file @ 30a33c62
# Preparing a build environment
 
See
https://gitlab.com/gitlab-org/gitlab-omnibus-builder/blob/master/README.md#recipe-default
for instructions on how to prepare a build box using Chef. After running the
cookbook you can perform builds as the `gitlab_ci_multi_runner` user.
```shell
# Ubuntu/Debian only: ensure you have proper locale available
sudo locale-gen en_US.UTF-8
# Login as build user
sudo su - gitlab_ci_multi_runner
# Set git author
git config --global user.email "email@example.com"
git config --global user.name "Example name"
# Ensure you have proper locale in the environment
export LC_ALL=en_US.UTF-8
# Clone the omnibus repo
git clone https://gitlab.com/gitlab-org/omnibus-gitlab.git
# Install gem dependencies for omnibus-ruby
cd omnibus-gitlab
bundle install --path .bundle --binstubs
# Do a build
bin/omnibus build gitlab
```
See [Preparing a Build Environment page](doc/build/prepare-build-environment.md)
for instructions on how to prepare build environment using Docker.
 
## Usage
 
*Important note* omnibus-gitlab project is used to build official GitLab
packages. These packages are also used to deploy GitLab.com.
The build tools are optimised for internal GitLab Inc infrastructure.
For example, omnibus-gitlab project will pull GitLab and dependent projects
code from internal dev.gitlab.org server. The internal server hosts the same
copy of the source code available elsewhere. Alternative source location is
necessary in case of an unforeseen circumstances.
All repositories used for building the packages that are not publicly reachable,
have their remotes listed in `.custom_sources.yml` file in the root of this
project.
If you are using these tools to build your own packages, you will have to
adjust them to your needs.
At the time of writing, an example of a fully public config for `.custom_sources.yml`
would look like this:
```
gitlab-rails:
remote: "https://gitlab.com/gitlab-org/gitlab-ce.git"
gitlab-rails-ee:
remote: "https://gitlab.com/gitlab-org/gitlab-ee.git"
gitlab-shell:
remote: "https://gitlab.com/gitlab-org/gitlab-shell.git"
gitlab-workhorse:
remote: "https://gitlab.com/gitlab-org/gitlab-workhorse.git"
gitlab-pages:
remote: "https://gitlab.com/gitlab-org/gitlab-pages"
config_guess:
remote: "git://git.savannah.gnu.org/config.git"
omnibus:
remote: "https://gitlab.com/gitlab-org/omnibus.git"
```
### Build
 
You create a platform-specific package using the `build` command:
doc/build/prepare-build-environment.md 0 → 100644
+ 85
− 0
View file @ 30a33c62
# Setting up a build environment
Omnibus GitLab provides docker images for all the OS versions that it
supports and these are available in the
[Container Registry](https://gitlab.com/gitlab-org/omnibus-gitlab/container_registry).
Users can use these images to setup the build environment. The steps are as
follows
1. Install docker. Visit [official docs](https://docs.docker.com/engine/installation)
for more details.
2. Login to GitLab's registry
You need a GitLab.com account to use the GitLab.com's container registry.
Login to the registry using the command given below. Provide your username
and password (you will have to create a
[personal access token](https://docs.gitlab.com/ce/api/README.html#personal-access-tokens_)
and use it instead of password, if you have enabled 2FA), when prompted.
**Note:** Please keep in mind that your password/personal access token will
be stored in the file `~/.docker/config.json`.
```
docker login registry.gitlab.com
```
3. Pull the docker image for the OS you need to build package for
Omnibus GitLab registry contains images for all the supported OSs and
versions. You can use one of them to build a package for it. For example,
to prepare a build environment for Debian Jessie, you have to pull its
image.
```
docker pull registry.gitlab.com/gitlab-org/omnibus-gitlab:jessie
```
4. Start the container and enter its shell
```
docker run -it registry.gitlab.com/gitlab-org/omnibus-gitlab:jessie bash
```
5. Clone the Omnibus GitLab source and change to the cloned directory
```
git clone https://gitlab.com/gitlab-org/omnibus-gitlab.git ~/omnibus-gitlab
cd ~/omnibus-gitlab
```
6. Omnibus GitLab is optimized to use the internal repositories from
dev.gitlab.org. This is specified in the `.custom_sources.yaml` file in the
root of the source tree and these repositories are not publicly usable. So,
for personal builds, you have to use public alternatives of these repos.
An example `.custom_sources.yaml` file would be as follows. Edit the file
and make necessary changes.
```
gitlab-rails:
remote: "https://gitlab.com/gitlab-org/gitlab-ce.git"
gitlab-rails-ee:
remote: "https://gitlab.com/gitlab-org/gitlab-ee.git"
gitlab-shell:
remote: "https://gitlab.com/gitlab-org/gitlab-shell.git"
gitlab-workhorse:
remote: "https://gitlab.com/gitlab-org/gitlab-workhorse.git"
gitlab-pages:
remote: "https://gitlab.com/gitlab-org/gitlab-pages"
config_guess:
remote: "git://git.savannah.gnu.org/config.git"
omnibus:
remote: "https://gitlab.com/gitlab-org/omnibus.git"
```
7. Install the dependencies and generate binaries
```
bundle install --path .bundle --binstubs
```
8. Run the build command to initiate a build process
```
bin/omnibus build gitlab
```
You can see the results of the build in the `pkg` folder at the root of the
source tree.
doc/development/README.md
+ 62
− 33
View file @ 30a33c62
# Setting up your development environment
 
# Development process
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](doc/build/prepare-build-environment.md).
 
## Testing
1. Setup a VM
 
Any change in the internal cookbook also requires specs.
It would be greatly appreciated if with any MR submitted, apart from testing
the specific feature/bug, more tests are written to increase the test coverage.
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. Installing docker
 
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 that originally wrote the code.
```
sudo apt-get install docker
```
 
2. Pulling a Debian Jessie image
 
# Development setup
```
docker pull debian:jessie
```
 
To avoid building the packages for every change you do during development, it
is useful to setup a VM on which you can develop.
3. Running docker image with a shell prompt
 
Once you get the VM running, download the package from
`https://about.gitlab.com/downloads/` and using the directions there finish the
package installation.
```
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.
 
Once the package is installed, navigate to `/opt/gitlab/embedded/cookbooks` and
rename the `gitlab` directory which holds the internal omnibus-gitlab cookbook.
2. Install basic necessary tools
 
```
sudo mv /opt/gitlab/embedded/cookbooks/gitlab /opt/gitlab/embedded/cookbooks/gitlab.$(date +%s)
```
Basic tools used for developing Omnibus GitLab may be installed using the
following command
 
Clone the omnibus-gitlab repository from
`https://gitlab.com/gitlab-org/omnibus-gitlab.git` to a known location, for
example your home directory.
```
sudo apt-get install git
```
 
```
git clone https://gitlab.com/gitlab-org/omnibus-gitlab.git ~/omnibus-gitlab
```
3. Getting GitLab CE nightly package and installing it
 
Once the repository is cloned symlink the cookbook in the omnibus-gitlab
repository, for example:
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>
 
```
sudo ln -s ~/omnibus-gitlab/files/gitlab-cookbooks/gitlab /opt/gitlab/embedded/cookbooks/gitlab
```
4. Getting source of Omnibus GitLab
 
Now you can do the changes in the omnibus-gitlab repository, try the changes
right away and contribute back to 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
```
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.
 
## Openshift GitLab Development Setup
 
See See [doc/development/openshift/README.md.](doc/development/openshift/README.md#development-setup)
See [doc/development/openshift/README.md.](doc/development/openshift/README.md#development-setup)
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment