Changelog
#########

This document catalogs the changes to ``decree-tree``.
Some versions have been released, others not.

Unreleased
**********

In progress...

v0.4.0
******

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

* Fixed the attribute check for a populated parser in
  :meth:`~decree_tree.DecreeTree.run`. This avoids
  rebuilding the parser on every call even when it had
  already been configured.

* Ensured that an empty namespace can be passed to the
  ``options`` parameter in
  :meth:`~decree_tree.decree.Decree.preprocess_options`.

* Changed :meth:`~decree_tree.DecreeTree.repr_kwargs` to
  raise :exc:`RuntimeError` rather than :exc:`KeyError`
  when unexpected keyword argument keys are detected.

* Added a ``raise_exception`` parameter to
  :meth:`~decree_tree.tree.Tree.remove_child`. By default the
  method silently does nothing when the named child does not
  exist. Passing ``raise_exception=True`` causes
  :exc:`~decree_tree.base.InvalidName` to be raised instead.

* Updated :class:`~decree_tree.parser.ModifiedArgumentParser`
  to use :class:`~collections.abc.Iterable` instead of
  :class:`~collections.abc.Sequence` in the type signature of
  :meth:`~decree_tree.parser.ModifiedArgumentParser.parse_known_args`,
  matching an update to the upstream ``argparse`` type
  annotations.

* Documented MRO ordering requirements for mixin classes.
  Placing a mixin *after* :class:`~decree_tree.DecreeTree` in
  the MRO (e.g. ``class MyCommand(DecreeTree, MyMixin)``) is
  not supported, as :class:`~decree_tree.DecreeTree` relies on
  cooperative inheritance in ways that prevent mixins in that
  position from contributing behaviour reliably. Mixins should
  be placed *before* :class:`~decree_tree.DecreeTree`
  (e.g. ``class MyCommand(MyMixin, DecreeTree)``), which is
  also the conventional Python ordering for mixins.

* Split the CI test job into a matrix of per-interpreter jobs,
  using separate images for each supported Python version rather
  than using a single multi-python container for invoking ``tox``.

* Simplified the tox configuration by using wildcard
  environment patterns, reducing the number of explicit
  environment listings in ``pyproject.toml``.

* Added dependency locking to development and CI environments.
  ``poetry.lock`` and ``pylock.toml`` are now committed to the
  repository, ensuring reproducible dependency resolution
  across local development and CI runs.

* Configured trusted publishing of the package to
  `PyPI <https://pypi.org/project/decree-tree/>`__ and
  `TestPyPI <https://test.pypi.org/project/decree-tree/>`__
  using OIDC. Separate CI jobs handle tag-triggered releases to
  PyPI and branch-triggered releases to TestPyPI, each
  authenticating with a GitLab-issued OIDC token rather than a
  stored credential.

* Added automated documentation publishing via CI.
  Documentation is built and pushed to the documentation site
  on every commit to the default branch and on every version
  tag. After each push, a downstream pipeline in the
  documentation repository is triggered automatically to deploy
  the updated content.

* Added automated release creation for version tags. A
  dedicated CI job creates a GitLab release for each tag,
  including a changelog excerpt drawn from the main docs and
  links to the documentation site and the PyPI package page.

* Added Cobertura XML coverage reports and JUnit test result
  files as CI artifacts, enabling per-line coverage display
  in merge request diffs and test-result visualization within
  GitLab.

* Disabled publish jobs in pipelines running in forked
  repositories. Jobs that push packages or documentation are
  guarded by a namespace check and do not run outside the
  originating project, preventing accidental publication
  attempts from forks.

* Synchronized with v0.3.0 of the elasmocalc-copier-template.
  This included restructuring ``pyproject.toml`` to align
  with updated template conventions, adding a ``conftest.py``
  for shared test configuration, updating ``.gitignore``
  patterns, and refreshing other project scaffolding files.

* Updated development package dependency versions.

* Several other minor code, test, CI, and documentation improvements.

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.