Browse Source

Merge "Contribution guide draft"

changes/38/121138/1
Jenkins 4 years ago
parent
commit
150c345cdd
1 changed files with 199 additions and 0 deletions
  1. 199
    0
      groups-portal-contrib-guide.md

+ 199
- 0
groups-portal-contrib-guide.md View File

@@ -0,0 +1,199 @@
1
+OpenStack Groups Portal Contribution Guide
2
+=============================================
3
+
4
+The Groups Portal based on Drupal 7.x [1] and Drupal Commons [2] distribution, and
5
+the entire development process is integrated into the OpenStack CI system
6
+including the code-review and automatic deployment of development and production
7
+branch. If you want to contribute back a new portal feature or just simply
8
+resolve a bug it is very important to setup a local development environment
9
+with proper application stack to match the environment of staging and production
10
+servers and avoid a lot's of unwanted issues. As we are using the OpenStack CI
11
+the contribution process exactly match the official way [3], so this paper contains
12
+additional project specific details.
13
+
14
+Prerequisites
15
+-------------
16
+
17
+The Groups Portal production and development currently based on the following
18
+application stack:
19
+
20
+- Ubuntu 12.04 LTS
21
+- Apache 2.2.22
22
+- MySQL database server 5.5.38
23
+- PHP 5.3.10 (extensions: mysql, gd)
24
+- Drush 6.0
25
+- Git
26
+- Git-review
27
+- Compass
28
+
29
+Development workflow
30
+--------------------
31
+
32
+## Install site from scratch ##
33
+
34
+As the first step of the development workflow we need to prepare an empty
35
+database, register a drush site alias, clone the site source code from
36
+git repository and finally install the site into an apache vhost docroot
37
+directory.
38
+
39
+### Create a mysql database ###
40
+
41
+Create a new mysql database and grant permissions:
42
+
43
+    $ mysqladmin -u username -p create groupsdev
44
+    $ mysql -u username -p
45
+    $ GRANT ALL ON groupsdev.* TO groupsdev@'localhost' IDENTIFIED BY 'urs3cr3tpassw0rd';
46
+
47
+Where groupsdev will be the user name and urs3cr3tpassw0rd will be the password.
48
+
49
+### Define drush site alias ###
50
+
51
+Drush alias helps to shorten the access of local or remote Drupal installation.
52
+For example you can set an alias as a default site root with `drush use @sitealias`
53
+command.
54
+
55
+The alias files must be placed in the global /etc/drush/aliases.drushrc.php or
56
+in the local ~/.drush/aliases.drushrc.php files.
57
+
58
+Example aliases.drushrc.php configuration:
59
+
60
+    <?php
61
+    $aliases['groupsdev'] = array(
62
+      'uri' => 'groups-dev.local',
63
+      'root' => '/var/www/groups-dev.local',
64
+      'db-url' => 'mysql://groupsdev:12345678@localhost/groupsdev',
65
+      'databases' => array(
66
+        'default' => array(
67
+          'driver' => 'mysql',
68
+          'username' => 'groupsdev',
69
+          'password'  => 'urs3cr3tpassw0rd',
70
+          'port' => '',
71
+          'host' => 'localhost',
72
+          'database' => 'groupsdev',
73
+        ),
74
+      ),
75
+    );
76
+
77
+Further alias configuration examples available here [4].
78
+
79
+Query available site aliases:
80
+
81
+    $ drush sa
82
+    @groupsdev
83
+    default
84
+
85
+### Build a working copy ###
86
+
87
+The Groups Portal based on a Drupal Installation Profile, it means we are
88
+keeping only the portal related modules in the git repository, and define all
89
+of the original Drupal contributed modules and their patches in make files. The
90
+drupal-org-core.make contains the defintion of Drupal core distribution and the
91
+required core patches, the drupal-org.make file includes the defintion of
92
+contrib modules, patches, themes and libraries.
93
+
94
+Fetch the git repository and clone a working copy, then build the distribution
95
+into site vhost directory:
96
+
97
+    $ git clone git://git.openstack.org/openstack-infra/groups groups
98
+    $ cd groups
99
+    $ bash scripts/dev-build.sh /var/www/groups-dev.local
100
+
101
+The /var/www/groups-dev.local is the site root registered in your apache
102
+vhost file, this can be different in your local environment.
103
+
104
+### Install Groups portal ###
105
+
106
+    $ drush use @groupsdev
107
+    $ drush si groups -y
108
+    $ drush features-revert-all -y
109
+    $ drush cc all
110
+
111
+Now the portal available at your local site url, for example at
112
+`http://groups-dev.local`.
113
+
114
+### Rebuild theme css files ###
115
+
116
+    $ cd /var/www/groups-dev.local/profiles/groups/themes/openstack
117
+    $ bundle exec compass compile
118
+
119
+## Import contents ##
120
+
121
+The default installation will come with a really minimal content set, so
122
+we need to import some initial content for testing.
123
+
124
+### Import user group data ###
125
+
126
+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
127
+through openstack-infra/groups-static project.
128
+
129
+    $ drush import-user-groups
130
+
131
+### Import static pages content ###
132
+
133
+The static pages are holding markdown formatted content, during development
134
+clone to a local directory from openstack-infra/groups-static-pages repository
135
+and don't forget to set the groups_feeds_markdown_directory variable to
136
+specify the location of the files
137
+
138
+    $ git://git.openstack.org/openstack-infra/groups-static-pages /var/www/groups-static-pages
139
+    $ drush vset groups_feeds_markdown_directory /var/www/groups-static-pages
140
+    $ drush import-static-pages
141
+
142
+### Import meetup events ###
143
+
144
+The meetup events can be imported directly from meetup.com calendars, and
145
+related user group meetup.com location extracted from meetup attribute of the
146
+uploaded user group content.
147
+
148
+    $ drush import-meetup-events
149
+
150
+## Submit a patch ##
151
+
152
+Start with low-hanging fruits and first try to fix a small bug or
153
+do some housekeeping. The entire code-space maintained by the Groups
154
+Portal team lives under the profiles/groups directory. If you like
155
+to change anything, add a new drupal module, create a new feature,
156
+you must place the files there. It is very important to know that
157
+Drupal 7 store a lot of configuration setting, variable in database
158
+and to make the code portable, we need to move those settings out
159
+to code, using the Features module [5].
160
+
161
+Follow the development workflow of OpenStack [6] and post
162
+your patches to gerrit code review system.
163
+
164
+    $ git checkout -b TOPIC-BRANCH
165
+    $ git commit -a
166
+    $ git review
167
+
168
+Example commit message:
169
+
170
+    Security upgrade of core and date module
171
+    
172
+    Update Drupal Core to 7.30 and Date module to 2.8.
173
+    Related release notes available here:
174
+    https://www.drupal.org/drupal-7.30-release-notes
175
+    https://www.drupal.org/node/231188
176
+    Change-Id: Ia2d04322fff4bc1f49e8cccada2ac2b267a3f9ca
177
+
178
+After execution of successful jenkins check jobs, you need to get a
179
+manual approval from project owners. If everything works well your
180
+approved code will be automatically deployed into
181
+groups-dev.openstack.org staging site.
182
+
183
+[1] Drupal Core
184
+https://www.drupal.org/project/drupal
185
+
186
+[2] Drupal Commons
187
+https://www.drupal.org/project/commons
188
+
189
+[3] OpenStack How To Contribute
190
+https://wiki.openstack.org/wiki/How_To_Contribute
191
+
192
+[4] Drush alias examples
193
+http://drush.ws/examples/example.aliases.drushrc.php
194
+
195
+[5] Drupal Features module
196
+https://www.drupal.org/project/features
197
+
198
+[6] Gerrit workflow
199
+https://wiki.openstack.org/wiki/Gerrit_Workflow

Loading…
Cancel
Save