doc: Add better examples for "updating dependencies"

Author: sgillespie

CONTRIBUTING.rst

@@ -149,32 +149,94 @@ project.  The most important thing to note is that we pin the ``index-state`` of
 the Hackage package index in ``cabal.project``.  This means that cabal will
 always see Hackage “as if” it was that time, ensuring reproducibility.  But it
 also means that if you need a package version that was released *after* that
-time, you need to bump the ``index-state`` (and to run ``cabal update``
-locally).
+time, you need to bump the ``index-state``.
+
+Run ``cabal update`` locally::
+
+  cabal update
+
+  Downloading the latest package lists from:
+  - hackage.haskell.org
+  - cardano-haskell-packages
+  ...
+  Package list of hackage.haskell.org has been updated.
+  The index-state is set to 2024-06-26T15:03:35Z.
+
+Copy the value of the index-state int ``cabal.project``::
+
+  index-state:
+  , hackage.haskell.org 2024-06-26T15:03:35Z
 
 Because of how we use Nix to manage our Haskell build, whenever you do this you
 will also need to pull in the Nix equivalent of the newer ``index-state``.  You
-can do this by running ``nix flake lock --update-input hackageNix``.
+can do this by running::
+
+  nix flake lock --update-input hackageNix
+
+If this fails to build, it may also be necessary to update haskell.nix::
+
+  nix flake lock --update-input haskellNix
 
 From the Cardano Haskell Package repository
 -------------------------------------------
 
-Many Cardano packages are not on Hackage and are instead in the `Cardano Haskell
-Package repository <cardano-haskell-packages_>`_ (CHaP), see the README for
-(lots) more information.  Getting new packages from there works much like
-getting them from Hackage.  The differences are that it has an independent
-``index-state``, and that there is a different Nix command you need to run
-afterwards: ``nix flake lock --update-input CHaP``.
+Many Cardano packages are not on Hackage and are instead in the `Cardano Haskell Package
+repository <cardano-haskell-packages_>`_ (CHaP), see the README for (lots) more
+information.  Getting new packages from there works much like getting them from
+Hackage. The differences are that it has an independent ``index-state``, and that there is
+a different Nix command you need to run afterwards.
+
+Run ``cabal update`` locally::
+
+  cabal update
+
+  Downloading the latest package lists from:
+  - hackage.haskell.org
+  - cardano-haskell-packages
+  Package list of cardano-haskell-packages has been updated.
+  The index-state is set to 2024-06-24T07:23:35Z.
+  ...
+
+Copy the value of the index-state int ``cabal.project``::
+
+  index-state:
+  , hackage.haskell.org 2024-06-26T15:03:35Z
+  , cardano-haskell-packages 2024-06-24T07:23:35Z
+
+Update the Nix equivalent of the newer ``index-state``::
+
+  nix flake lock --update-input CHaP
+
+If there are updated configuration files, be sure to also update ``iohk-nix``::
+
+  nix flake lock --update-input nix flake lock --update-input hackageNix
+
+In rare cases, it may also be necessary to update haskell.nix::
+
+  nix flake lock --update-input haskellNix
 
 Using unreleased versions of dependencies
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Sometimes we need to use an unreleased version of one of our dependencies,
 either to fix an issue in a package that is not under our control, or to
 experiment with a pre-release version of one of our own packages.  You can use a
-``source-repository-package`` stanza to pull in the unreleased version.  Try
-only to do this for a short time, as it does not play very well with tooling,
-and will interfere with the ability to release cardano-db-sync itself.
+``source-repository-package`` stanza to pull in the unreleased version::
+
+  source-repository-package
+    type: git
+    location: https://github.com/IntersectMBO/cardano-node
+    tag: 4a18841e7df0d10edab98a612c80217ea49a5c11
+    --sha256: sha256-T5kZqlzTnaain3rypUwhpmY3YcZoDtbSqEQADeucJH4=
+    subdir:
+      cardano-node
+      cardano-submit-api
+      trace-dispatcher
+      trace-forward
+      trace-resources
+
+Try only to do this for a short time, as it does not play very well with tooling, and will
+interfere with the ability to release cardano-db-sync itself.
 
 For packages that we do not control, we can end up in a situation where we have
 a fork that looks like it will be long-lived or permanent (e.g. the maintainer