From 3327a922921fe828c9613db86c7f574812c2fffd Mon Sep 17 00:00:00 2001
From: Andreas Herrmann <andreash87@gmx.ch>
Date: Sat, 2 Dec 2023 11:28:53 +0100
Subject: [PATCH 1/4] Expand the installation instructions

Closes #101.
---
 README.md | 32 ++++++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/README.md b/README.md
index 1c6c5882..61761c1a 100644
--- a/README.md
+++ b/README.md
@@ -51,8 +51,21 @@ and build configuration features well.
 
 ## Installation
 
+The instructions assume basic familiarity with the Bazel build system.
+Take a look at [Bazel's documentation][bazel-intro] if you are unfamiliar.
+
+[bazel-intro]: https://bazel.build/about/intro
+
 ### Using Bzlmod with Bazel >=6
 
+Bzlmod is Bazel's new dependency manager. You can read more about it in the
+[Bazel documentation][bzlmod-doc]. If you use bzlmod, then you can skip the
+WORKSPACE section below. Take a look at [Bazel's migration
+guide][bzlmod-migration] if you are switching from WORKSPACE to bzlmod.
+
+[bzlmod-doc]: https://bazel.build/external/overview#bzlmod
+[bzlmod-migration]: https://bazel.build/external/migration
+
 Add the following to your MODULE.bazel file to install rules_zig:
 
 ```bzl
@@ -65,8 +78,21 @@ archive_override(
 )
 ```
 
+Note, `$SHA256` and `$COMMIT` are placeholders that you need to fill in. Take a
+look at the [Bazel documentation][archive-override-doc] for further
+information.
+
+[archive-override-doc]: https://bazel.build/versions/6.4.0/rules/lib/globals#archive_override
+
 ### Using WORKSPACE
 
+The old way of managing external dependencies with Bazel is to declare them in
+your WORKSPACE file. You can read more about it in the [Bazel
+documentation][workspace-doc]. If you use the WORKSPACE approach, then you can
+skip the bzlmod section above.
+
+[workspace-doc]: https://bazel.build/external/overview#workspace-system
+
 Add the following to your WORKSPACE file to install rules_zig:
 
 ```bzl
@@ -93,6 +119,12 @@ zig_register_toolchains(
 )
 ```
 
+Note, `$SHA256` and `$COMMIT` are placeholders that you need to fill in. Take a
+look at the [Bazel documentation][http-archive-doc] for further
+information.
+
+[http-archive-doc]: https://bazel.build/rules/lib/repo/http#http_archive
+
 <!-- TODO[AH] Point to release installation instructions
 
 From the release you wish to use:

From 569455aeebb97f9c27fe31b23a0efa8e5df43e8f Mon Sep 17 00:00:00 2001
From: Andreas Herrmann <andreash87@gmx.ch>
Date: Sat, 2 Dec 2023 11:29:30 +0100
Subject: [PATCH 2/4] Document examples before reference docs

Related to #101
---
 README.md | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 61761c1a..baa37737 100644
--- a/README.md
+++ b/README.md
@@ -140,11 +140,6 @@ copy the WORKSPACE snippet into your `WORKSPACE` file.
 
 -->
 
-## Reference Documentation
-
-Generated API documentation for the provided rules is available in
-[`./docs/rules.md`](./docs/rules.md).
-
 ## Usage Examples
 
 <!-- TODO[AH] Create an instructive example.
@@ -153,3 +148,8 @@ Generated API documentation for the provided rules is available in
 
 Examples can be found among the end-to-end tests under
 [`./e2e/workspace`](./e2e/workspace).
+
+## Reference Documentation
+
+Generated API documentation for the provided rules is available in
+[`./docs/rules.md`](./docs/rules.md).

From a597ceafac4ea1ebe073e3bbf98d9794e438cdc0 Mon Sep 17 00:00:00 2001
From: Andreas Herrmann <andreash87@gmx.ch>
Date: Sat, 2 Dec 2023 11:34:17 +0100
Subject: [PATCH 3/4] Refer to release notes for install instructions

Closes #139
---
 README.md | 20 ++++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

diff --git a/README.md b/README.md
index baa37737..a2c5d544 100644
--- a/README.md
+++ b/README.md
@@ -66,7 +66,12 @@ guide][bzlmod-migration] if you are switching from WORKSPACE to bzlmod.
 [bzlmod-doc]: https://bazel.build/external/overview#bzlmod
 [bzlmod-migration]: https://bazel.build/external/migration
 
-Add the following to your MODULE.bazel file to install rules_zig:
+To install a [release version of rules_zig][rules-zig-releases] follow the
+installation instructions given in the corresponding release notes.
+
+[rules-zig-releases]: https://github.com/aherrmann/rules_zig/releases
+
+To install a development version add the following to your MODULE.bazel file:
 
 ```bzl
 bazel_dep(name = "rules_zig")
@@ -93,7 +98,10 @@ skip the bzlmod section above.
 
 [workspace-doc]: https://bazel.build/external/overview#workspace-system
 
-Add the following to your WORKSPACE file to install rules_zig:
+To install a [release version of rules_zig][rules-zig-releases] follow the
+installation instructions given in the corresponding release notes.
+
+To install a development version add the following to your WORKSPACE file:
 
 ```bzl
 load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
@@ -125,14 +133,6 @@ information.
 
 [http-archive-doc]: https://bazel.build/rules/lib/repo/http#http_archive
 
-<!-- TODO[AH] Point to release installation instructions
-
-From the release you wish to use:
-<https://github.com/aherrmann/rules_zig/releases>
-copy the WORKSPACE snippet into your `WORKSPACE` file.
-
--->
-
 <!-- TODO[AH] Write a user-guide
   https://github.com/aherrmann/rules_zig/issues/59
 

From 1a9d7c6bacae986d88e11614cad8a249623fcf6b Mon Sep 17 00:00:00 2001
From: Andreas Herrmann <andreash87@gmx.ch>
Date: Sat, 2 Dec 2023 11:35:51 +0100
Subject: [PATCH 4/4] Remove the early development warning

The rule set is sufficiently developed to support a basic Zig use-case
and already some advanced use-cases.
---
 README.md | 5 -----
 1 file changed, 5 deletions(-)

diff --git a/README.md b/README.md
index a2c5d544..291fa970 100644
--- a/README.md
+++ b/README.md
@@ -7,11 +7,6 @@ Build [Zig code][zig] with the [Bazel build system][bazel].
 
 ## Status
 
-🚧 This is a hobby project in early development. 🚧
-
-Please [get in touch](https://github.com/aherrmann) if you would like to use
-these rules in production.
-
 Take a look at the [planned functionality][planned-functionality] tracking
 issue to get a picture of which functionality is already implemented and what
 is still missing.