BUILD
=====
This document describes the technical details of the RIDE project:
* How to build, run and test RIDE
* What's in the source
* How to contribute
* How to make a release
* Settings migrations
Developing
==========
RIDE uses Paver__ as it's build tool. Packaging, testing, and running a
development version without installation can all be done using Paver. Install
Paver and run::
paver help
for more information.
__ http://paver.github.com/paver
Repository contents
===================
Repository contains source code, unit tests, and some helper scripts for
development and package generation.
Source code
-----------
Source code is located in `src` directory. `src/bin` contains installed start
scripts and `src/robotide` contains the actual source code.
Unit tests
----------
Unit tests are in `utest` directory. They can be executed with::
paver test
Contributing
============
Fork and send a pull request! To enhance the possibility of getting the pull
request merged, read guidelines below.
Coding guidelines
=================
In general, all the code should be written according to Style Guide for Python
Code [5] However, as stated in the Zen of Python, practicality beats purity.
Method names
------------
Typically, we use `lowercase_with_underscore` style for method names. Of
course, when overriding wx methods, `AllCapitalized` style must be used.
Additionally, there's a special case when writing event handler methods. We
have chosen to name event handlers following this pattern: `OnEventName` (e.g.
`OnMouseClick`).
Variable names
--------------
Instance variables also follow the `lowercase_with_underscore` naming
convention. Additionally, a leading underscore indicates that the variable is
considered private.
Global variables (provided there's really a need for such) use `ALL_CAPS`
style.
Getters and setters
-------------------
We follow the Pythonic way of not implementing getters and setters in the case
where direct attribute access is sufficient
http://www.python.org/dev/peps/pep-0008/
Releasing
=========
TODO: These are incomplete
* Release early and often!
Currently (10.8.2012) RIDE is used in many differing environments by a rather large userbase (reported bugs per feature is 1.56 - compared to RF:s 0.75).
Thus simulating (testing) all the possible use cases is more or less impossible (NOTE: You should still try to test all the relevant cases).
We can still keep the user observed quality good by doing small changes at a time and reacting fast to any observed regressions.
This should efficiently limit the number of users that encounter a specific defect.
* Usually I try to do releases before lunch - this gives us some time to react to possible regressions during the release day
* Avoid releasing on Fridays! - lousy reaction time (or weekend work) if there is a regression
* Manually test run RIDE in windows, linux and OSX
* Update the ReleaseNotes with "python get_issues.py rotes ride 0.xx" (the script is from robotframework-wiki-project / tools)
::
> paver test
> paver set_version 0.xx
> paver sdist
> git commit -am 'Version 0.xx'
> git tag 0.xx
> git push
> git push --tags
* currently (10.8.2012) it seems that something creates garbage to development directory so I always take a new clone for distribution packages
::
> cd ..
> git clone [your local ride clone] ride-release
> cd ride-release
> git checkout 0.xx
> paver sdist OR paver wininst
> cd ..
* Upload new packages to github
* Register new packages to PyPI - the Python Package Index.
NOTE! RIDE automatic update notifier checks updates from PyPI - so no update notifications without this step.
::
> paver register
* Announce on usergroup, robot homepage, and twitter
Settings migration
==================
RIDE has a user specific configuration file that you usually don't need to worry about.
But sometimes old configurations should be changed during RIDE version update. For example when the old configuration
had a bug or new RIDE uses a differing kind of configuration parameter then the old version.
For these situations I've created a configuration migration system that can do these changes when a new version of RIDE is taken in to use.
The migrator is currenlty (10.8.2012) located at preferences/settings.py/SettingsMigrator.
The mechanism works in the following way:
* Settings have a settings_version attribute that should be updated when a new migration is needed
* the SettingsMigrator.migrate method should be updated so that it will also do the new migration
* You only need to add a migration from the previous version to current (the migrate method will handle all the older versions -
so only the last configuration delta is needed)
Hope this helps when persistent things change a lot.