|Version 3 (modified by mdehaan, 9 years ago) (diff)|
Welcome! We're excited you have interest in working on Func.
Whether through adding new features to the core, contributing new modules, coming up with new features, or fixing bugs, Func is a community project and is very interested in your contributions. This page provides some useful information to help you get started with git, the way the app is packaged, as well as some basic coding info kind of information.
In git, we currently work mostly on the main branch. At some point we may branch, but most development happens in head at the moment.
Read here for information on how to get the source.
Func is built with a combo of python distutils, makefiles, and packaging files (aka, rpm spec files)
The spec files and the make files both run setup.py to do most of the hardwork.
So changes that add or remove files or directories may need changes in setup.py, MANIFEST.in, and func.spec.
The version of func is set in a top level text file called "version". Package builds should try to pull the version out of there if possible.
Interested in writing modules?
Basically if you are just wanting to add modules to func to make it do new things you are most likely concerned with checkout/func/func/minion/modules directory, and you will want to add files there. Read this for more information about adding and distributing modules.
Patches to func should be sent to the mailing list as attachments. Because the version of mailman we are running is somewhat temperamental, be sure you also include some text in the body of the email. Patches should be generated with "git-format-patch" (see the manpage on that for further info). This is mostly equivalent to "diff -U 10" which will also work, though git-format-patch will allow you to work directly out of git, which is preferred.
The top level makefile has a number of convenience targets for development.
- make clean
- 'make clean' cleans up temporary files, detritus from previous build, editor backup files, etc.
- make build
- 'make build' runs the python setup.py. Basically analogous to a compilation step.
- make install
- 'make install' runs clean, build, and creates the manpages. It also runs the 'setup.py install'
- make clean_hard
- 'make clean_hard' runs 'make clean' as well as removing files install into site-packages
- make clean_harder
- 'make clean_harder' runs 'make clean_hard' as well as removing any certificates that have been created. Try this
if a build is getting ssl cert related errors.
- make clean_hardest
- 'make clean_hardest' removes any install func rpms
- make install_hardest
- 'make install_hardest' is a good way to test a "fresh install". It removes func from the system, rebuilds rpms, installs the rpms,
and restart the daemons.
- make testit
- 'make testit' runs test/test-it.sh.
- make pychecker and make pyflakes
- runs the corresponding python static checkers over the code
- make money
- 1. run sloccount, 2. ...., 3. profit
In the test/ subdirectory there are a couple of test scripts. They may be worth adding to if you write new modules or features and you want to be sure that future development does not break them.
test-it.sh is a shell script that tries to emulate doing a fresh install of func and running some basic tests against it. It removes any currently installed packages, backs up the certs, shuts down running versions, builds new versions from a fresh git checkout, installs them, starts up services, and runs the func commandline against the minion.
Note: you may want to add a line to your /etc/hosts to point "certmaster" to 127.0.0.1 for the test script.
There are unittests in func/tests/unittests. test-it.sh should be running these by default with the "nose" unit test framework. So you need the "python-nose" package installed to run the unittests.
Development Conventions =
We're not too picky, but a few things to keep people happy.
- use under_scores for methods, not CamelCase. CamelCase for classes is ok. Follow the general Python style stuff.
- use spaces, not tabs. 4-space indent is preferred.
- use pydoc for functions where relevant, but dont' make it all super-verbose and make it read like javadoc :)
- ensure you have the GPL header at the top of each file, also including your name and email for copyright
- keep things simple, and comment the hard things so other people can understand them
- avoid one line ifs and "deep" list comprehensions
- if you add a new module or feature, add it to the Wiki in the appropriate sections
- keep the manpage (pod files) updated when syntax changes for func or any other apps that live in /usr/bin, they live in "docs"
- run the tests after you add things and before you commit to make sure stuff is still working
- make sure everything you do can work on EL-4, as it's a goal of Func to support EL-4 and later. (So things must work on Python 2.3)
- if you're planning on something complex, it can't hurt to post about it on the mailing list first
Thanks very much for the interest in working on Func!