From 0e1caa75cddb6ad3cc9f481e66697f7df7bf9981 Mon Sep 17 00:00:00 2001
From: Ed Morley <501702+edmorley@users.noreply.github.com>
Date: Thu, 21 Sep 2023 10:18:54 +0000
Subject: [PATCH] Update changelog and rustdocs for `BuildpackReference`
 changes (#677)

A few small tweaks:
* `BuildpackReference`  is only publicly exported at the root of the
  `libcnb-test` crate, so end users can't use it via the `build_config`
  module - so the `build_config::` references have been removed.
* The new `BuildpackReference::WorkspaceBuildpack` variant supports only
  libcnb.rs and composite buildpacks, not eg bash buildpacks, so the
  "any buildpack" reference in the changelog has been clarified.
  Similarly, the rustdocs for `BuildpackReference` previously didn't
  mention composite buildpacks, only `libcnb.rs` buildpacks.
* The "Rust workspace" references have been changed to
  "Cargo workspace" since it's Cargo not Rust that has the concept of a
  workspace: https://doc.rust-lang.org/book/ch14-03-cargo-workspaces.html
* The rustdocs for `.buildpacks()` has been updated to include an example
  of using the new variant, and made to be consistent ordering wise with
  the example in the `libcnb-test` README.
* The two changelog entries under "Added" have been consolidated, since
  they are covering the same newly added variant.
---
 CHANGELOG.md                    | 5 ++---
 libcnb-test/src/build_config.rs | 8 ++++++--
 2 files changed, 8 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 38d8c802..a9415673 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -15,8 +15,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - `ExecDProgramOutputKey`, `ProcessType`, `LayerName`, `BuildpackId` and `StackId` now implement `Ord` and `PartialOrd`. ([#658](https://github.com/heroku/libcnb.rs/pull/658))
   - Add `generic::GenericMetadata` as a generic metadata type. Also makes it the default for `BuildpackDescriptor`, `SingleBuildpackDescriptor`, `MetaBuildpackDescriptor` and `LayerContentMetadata`. ([#664](https://github.com/heroku/libcnb.rs/pull/664))
 - `libcnb-test`:
-  - Added the variant `WorkspaceBuildpack` to the `build_config::BuildpackReference` enum which allows any buildpack within the Rust workspace to be referenced for testing. ([#666](https://github.com/heroku/libcnb.rs/pull/666))
-  - Testing of composite buildpacks is now supported using the `WorkspaceBuildpack` variant - **Requires `pack` CLI version `>=0.30`**. ([#666](https://github.com/heroku/libcnb.rs/pull/666))
+  - Added the `BuildpackReference::WorkspaceBuildpack` enum variant. This allows for the testing of any libcnb.rs or composite buildpack in the Cargo workspace, instead of only the buildpack of the current crate. **Note: The testing of composite buildpacks requires `pack` CLI version `>=0.30`.** ([#666](https://github.com/heroku/libcnb.rs/pull/666))
 
 ### Changed
 
@@ -26,7 +25,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Build output for humans changed slightly, output intended for machines/scripting didn't change. ([#657](https://github.com/heroku/libcnb.rs/pull/657))
   - When performing buildpack detection, standard ignore files (`.ignore` and `.gitignore`) will be respected. ([#673](https://github.com/heroku/libcnb.rs/pull/673))
 - `libcnb-test`:
-  - Renamed the variant `Crate` to `CurrentCrate` for the `build_config::BuildpackReference` enum which references the buildpack within the Rust Crate currently being tested. ([#666](https://github.com/heroku/libcnb.rs/pull/666))
+  - Renamed `BuildpackReference::Crate` to `BuildpackReference::CurrentCrate`. ([#666](https://github.com/heroku/libcnb.rs/pull/666))
 
 ## [0.14.0] - 2023-08-18
 
diff --git a/libcnb-test/src/build_config.rs b/libcnb-test/src/build_config.rs
index 152c0691..68287a69 100644
--- a/libcnb-test/src/build_config.rs
+++ b/libcnb-test/src/build_config.rs
@@ -55,12 +55,14 @@ impl BuildConfig {
     ///
     /// # Example
     /// ```no_run
+    /// use libcnb::data::buildpack_id;
     /// use libcnb_test::{BuildConfig, BuildpackReference, TestRunner};
     ///
     /// TestRunner::default().build(
     ///     BuildConfig::new("heroku/builder:22", "test-fixtures/app").buildpacks(vec![
-    ///         BuildpackReference::Other(String::from("heroku/another-buildpack")),
     ///         BuildpackReference::CurrentCrate,
+    ///         BuildpackReference::WorkspaceBuildpack(buildpack_id!("my-project/buildpack")),
+    ///         BuildpackReference::Other(String::from("heroku/another-buildpack")),
     ///     ]),
     ///     |context| {
     ///         // ...
@@ -251,8 +253,10 @@ impl BuildConfig {
 #[derive(Debug, Clone, Eq, PartialEq)]
 pub enum BuildpackReference {
     /// References the buildpack in the Rust Crate currently being tested.
+    ///
+    /// Is equivalent to `BuildpackReference::WorkspaceBuildpack(buildpack_id!("<buildpack ID of current crate"))`.
     CurrentCrate,
-    /// References a libcnb.rs buildpack within the Rust Workspace that needs to be packaged into a buildpack
+    /// References a libcnb.rs or composite buildpack within the Cargo workspace that needs to be packaged into a buildpack.
     WorkspaceBuildpack(BuildpackId),
     /// References another buildpack by id, local directory or tarball.
     Other(String),