groups-static-pages/groups-portal-contrib-guide.md

title	path
OpenStack Groups Portal Contribution Guide	contribute

OpenStack Groups Portal Contribution Guide

The Groups Portal based on Drupal 7.x [1] and Drupal Commons [2] distribution, and the entire development process is integrated into the OpenStack CI system including the code-review and automatic deployment of development and production branch. If you want to contribute back a new portal feature or just simply resolve a bug it is very important to setup a local development environment with proper application stack to match the environment of staging and production servers and avoid a lot's of unwanted issues. As we are using the OpenStack CI the contribution process exactly match the official way [3], so this paper contains additional project specific details.

Prerequisites

The Groups Portal production and development currently based on the following application stack:

• Ubuntu 12.04 LTS
• Apache 2.2.22
• MySQL database server 5.5.38
• PHP 5.3.10 (extensions: mysql, gd)
• Drush 6.0
• Git
• Git-review
• Compass

Development workflow

Install site from scratch

As the first step of the development workflow we need to prepare an empty database, register a drush site alias, clone the site source code from git repository and finally install the site into an apache vhost docroot directory.

Create a mysql database

Create a new mysql database and grant permissions:

$ mysqladmin -u username -p create groupsdev
$ mysql -u username -p
$ GRANT ALL ON groupsdev.* TO groupsdev@'localhost' IDENTIFIED BY 'urs3cr3tpassw0rd';

Where groupsdev will be the user name and urs3cr3tpassw0rd will be the password.

Define drush site alias

Drush alias helps to shorten the access of local or remote Drupal installation. For example you can set an alias as a default site root with drush use @sitealias command.

The alias files must be placed in the global /etc/drush/aliases.drushrc.php or in the local ~/.drush/aliases.drushrc.php files.

Example aliases.drushrc.php configuration:

<?php
$aliases['groupsdev'] = array(
  'uri' => 'groups-dev.local',
  'root' => '/var/www/groups-dev.local',
  'db-url' => 'mysql://groupsdev:12345678@localhost/groupsdev',
  'databases' => array(
    'default' => array(
      'driver' => 'mysql',
      'username' => 'groupsdev',
      'password'  => 'urs3cr3tpassw0rd',
      'port' => '',
      'host' => 'localhost',
      'database' => 'groupsdev',
    ),
  ),
);

Further alias configuration examples available here [4].

Query available site aliases:

$ drush sa
@groupsdev
default

Build a working copy

The Groups Portal based on a Drupal Installation Profile, it means we are keeping only the portal related modules in the git repository, and define all of the original Drupal contributed modules and their patches in make files. The drupal-org-core.make contains the defintion of Drupal core distribution and the required core patches, the drupal-org.make file includes the defintion of contrib modules, patches, themes and libraries.

Fetch the git repository and clone a working copy, then build the distribution into site vhost directory:

$ git clone git://git.openstack.org/openstack-infra/groups groups
$ cd groups
$ bash scripts/dev-build.sh /var/www/groups-dev.local

The /var/www/groups-dev.local is the site root registered in your apache vhost file, this can be different in your local environment.

Install Groups portal

$ drush use @groupsdev
$ drush si groups -y
$ drush features-revert-all -y
$ drush cc all

Now the portal available at your local site url, for example at http://groups-dev.local.

Rebuild theme css files

$ cd /var/www/groups-dev.local/profiles/groups/themes/openstack
$ bundle exec compass compile

Import contents

The default installation will come with a really minimal content set, so we need to import some initial content for testing.

Import user group data

The user group data located at https://git.openstack.org/cgit/openstack-infra/groups-static-pages/tree/groups.json file, so you can easily modify or contribute back modification through openstack-infra/groups-static project.

$ drush import-user-groups

Import static pages content

The static pages are holding markdown formatted content, during development clone to a local directory from openstack-infra/groups-static-pages repository and don't forget to set the groups_feeds_markdown_directory variable to specify the location of the files

$ git://git.openstack.org/openstack-infra/groups-static-pages /var/www/groups-static-pages
$ drush vset groups_feeds_markdown_directory /var/www/groups-static-pages
$ drush import-static-pages

Import meetup events

The meetup events can be imported directly from meetup.com calendars, and related user group meetup.com location extracted from meetup attribute of the uploaded user group content.

$ drush import-meetup-events

Submit a patch

Start with low-hanging fruits and first try to fix a small bug or do some housekeeping. The entire code-space maintained by the Groups Portal team lives under the profiles/groups directory. If you like to change anything, add a new drupal module, create a new feature, you must place the files there. It is very important to know that Drupal 7 store a lot of configuration setting, variable in database and to make the code portable, we need to move those settings out to code, using the Features module [5].

Follow the development workflow of OpenStack [6] and post your patches to gerrit code review system.

$ git checkout -b TOPIC-BRANCH
$ git commit -a
$ git review

Example commit message:

Security upgrade of core and date module

Update Drupal Core to 7.30 and Date module to 2.8.
Related release notes available here:
https://www.drupal.org/drupal-7.30-release-notes
https://www.drupal.org/node/231188
Change-Id: Ia2d04322fff4bc1f49e8cccada2ac2b267a3f9ca

After execution of successful jenkins check jobs, you need to get a manual approval from project owners. If everything works well your approved code will be automatically deployed into groups-dev.openstack.org staging site.

[1] Drupal Core https://www.drupal.org/project/drupal

[2] Drupal Commons https://www.drupal.org/project/commons

[3] OpenStack How To Contribute http://docs.openstack.org/infra/manual/developers.html

[4] Drush alias examples http://drush.ws/examples/example.aliases.drushrc.php

[5] Drupal Features module https://www.drupal.org/project/features

[6] Gerrit workflow http://docs.openstack.org/infra/manual/developers.html#development-workflow