Extend tap instructions for both users and developers

Author: NlightNFotis

doc/ADR/homebrew_tap.md

@@ -1,5 +1,12 @@
 # Homebrew tap instructions
 
+CBMC archives versions into a tap which you can use to quickly download and
+build various historical versions.
+
+The tap is available at https://github.com/diffblue/homebrew-cbmc.
+
+Any version installed from the tap is going to be built from source.
+
 ## User instructions
 
 1. Add the CBMC tap using the following command:
@@ -14,6 +21,18 @@
    $ brew install diffblue/cbmc/[email protected]
    ```
 
+3. To remove the version of CBMC installed you need to issue
+
+   ```sh
+   $ brew remove diffblue/cbmc/[email protected]
+   ```
+
+4. To remove the tap altogether, you need to issue
+
+   ```sh
+   $ brew untap diffblue/cbmc
+   ```
+
 ## Developer instructions
 
 1. First of all, you need to create a new tap locally:
@@ -48,6 +67,19 @@
    contain the formula that we had submitted for that version of CBMC in the
    `homebrew/core` repository.
 
+4. If you want to edit a specific version formula, you can do that by issueing
+
+   ```sh
+   $ brew edit [email protected]
+   ```
+
+   with the appropriate version tag. This will open the formula on the default
+   editor in your system to allow you to make changes.
+
+   These changes are only going to reflected locally - but you can `cd` to the
+   repository, commit and then push to the tap (this is allowed only for people
+   who have permission to push to the tap - mainly, the Diffblue open source team).
+
 
 ## Notes
 
@@ -59,13 +91,15 @@
 
 * The binaries are installed without any version tag attached, so they cannot
   live side by side.
-* The install formula doesn't override binaries, so if you already have a CBMC
-  version installed, you need to `remove` it before installing another one:
+* If you install a different version of CBMC and you want to use that one
+  instead, you need to take an extra step after installation to setup the
+  appropriate symlinks by using the `brew link` instruction:
 
   ```sh
-  $ brew install diffblue/cbmc/[email protected]
-  [...]
-  $ brew remove [email protected]
-  [...]
+  $ cbmc --version   # version installed by brew
+  5.54.0
   $ brew install diffblue/cbmc/[email protected]
+  $ brew link --overwrite [email protected]
+  $ cbmc --version
+  5.55.0
   ```