acsoo - Acsone Odoo Dev Tools
=============================

.. image:: https://img.shields.io/badge/license-GPL--3-blue.svg
   :target: http://www.gnu.org/licenses/gpl-3.0-standalone.html
   :alt: License: GPL-3
.. image:: https://badge.fury.io/py/acsoo.svg
    :target: http://badge.fury.io/py/acsoo
.. image:: https://travis-ci.org/acsone/acsoo.svg?branch=master
   :target: https://travis-ci.org/acsone/acsoo
.. image:: https://codecov.io/gh/acsone/acsoo/branch/master/graph/badge.svg
  :target: https://codecov.io/gh/acsone/acsoo

This is a set of command-line utilities to facilitate
the Odoo development workflow at Acsone.

It assumes the project is a setuptools-based python package
that can be packaged and installed with pip.

.. contents::

Criteria for tools to be included here:

* being small wrappers around standard commands (``git``, ``pip``, etc)
* yet being sufficiently non-trivial to be error-prone or time consuming when done manually
* being used across several Acsone Odoo projects

Installation
~~~~~~~~~~~~

  .. code:: shell

    pip install acsoo

.. note::

   Since ``acsoo`` has a lot of dependencies that are not required at runtime, it
   is not recommanded to install it in the same virtualenv as your project.
   A good approach is to install it in it's own virtual env and symlink the ``acsoo``,
   ``mrbob`` and ``bumpversion`` executables somewhere in your PATH.
   By the way, `pipsi <https://github.com/mitsuhiko/pipsi>`_ is an interesting way to manage
   such python scripts without polluting your system.

To enable bash completion, add this line in your ``.bashrc``:

  .. code:: shell

     eval "$(_ACSOO_COMPLETE=source acsoo)"

What we have here
~~~~~~~~~~~~~~~~~

Below, the list of available commands with a few examples.

Use ``acsoo --help`` or ``acsoo <command> --help`` for more information.

Initialize a new project
------------------------

  .. code:: shell

    mrbob acsoo:templates/project
    cd {project name}
    mkvirtualenv {project name} -a .

acsoo tag
---------

Tag the current project after ensuring everything has been commited to git.

acsoo tag_requirements
----------------------

Tag all VCS requirements found in ``requirements.txt``, so
the referenced commits are not lost in case of VCS garbage collection.

acsoo wheel
-----------

Build wheels for all dependencies found in ``requirements.txt``,
plus the project in the current directory.

This is actually almost trivial (ie ``pip wheel -r requirements.txt -e .``),
but works around a pip quirk.

acsoo release
-------------

Perform ``acsoo tag``, ``acsoo tag_requirements`` and
``acsoo wheel`` in one command.

acsoo flake8
------------

Run `flake8 <https://pypi.python.org/pypi/flake8>`_ with sensible default for Odoo code.

It is possible to pass additional options to the ``flake8`` command, eg:

  .. code:: shell

    acsoo flake8 -- --ignore E24,W504

acsoo pylint
------------

Run `pylint <https://pypi.python.org/pypi/pylint>`_ on detected Odoo addons in odoo/addons,
odoo_addons or the current directory.
It automatically uses the `pylint-odoo <https://pypi.python.org/pypi/pylint-odoo>`_ plugin and
runs with a reasonable configuration, including an opinionated set of disabled message.

It is possible to pass additional options to the ``pylint`` command, eg:

  .. code:: shell

    acsoo pylint -- --disable missing-final-newline

This command returns an non-zero exit code if any message is reported.
It is however possibly to display messages while reporting success, eg:

  .. code:: shell

    acsoo pylint --expected api-one-deprecated:2,line-too-long

The above command succeeds despite having exactly 2 ``api-one-deprecated`` or
any number of ``line-too-long`` messages being reported.

It is also possible to force failure on messages that are ``expected`` in the
default configuration, eg to fail on ``fixme`` errors, just expect 0 ``fixme`` messages, like this:

  .. code:: shell

    acsoo pylint --expected fixme:0

acsoo addons
------------

A set of commands to print addons lists, useful when running tests.

  .. code:: shell

     acsoo addons list
     acsoo addons list-depends

acsoo checklog
--------------

Check if an odoo log file contains error, with the possibility to ignore some
errors based on regular expressions.

  .. code:: shell

     acsoo checklog odoo.log
     odoo -d mydb -i base --stop-after-init | acsoo checklog
     acsoo checklog --ignore "WARNING.*blah" odoo.log

bumpversion
-----------
Bumpversion is a software automatically installed with acsoo. It allows you to increment or simply change the version of the project in several files at once, including acsoo.cfg.

  .. code:: shell

    bumpversion {part}

Where part is 'major', 'minor' or 'patch' (see `semantic versioning <http://semver.org/>`_).

Configure bumpversion by editing the .bumpversion.cfg config file at the root of your project.
See the bumpversion `documentation <https://pypi.python.org/pypi/bumpversion>`_ to go further (automatic commit, tag, customisation...).

Ideas
~~~~~

acsoo freeze
------------

``pip freeze`` (which works very well as is) with the following additions

* exluding some common dev tools that are not required in production
  (pudb, ipdb, acsoo, git-aggregator, setuptools-odoo...)
  and their dependencies unless such dependencies are required by the project
  (directly or indirectly).
* excluding the project itself (as usual for python requirements.txt files)

