# Note on deprecations
A tick-tock release cycle allows easy migration to new software versions.
Obsolete code is marked as deprecated for one major release.
Deprecated code produces compile-time warnings. These warning serve as
notification to users that their code should be upgraded. The next major
release will remove the deprecated code.

## Ignition Gazebo 4.x to 5.x

* Use `cli` component of `ignition-utils1`.

* `ignition::gazebo::RenderUtil::SelectedEntities()` now returns a
  `const std::vector<Entity> &` instead of forcing a copy. The calling code
  should create a copy if it needs to modify the vector in some way.

* Default generated topic name for thermal cameras now includes the `/image`
  suffix. The `camera_info` topic has also been fixed to include the sensor
  name in the generated topic string. The naming scheme should be consistent
  with a normal camera sensor. Topic changes:
    * `/<prefix>/<sensor_name>` -> `/<prefix>/<sensor_name>/image`
    * `/<prefix>/camera_info` -> `/<prefix>/<sensor_name>/camera_info`

* Various `GuiEvent`s were deprecated in favor of their Ignition GUI
  equivalents.
  * **Deprecated** `ignition::gazebo::gui::SnapIntervals`
  * **Replacement** `ignition::gui::SnapIntervals`
  * **Deprecated** `ignition::gazebo::gui::Render`
  * **Replacement** `ignition::gui::Render`
  * **Deprecated** `ignition::gazebo::gui::SpawnPreviewModel`
  * **Replacement** `ignition::gui::SpawnFromDescription`
  * **Deprecated** `ignition::gazebo::gui::SnapPreviewPath`
  * **Replacement** `ignition::gui::SnapFromPath`

* The `<direction>` tag of spot lights was previously not parsed by the
  scene, so all spot lights shone in the direction corresponding to the
  default `0 0 -1`. Since 5.x, the `<direction>` tag is correctly
  processed.

## Ignition Gazebo 4.0.0 to 4.X.X

* Ignition Gazebo 4.0.0 enabled double sided material by default but this
caused shadow artifacts to appear on some meshes. Double sided material is
now disabled and made an opt-in feature. Users can configure this property
in SDF by setting the `<visual><material><double_sided>` SDF element.

## Ignition Gazebo 3.x to 4.x

* The `RenderUtil::SetEnabledSensors` callback in gazebo rendering has a new
  required function argument for the Entity of the sensor.
    * ***Removed***
      `public: void SetEnableSensors(bool, std::function<
          std::string(const sdf::Sensor &, const std::string &)>)`
    * ***Replacement***
      `public: void SetEnableSensors(bool, std::function<
          std::string(const gazebo::Entity &,
          const sdf::Sensor &, const std::string &)>)`

* Log playback using `<path>` SDF parameter is removed. Use --playback command
  line argument instead.

* `rendering::SceneManager`
    * **Deprecated**: `Entity EntityFromNode(const rendering::NodePtr &_node) const;`
    * **Replacement**: `Entity entity = std::get<int>(visual->UserData("gazebo-entity"));`

## Ignition Gazebo 2.x to 3.x

* Use ign-rendering3, ign-sensors3 and ign-gui3.

## Ignition Gazebo 1.x to 2.x

* Changed component data types:
    * `Altimeter` now uses `sdf::Sensor`
    * `JointVelocity` now uses `std::vector<double>`

* Deprecated components:
    * `JointVelocity2`: use `JointVelocity`'s vector instead.

* The `--distributed` command line argument has been deprecated. Use
  `--network-role` instead.

* The `-f`/`--file` command line argument has been deprecated. The SDF
  file can now be loaded without a flag.

* The `ign-gazebo` command line tool is deprecated. The new tool is
  `ign gazebo`, which has all the same options, except for
  `--distributed` and `--file`/`-f`, which have been removed.

* The `entity_name` field in the messages published by the imu system is
updated to report its scoped name.

* Log files generated from Ignition Gazebo 1.X are no longer compatible with
Gazebo 2+ for playback. [BitBucket pull request
#257](https://osrf-migration.github.io/ignition-gh-pages/#!/ignitionrobotics/ign-gazebo/pull-requests/257)
added an SDF message to the start of log files.

* Log playback using `<path>` SDF parameter is deprecated. Use `--playback`
  command line argument instead.

## Ignition Gazebo 1.0.2 to 1.1.0

* All headers in `gazebo/network` are no longer installed.

* The ignition-gazebo1-gui library has been changed to a `gui` component of
ignition-gazebo. To use the gui component downstream, update the find package
call in cmake to request for the component, e.g.
`ign_find_package(ignition-gazebo1 REQUIRED COMPONENTS gui)`, and link to the
`libignition-gazebo1::gui` target instead of `libignition-gazebo1-gui`
