================
Migrating to 1.0
================

If your project uses ska-tango-base, please refer to the full migration guide for 
`ska-tango-base release 1.0.0 
<https://developer.skao.int/projects/ska-tango-base/en/latest/releases/migrating-to-1.0.html>`_ - 
which includes the breaking change for ska-control-model 1.0.0, since ska-tango-base
and ska-control-model are so tightly coupled. If your project only uses ska-control-model, 
here follows the PyTango update and breaking change to :obj:`~ska_control_model.AdminMode`.

PyTango dependency
------------------

ska-control-model 1.0.0 requires PyTango >= 9.4.2 < 10.0.0.  
This is due to a combination of two reasons:

* The Tango event system does not work in between Kubernetes namespaces for
  PyTango versions before 9.4.2.
* The PyTango releases 9.3.x are more difficult to work with because the
  Tango collaboration do not provide wheels for them.

Although ska-control-model 1.0.0 supports PyTango 9.4.2, it is recommended to update
to the latest PyTango 9.5.1.

It is possible to update both ska-control-model to 1.0.0 and PyTango to 9.5.1
simultaneously, and it is expected that this will be straight forward for most
packages.  See the `PyTango migration guide
<https://pytango.readthedocs.io/en/latest/versions/migration/index.html>`_
for help updating.

AdminMode.MAINTENANCE has been removed
--------------------------------------

The ska-control-model release 0.3.4 introduced the following changes:

- Replaced :obj:`!AdminMode.MAINTENANCE` with  :obj:`AdminMode.ENGINEERING <ska_control_model.AdminMode.ENGINEERING>`.
- Replaced the :class:`~ska_control_model.AdminModeModel` action :code:`"to_maintenance"`  with :code:`"to_engineering"`.

These changes were introduced to avoid confusion with the DISH MAINTENANCE mode
(see SP-3868 for details).

To maintain backwards compatibility, ska-control-model 0.3.4 allowed for the use
of the old names :obj:`!AdminMode.MAINTENANCE` and :code:`"to_maintenance"`,
generating deprecation warnings on use.

With the ska-control-model release 1.0.0 :obj:`!AdminMode.MAINTENANCE` has been
removed as has the :code:`"to_maintenance"` action.  This might require changes
when updating to ska-control-model 1.0.0.

When updating you must replace any reference to :obj:`!AdminMode.MAINTENANCE`
with :obj:`AdminMode.ENGINEERING <ska_control_model.AdminMode.ENGINEERING>`.
Recall that :obj:`!AdminMode.MAINTENANCE` might be being referenced by a string
variable by either indexing or calling :class:`~ska_control_model.AdminMode`,
for example::

   mode_str = "MAINTENANCE"
   mode = AdminMode[mode_str]
   mode2 = AdminMode(mode_str)

In this example, :code:`mode_str` would need to be updated to
:code:`"ENGINEERING"`.  The deprecation warnings provided by ska-control-model
0.3.4 can help you track down these cases.

It is unlikely that your package is referencing the :code:`"to_maintenance"`
action of the :class:`ska_control_model.AdminModeModel`, but if it is you will
need to use :code:`"to_engineering"` instead.