Skip to content

Commit

Permalink
Merge pull request #111 from hpcugent/develop
Browse files Browse the repository at this point in the history
update docs to 20150327.01
  • Loading branch information
boegel committed Mar 27, 2015
2 parents becb015 + 54dfc6a commit 303ed06
Showing 3 changed files with 38 additions and 3 deletions.
3 changes: 3 additions & 0 deletions docs/Changelog.rst
Original file line number Diff line number Diff line change
@@ -3,6 +3,9 @@
Changelog for EasyBuild documentation
-------------------------------------

* **release 20150327.01** (`Mar 27th 2015`):

* documented deprecated functionality w.r.t. error reporting (see :ref:`depr_error_reporting`)
* **release 20150316.01** (`Mar 16th 2015`):

* include list of EasyBuild repositories cloned by ``install-EasyBuild-develop.sh`` script
36 changes: 34 additions & 2 deletions docs/Deprecated-functionality.rst
Original file line number Diff line number Diff line change
@@ -34,11 +34,43 @@ For authors of easyconfig files:

For developers of easyblocks:

*(nothing yet)*
* :ref:`depr_error_reporting`

For EasyBuild framework developers:

*(nothing yet)*
* :ref:`depr_error_reporting`

.. _depr_error_reporting:

Report errors by raising ``EasyBuildError`` rather than using log methods
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

**Use of the** ``error()`` **and** ``exception()`` **log methods is deprecated.**

* *deprecated since:* EasyBuild v2.1.0 (April'15)
* *removed in:* EasyBuild v3.0
* *alternative(s)*: **use** ``raise EasyBuildError(...)`` **instead**

The ``error()`` and ``exception()`` log methods defined by EasyBuild (in the ``easybuild.tools.build_log`` module)
do not match the semantics of the `standard Python log methods
<https://docs.python.org/2/library/logging.html#logging.Logger.error>`_, in the sense that they also raise an
exception next to logging messages.

This may cause problems when 3rd party libraries (e.g., `gc3pie <https://pypi.python.org/pypi/gc3pie>`_) are being
used by EasyBuild, since they may be using these log methods without expecting an exception being raised.

The custom definitions for the ``error()`` and ``exception()`` log methods will be removed in EasyBuild v3.0.

Hence, these log methods should no longer be used to report errors since they will not raise an exception anymore once
their custom definitions are removed. Note that this applies both to the EasyBuild framework and to (custom) easyblocks.

To report errors, an ``EasyBuildError`` should be raised instead. For example:

.. code::
# make sure config.sh script is there
if not os.path.exists(os.path.join(self.builddir, 'config.sh')):
raise EasyBuildError("config.sh script is missing in %s", self.builddir)
.. _deprecation_policy:

2 changes: 1 addition & 1 deletion docs/conf.py
Original file line number Diff line number Diff line change
@@ -43,7 +43,7 @@
# The short X.Y version.
version = '2.0.0' # this is meant to reference the version of EasyBuild
# The full version, including alpha/beta/rc tags.
release = '20150316.01' # this is meant to reference the version of the documentation itself
release = '20150327.01' # this is meant to reference the version of the documentation itself

# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:

0 comments on commit 303ed06

Please sign in to comment.