Changelog
#########

This document catalogs the changes to ``decree-tree``.

Versions
********

Some versions have been released, others not.

Unreleased
==========

In progress...

v0.3.0
======

This release includes several enhancements, bug fixes,
and documentation improvements, including but not limited to:

* Changed the interplay of subcommands and other command
  line options and arguments. Now a particular subcommand
  will only allow *either* its subcommands (and help option)
  *or* its own and inherited arguments and options. This
  avoids situations where arguments or options are
  specified and ignored, and improves help output.

* Defined a custom argument parser class:
  :class:`~decree_tree.parser.ModifiedArgumentParser`.
  At present, its only difference from
  `its parent in argparse <https://docs.python.org/3/library/argparse.html#argumentparser-objects>`__
  is that it
  :meth:`~decree_tree.parser.ModifiedArgumentParser.parse_known_args`
  now errors on unrecognized arguments. This ensures that
  help usage statements for unexpected arguments are as specific
  as possible for the chosen subcommand. A different parser
  class can be substituted by specifying
  :attr:`~decree_tree.DecreeTree.argument_parser_class`
  directly or via an argument to
  :meth:`~decree_tree.DecreeTree.run`.

* Implemented the :meth:`~decree_tree.DecreeTree.debug_print`
  method for optionally printing debug information.
  Printing is controlled by
  :attr:`~decree_tree.DecreeTree.debug_tracing`,
  and can be specified as an argument to
  :meth:`~decree_tree.DecreeTree.run`. Internally,
  ``debug_tracing`` is propagated to children via
  :meth:`~decree_tree.DecreeTree.set_debug_tracing`.

* Defined :attr:`~decree_tree.DecreeTree.exec_obj_opt`,
  which facilitates renaming of the hidden option indicating
  the selected subcommand. This can help avoid name clashes.
  This attribute is propagated via the new
  :meth:`~decree_tree.DecreeTree.set_options` method.

* Added a flag to :meth:`~decree_tree.DecreeTree.parser_options`
  to indicate whether its the options are applied to a
  subparser or a top-level parser.

* Defined :meth:`~decree_tree.DecreeTree.repr_kwargs` to
  control the arguments displayed in the output
  from :meth:`~decree_tree.DecreeTree.__repr__`.

* Split :meth:`~decree_tree.DecreeTree.configure_parser`
  from :meth:`~decree_tree.decree.Decree.configure_parser`
  to improve separation of concerns.

* Transitioned ``pyproject.toml`` to use a PEP-621 style.
  `Poetry <https://python-poetry.org/>`__ is still used
  for defining developmental dependencies.

* Included coverage summary in local developmental test
  output.

* Fixed some linting and test failures, including in docstrings.

* Updated, expanded, and clarified documentation, particularly
  for configuration, development, and command nesting.

* Added support for documentation source code links based on the
  `sphinx.ext.linkcode <https://www.sphinx-doc.org/en/master/usage/extensions/linkcode.html>`__
  extension.

This version was manually pushed to PyPI and the documentation
site, as the CI pipeline was still under development.

v0.2.0
======

This release includes several substantial refactorings
and enhancements, including but not limited to:

* Renamed ``TreeContainer`` class to
  :class:`~decree_tree.tree.Tree`, changed it to
  use a generic type var, and moved its definition to a
  separate module.

* Renamed :class:`~decree_tree.DecreeTree` methods to
  consistently refer to the *parent*
  or *child*, retaining helper methods
  :meth:`~decree_tree.DecreeTree.add` and
  :meth:`~decree_tree.DecreeTree.get`
  in :class:`~decree_tree.DecreeTree`.

* Clarified that :meth:`~decree_tree.DecreeTree.add_arguments`
  modifies its parser argument,
  not directly a class or instance variable.

* Ensured that :meth:`~decree_tree.DecreeTree.run` can be
  executed from non-root commands in the assembled tree.

* Improved arguments to :meth:`~decree_tree.DecreeTree.__init__`,
  along with creating
  :meth:`~decree_tree.DecreeTree.__str__` and
  :meth:`~decree_tree.DecreeTree.__repr__` methods. This removes the
  ``prog_or_name`` argument to :meth:`~decree_tree.DecreeTree.__init__`,
  replacing it with ``name`` and ``prog_is_name``.

* Changed the ``summary()`` method into the
  :attr:`~decree_tree.DecreeTree.structure` property
  and improved its output.

* Created the :class:`~decree_tree.extras.AbstractDT` class
  to facilitate abstract :class:`~decree_tree.DecreeTree`
  inheritance.

* Removed :class:`~decree_tree.decreeDecree` class from
  the top level of package import.

* Changed the inheritance behavior of commands, including from
  abstract parent classes and manual tree association, and
  the ``inherit`` class initialization argument.

* Enhanced customization of parsers with
  :meth:`~decree_tree.DecreeTree.parser_options`
  and :meth:`~decree_tree.DecreeTree.subparsers_options`.

* Improved typing throughout the package, with a goal of clear
  documentation and IDE hinting.

* Greatly expanded the test suite, reaching greater than 90%
  coverage.

* Created extensive documentation, including embedded tests.

* Started use of GitLab CI for testing and package building.

* Lowered the minimum version required for the
  `typing-extensions <https://github.com/python/typing_extensions>`__
  package.

This version was manually pushed to PyPI and the documentation
site, as the CI pipeline was still under development.

v0.1.0
======

The first working version of the tool. Still
in a developmental state, this version was not
released as a package.

v0.0.0
======

The initial commit, tagged for posterity.