From ca5490f9747b81e6c06dd783b46682275c4598a4 Mon Sep 17 00:00:00 2001 From: Marton Kiss Date: Thu, 28 Aug 2014 21:38:07 +0200 Subject: [PATCH] Contribution guide draft Initial version of Community portal contribution guide. Change-Id: I7acb3cde22f905ec4ae8379fa8990266a447cd3e --- groups-portal-contrib-guide.md | 199 +++++++++++++++++++++++++++++++++ 1 file changed, 199 insertions(+) create mode 100644 groups-portal-contrib-guide.md diff --git a/groups-portal-contrib-guide.md b/groups-portal-contrib-guide.md new file mode 100644 index 0000000..21ad286 --- /dev/null +++ b/groups-portal-contrib-guide.md @@ -0,0 +1,199 @@ +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: + + '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 +https://wiki.openstack.org/wiki/How_To_Contribute + +[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 +https://wiki.openstack.org/wiki/Gerrit_Workflow \ No newline at end of file