From 0885233281151877ae5613ab87e095dbff1575e2 Mon Sep 17 00:00:00 2001
From: Dale Wijnand <dale.wijnand@gmail.com>
Date: Wed, 10 Jan 2018 10:44:45 +0000
Subject: [PATCH] Deprecates Extracted#append for appendWithSession.

.. and appendWithoutSession.
---
 main/src/main/scala/sbt/Extracted.scala | 23 +++++++++++++++++++++--
 notes/1.1.1/fix-Extracted.append.md     | 11 +++++++++++
 notes/{1.0.2 => 1.1.1}/sample.md        |  0
 3 files changed, 32 insertions(+), 2 deletions(-)
 create mode 100644 notes/1.1.1/fix-Extracted.append.md
 rename notes/{1.0.2 => 1.1.1}/sample.md (100%)

diff --git a/main/src/main/scala/sbt/Extracted.scala b/main/src/main/scala/sbt/Extracted.scala
index 80243ada1..f507fa2c7 100644
--- a/main/src/main/scala/sbt/Extracted.scala
+++ b/main/src/main/scala/sbt/Extracted.scala
@@ -120,10 +120,29 @@ final case class Extracted(structure: BuildStructure,
     structure.data.get(scope, key) getOrElse sys.error(
       display.show(ScopedKey(scope, key)) + " is undefined.")
 
-  def append(settings: Seq[Setting[_]], state: State): State = {
+  @deprecated("This discards session settings. Migrate to appendWithSession or appendWithoutSession.", "1.2.0")
+  def append(settings: Seq[Setting[_]], state: State): State =
+    appendWithoutSession(settings, state)
+
+  /** Appends the given settings to all the build state settings, including session settings. */
+  def appendWithSession(settings: Seq[Setting[_]], state: State): State =
+    appendImpl(settings, state, session.mergeSettings)
+
+  /**
+   * Appends the given settings to the original build state settings, discarding any settings
+   * appended to the session in the process.
+   */
+  def appendWithoutSession(settings: Seq[Setting[_]], state: State): State =
+    appendImpl(settings, state, session.original)
+
+  private[this] def appendImpl(
+      settings: Seq[Setting[_]],
+      state: State,
+      sessionSettings: Seq[Setting[_]],
+  ): State = {
     val appendSettings =
       Load.transformSettings(Load.projectScope(currentRef), currentRef.build, rootProject, settings)
-    val newStructure = Load.reapply(session.original ++ appendSettings, structure)
+    val newStructure = Load.reapply(sessionSettings ++ appendSettings, structure)
     Project.setProject(session, newStructure, state)
   }
 }
diff --git a/notes/1.1.1/fix-Extracted.append.md b/notes/1.1.1/fix-Extracted.append.md
new file mode 100644
index 000000000..56e450391
--- /dev/null
+++ b/notes/1.1.1/fix-Extracted.append.md
@@ -0,0 +1,11 @@
+[@dwijnand]: https://github.com/dwijnand
+
+[#3865]: https://github.com/sbt/sbt/pull/3865
+
+### Fixes with compatibility implications
+
+### Improvements
+
+- Deprecates `Extracted#append` in favour of `appendWithSession` or `appendWithoutSession`.  [#3865][] by [@dwijnand][]
+
+### Bug fixes
diff --git a/notes/1.0.2/sample.md b/notes/1.1.1/sample.md
similarity index 100%
rename from notes/1.0.2/sample.md
rename to notes/1.1.1/sample.md