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
==========

It is recommended to use Virtualenv__ as a development Python environment.

Necessary development dependencies can be installed with::

    pip install -r requirements-dev.txt

RIDE uses Invoke__ (version 0.13 or newer) as it's task runner. Packaging, testing, and running a
development version without installation can all be done using Invoke.
Run::

    invoke --list

for more information.

Most often command is::

    invoke devel

__ https://pypi.python.org/pypi/virtualenv
__ http://www.pyinvoke.org


wxPython
--------
Version 2.8.12.1 of wxPython__ was the last for the 2 series.
Together with version 3.0.2, they are called the wxPython Classic.

The current recommended version of wxPython is 4.0.7.post2 and was called wxPhoenix.
RIDE is not fully compatible with newest wxPython 4.1.

RIDE on Python 2.7 still runs with any version of those Classic or wxPhoenix.
On Python 3.6+, only wxPhoenix is supported (and in the future we will only
support those).

**VERSION 1.7.4.2 IS THE LAST RELEASE SUPPORTING PYTHON 2.7 AND WXPYTHON <3.0.3**

**wxPython will be updated to current version 4.0.7.post2**

For testing purposes, users can select which version to use, by creating the
file ``wx.pth`` containing the directory name of the wxPython to use. That 
directory must contain the two wxPython directories (moved into)::

    ls  -cF /usr/lib/python2.7/site-packages/wx-4.0.7
    wxPython-4.0.7.dist-info/
    wx/    
 
Example::

    type C:\\Python27\\Lib\\site-packages\\wx.pth
    # 
    wx-2.8-msw-unicode
    # wx-3.0-msw
    # wx-4.0.2
    # wx-4.0.3
    # wx-4.0.4
    # wx-4.0.6
    # wx-4.0.7


It is highly recommended, if you want to program with wxPython to download and
run its ``demo``. We need your programming skils on this project, talk with Hélio Guilherme.

__ https://wxpython.org

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::

  invoke test

There is also a shell script (requiring customization for your environment).
It allows to run the test files stopping when errors are found.
Example::

    ./test_all.sh utest/namespace   # to test with python3 and namespace dir

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`).


 http://www.python.org/dev/peps/pep-0008/


Releasing
=========

* Release early and often!
* **Consider making a preview release** - this will give you possibility to test the new release with friendly real users
* Manually test run RIDE in windows, linux and OSX
* Primary distribution channel is PyPi.
* Following steps are needed for a final release. Updating release notes plugin is optional for pre-releases::

  > invoke clean
  > invoke test
  > invoke version 1.xx

* Release notes in markdown format can be created with::

  > invoke release-notes

* Prepare source package::

  > invoke sdist --upload
  > git commit -am 'Version 1.xx'
  > git tag 1.xx
  > git push --tags


Creating distributions
----------------------

(borrowed from https://github.com/robotframework/robotframework/blob/master/BUILD.rst)

1. Checkout the earlier created tag if necessary::

      git checkout v$VERSION

   This isn't necessary if continuing right after `tagging <https://github.com/robotframework/robotframework/blob/master/BUILD.rst#tagging>`_.

2. Cleanup (again). This removes temporary files as well as ``build`` and
   ``dist`` directories::

      invoke clean

3. Create and validate source distribution in zip format and universal (i.e.
   Python 2 and 3 compatible) `wheel <http://pythonwheels.com>`_::

      python setup.py sdist --formats zip bdist_wheel --universal
      ls -l dist
      twine check dist/*

   Distributions can be tested locally if needed.

4. Upload distributions to PyPI::

      twine upload dist/*

5. Verify that project pages at `PyPI
   <https://pypi.python.org/pypi/robotframework-ride>`_ look good.

6. Test installation::

      pip install --pre --upgrade robotframework-ride


* Announce on usergroup, robot homepage, forum, slack, 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.
