forked from fedora-infra/fas
-
Notifications
You must be signed in to change notification settings - Fork 0
/
HACKING
344 lines (247 loc) · 11.9 KB
/
HACKING
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
=================================
HACKING the Fedora Account System
=================================
:Authors: Adam M. Dutko
:Contact: [email protected]
:Date: Wed, 02 November, 2011
:For FAS version: 0.8.x
This file provides a guideline to new developers hacking on the Fedora Account System. It is not yet complete.
.. contents::
-------
Caveats
-------
Add specific directions for each Fedora release if there any and finish this file.
All Releases
============
Fedora 16 Caveats
=================
----------
PostgreSQL
----------
On F16 you'll need to initialize the PostgreSQL database as the user postgres and
not rely on the sysvinit script or service wrapper to do it for you. For example,
sudo su - postgres
initdb
exit
sudo systemctl start postgresql.service
On F16 be aware the pg_hba.conf file options are 'ident' and not 'ident sameuser'.
Fedora 15 Caveats
=================
----------
PostgreSQL
----------
On F15 you'll need to initialize the PostgreSQL database as the user postgres and
not rely on the sysvinit script or service wrapper to do it for you. For example,
sudo su - postgres
initdb
exit
sudo systemctl start postgresql.service
Fedora 14 Caveats
=================
On F14 you need to do the following until/unless the python-fedora change is released:
-- uninstall python-fedora if it is installed
-- yum erase python-fedora
-- yum install Django
-- yum install python-repoze-who-friendlyform
-- wget http://kojipkgs.fedoraproject.org/packages/python-fedora/0.3.25.1/1.fc14.1/noarch/python-fedora-0.3.25.1-1.fc14.1.noarch.rpm
-- rpm -ivh python-fedora-0.3.25.1-1.fc14.1.noarch.rpm
-------------
Prerequisites
-------------
Before you can get started hacking on the Fedora Account System (FAS) you will need to have a fedora account in the production instance of FAS. You will also need to complete the Contributor License Agreement (CLA). Once these things are done you will need to become a member of the FAS Git Commit group by first becoming an apprentice through Fedora Infrastructure then proving your competency (this is easier than it sounds so don't let it seem intimidating).
Alernatively, you can start hacking on FAS without commit access and submit patches to the mailing list:
You should use the mailing list and Internet Relay Chat (IRC) to ask questions about FAS. The IRC channel is #fedora-admin on the Freenode network (irc.freenode.net). You can access the FAS code base through git:
Anonymous checkout
git clone git://github.com/fedora-infra/fas.git
Committers checkout
git clone [email protected]:fedora-infra/fas.git
A github account is reequired here. Although, commit access requires some approvals and membership to the Fedora Infrastructure team.
Please stop by #fedora-apps (irc.freenode.net) if you have more question regarding this project.
You can view tickets, outstanding issues and more by visiting the Trac instance for FAS located at:
https://fedorahosted.org/fas/
Common Fedora Packages
======================
If you're developing on Fedora (good idea) you will need to use yum to install the packages required to run your FAS test instance:
yum install git-core postgresql-plpython postgresql-server postgresql-python \
python-TurboMail TurboGears pygpgme python-sqlalchemy python-genshi \
python-psycopg2 pytz python-babel babel python-GeoIP \
python-fedora python-migrate python-memcached python-tgcaptcha2 pyOpenSSL gettext
Please read the ''Caveats'' section for important caveats about particular releases.
Common RHEL Packages
====================
If you're developing on RedHat Enterprise Linux (RHEL) you will need to use yum to install the packages required to run your FAS test instance:
yum install git-core postgresql-pl postgresql-server postgresql-python \
python-TurboMail TurboGears pygpgme python-sqlalchemy python-genshi \
python-psycopg2 pytz python-babel babel python-GeoIP \
python-fedora python-migrate python-memcached python-tgcaptcha2 pyOpenSSL gettext
For RHEL5 (and above) please note the naming difference in the postgresql-plpython package. On RHEL5 (and above) this package is referred to as postgresql-pl instead of postgresql-plpython.
Database
========
FAS requires a database. The database must also be a postgres database since we use postgres specific triggers to manage some of the data (like syncing accounts with bugzilla). For help on this particular step, please refer to the INSTALL file located in the same directory as this file.
Installation Steps
==================
Before you start hacking you should follow the steps outlined in the INSTALL document to get your own development version of FAS running.
-------
HACKING
-------
Thank you for hacking on FAS! There are other pieces you can configure such as setting up Apache + mod_wsgi to serve FAS, adjusting settings, testing integration with other components and etc. Please read the INSTALL file for more information on these options.
NOTE: We strive to follow Python (PEP-8) style guidelines.
---------------
ENABLING OPENID
---------------
For OpenID support, run tg-admin -c fas.cfg sql create to create the OpenID tables.
----------------------------
Apache + mod_wsgi deployment
----------------------------
WSGI or, Web Server Gateway Interface is a specification to allow servers and
applications to communicate with each other. It's one method that allows Turbo
Gears to scale properly. To install it run:
# yum -y install httpd mod_wsgi
next create a configuration file in /etc/httpd/conf.d/accounts.conf with the
following information in it:
# File Start
WSGISocketPrefix /var/run/wsgi
# Repress TG's stdoutput
WSGIRestrictStdout On
# TG implements its own signal handler.
WSGIRestrictSignal Off
# These are the real tunables
WSGIDaemonProcess daemon processes=2 threads=2 maximum-requests=1000 user=fas display-name=fas inactivity-timeout=30
WSGIPythonOptimize 1
WSGIScriptAlias /accounts /path/to/turbogears/fas/fas.wsgi/accounts
<Directory /path/to/turbogears/fas/>
WSGIProcessGroup fas
Order deny,allow
Allow from all
</Directory>
#EOF
Finally edit fas.wsgi and add the proper values for your setup and start the
server with:
/etc/init.d/httpd start
--------------------
Enabling Local Users
--------------------
* THIS IS EXPERIMENTAL *
To allow local users to log in to your system, first enable fas via the
client in fas/client/fasClient.py
./fasClient -e
To disable run
./fasClient -d
To sync with your local install run:
./fasClient -i
To test, look and see if your groups or users show up with getent. For
example:
getent passwd
getent group
------------
Localization
------------
We use the translation services at transifex.net to manage po files, coordinate
people translating strings, and merge new strings to the files. The following
instructions briefly tell how to use transifex to update the source languages
files and pull new translations for release. Actually doing translations can
be found in the `transifex user's guide`_.
.. `transifex user's guide`:: http://help.transifex.net/user-guide/translating.html
To generate the POT file (located in the po/ subdirectory), run the
following from the top level directory::
pybabel extract -F pybabel.conf -o po/fas.pot fas/
Then upload this pot file to transifex::
tx push -s
To pull messages from transifex prior to making a release, do::
tx pull -a -f
Transifex will perform merging of strings for you.
To enable the languages in FAS, you must compile the PO files and places them
where TurboGears will look for them. Then you need to enable the language to
be available to users by adding it to fas.cfg.sample.
Remember that we commit to the git repo the pot file and the po files. We do
not commit mo files.
----------------
MAKING A RELEASE
----------------
1. Make sure that any feature branches you want have been merged.
2. If time allows, read and do the :id:`Getting Translated` section below.
3. Pull in new translations using tx pull -a -f. Add any new translations to
the fas.cfg.sample file. Commit the changes.
4. Update the version in fas.spec and fas/release.py. Commit the changes to
the master branch.
5. Make sure the NEWS file is up to date
6. Push the results to the server.
7. Make a fresh clone of the repository::
cd /var/tmp
git clone git://git.fedorahosted.org/git/fas
8. Make the source tarball in that directory::
cd /var/tmp/fas
python setup.py sdist
9. Make rpms from the tarball. You can use the koji dist-5E-epel-infra build
target for that::
mv dist/*.tar.gz .
rpmbuild-md5 -bs --nodeps fas.spec
koji build --scratch dist-5E-epel-infra fas*.src.rpm
10. Upload the tarball to fedorahosted. Copy the rpms from koji to the
infrastructure repository::
scp fas*tar.gz fedorahosted.org:/srv/web/releases/f/a/fas/
ssh puppet1
wget # all rpm files from the scratch build
rpm --addsign *.rpm
# Move rpms to the epel infrastructure dir
# createrepo the new repository
11. tag the release::
cd [LOCAL GIT REPO]
git tag [RELEASE VERSION NUMBER]
git push --tags
12. Install in staging and test.
13. Finally, upgrade the production fas servers.
Getting Translated
==================
If the release is not time critical, it's wise to get it translated prior to
release. Allow 8 to 10 days for this to happen.
1) Make sure that all the steps in :id:`Localization` are done.
2) Announce to the other committers (via
[email protected]) that we are in string freeze
preparatory to making a release. Explain that string freeze means that
changes and additions to the strings people see should not be done on the
main fas branch -- do such changes on a branch and merge it after the
release.
.. note:: We'd like to change the process here slightly -- create a test
instance of fas and deploy to that instead of staging. Then make the
translators admins of the test instance. That way they can see all of the
changes that they're making.
3) Email [email protected] that you're making a release. FAS is
halfway between upstream project and Fedora website so each translation
team there will update what they have the time to do. Include the following
information:
* The staging fas server can be looked at for the running code:
https://admin.stg.fedoraproject.org/accounts/
* Code can be viewed at http://git.fedorahosted.org/git/?p=fas.git;a=tree
* The date that you're going to release (Remember, you want it to be 8-10
days from this announcement)
* If you have the time to make daily, weekly, etc updates to stg to pull in
the new translations mention that so the translators know whether they can
expect to see their changes in a live environment or not.
4) When you make a new test release, be sure you remember the tx pull step from
above or you won't be pulling in the new translations. When you accept new
commits, be sure that there are no new strings. If new strings are
unavoidable in he fixing of a bug, email [email protected] to
make people aware of it.
5) When the release date arrives, spin the new release into an rpm as above
(remembering to run tx pull -a :-) and make the release.
-------
Plugins
-------
FAS2 has a plugin system for adding new functionality. There is a sample,
dummy plugin in the FAS2 install that you can try out and use as the basis
of your own plugins. Enabling it for testing currently requires a few
steps. When installed things will be much simpler::
cd plugins/dummy_plugin
python setup.py egg_info
cd ../
export PYTHONPATH=${PYTHONPATH}:`pwd`/dummy_plugin
cd ../
./start-fas
You should then be able to browse to::
http://localhost:8088/accounts/dummy
and see some simple output from the dummy plugin.
In a real install, the plugin will be installed to a directory already on your
PYTHONPATH (for instance, site-packages) so there won't be a need to set the
PYTHONPATH variable explicitly.