Inspiration to be found in https://pypi.python.org/pypi/pipdeptree, although I don't
think acsoo should depend on that, as it's only a thin wrapper around the ``pip`` api.

Useful links
~~~~~~~~~~~~

- pypi page: https://pypi.python.org/pypi/acsone
- code repository: https://github.com/acsone/acsoo
- report issues at: https://github.com/acsone/acsoo/issues

Maintainer
~~~~~~~~~~

.. image:: https://www.acsone.eu/logo.png
   :alt: ACSONE SA/NV
   :target: https://www.acsone.eu

This project is maintained by ACSONE SA/NV.

Changes
~~~~~~~

.. Future (?)
.. ----------
.. -

1.5.0 (2017-09-19)
------------------
- [IMP] tag_requirements: fetch more aggressively; this solves the errors
  trying to write ref with non existent object
- [IMP] tag: always tag requirements when doing acsoo tag
- [IMP] tag: tag requirements before tagging project, so if something fails
  when tagging the requirements the project is not tagged and the release 
  build is not triggered.
- [ADD] addons: add --separator option (and fix tests that were not testing much)
- [IMP] addons: consider current dir as addons dir candidate
- [IMP] pylint: look for module to test in current dir by default, using the
  same algorithm as ``addons list``
- [IMP] pylint: support python 3 style odoo/addons namespace (without __init__.py)

1.4.3 (2017-06-16)
------------------
- [IMP] checklog: consider ignore lines starting with # as comments
- [FIX] checklog: the previous release broke checklog color output

1.4.2 (2017-06-16)
------------------
- [IMP] checklog: fail if no log record found in input
- [IMP] checklog: echo with click to be less sensitive to unicode issues

1.4.1 (2017-06-14)
------------------
- [FIX] regression in acsoo release

1.4.0 (2017-06-13)
------------------
- [IMP] colored logging
- [IMP] major change to acsoo tag and tag_editable_requirements. These changes
  make it easier to work with a CI-driven release process that is triggered on
  new tags. The usual manual ``acsoo release`` process should be mostly unimpacted by
  these changes.

  - ``tag_editable_requirements`` is now ``tag_requirements``.
  - the tags structure has changed from ``{series}-{trigram}_{version}`` to
    ``{series}-{trigram}-{req_sha}-{egg}``, where ``{req_sha}`` is the sha of the
    last change to ``requirements.txt``.
  - ``tag_requirements`` includes the egg name in the tag so different commits
    in the same repo can be tagged (before, all addons in a given dependency repo had
    to be on the same commit).
  - when a tag for the given series, trigram and egg already exists on the
    dependency commit, ``tag_requirements`` does not attempt to create another
    tag (this avoids creating useless tags or forced tags) and
    this is sufficient because the sole purpose of these dependency tags is
    to avoid commits to be garbage collected.
  - ``acsoo tag`` now invokes ``tag_requirements``. In most cases however this
    will not place additional tags on dependencies, because the normal workflow
    is to invoke ``tag_requirements`` as soon as ``requirements.txt`` is updated.
  - ``tag_requirements`` automatically transforms http(s) urls into ssh urls
    for the purpose of pushing tags. This allows to maximize the use of http(s)
    urls in requirements so CI and scripts do not require ssh access
    to the public dependencies. This currently only works for the acsone organization
    on github but the mechanism is easy to extend, should the need arise.

1.3.0 (2017-06-04)
------------------
- [IMP] flake8: read additional ``flake8-options`` in acsoo configuration file.
- [IMP] template: series-dependent odoo command in ``.gitlab.ci.yml``.
- [IMP] template: createdb in ``.gitlab-ci.yml`` because Odoo 8 does not do it by itself.
- [ADD] addons list-depends: ``--exclude`` option

1.2.2 (2017-05-30)
------------------
- [FIX] regression in ``tag``, ``tag_editable_requirements`` and ``release`` commands.

1.2.1 (2017-05-27)
------------------
- [IMP] add possibility to provide main config file as option.
- [IMP] checklog: read default options from ``[checklog]`` section of config file.
- [IMP] pylint: read default options from ``[pylint]`` section of config file.
- [IMP] pylint: the module or package to lint may be provided with ``-m``.
- [IMP] flake8: read default options from ``[flake8]`` section of config file.
  The only option so far is ``config`` to provide an alternate flake8
  configuration file. This is useful so developer only need to type
  ``acsoo flake8`` locally, even when a specific configuration is needed,
  so it's trivial to run locally with the same config as in CI.

1.1.0 (2017-05-25)
------------------
- [IMP] pylint: BREAKING the package to test must be provided explicitly,
  as soon as additional pylint options are provided,
  so as to enable easy local testing of a subset of a project. Examples:
  ``acsoo pylint -- -d some-message odoo``, ``acsoo pylint -- odoo.addons.xyz``;
- [IMP] pylint: disable more code complexity errors: ``too-many-nested-blocks``,
  ``too-many-return-statements``.
- [IMP] pylint: display messages causing failure last, so emails from CI.
  that show the last lines of the log are more relevant.
- [IMP] pylint: display summary of messages that did not cause failure, also
  when there is no failure.
- [ADD] ``acsoo addons list`` and ``acsoo addons list-depends``.
- [ADD] ``acsoo checklog``.

1.0.1 (2017-05-21)
------------------
- First public release.


