Document deprecation and add test for smooth update

Test that when you generate a package in the previous main
and then update to the HEAD using only the required data
and defaults, that it is the same as generating the package
in the HEAD.

Warning: the interactions with other changes is not clear yet.

Closes #428

docs/src/91-developer.md

@@ -317,3 +317,26 @@ Since the GitHub workflow also uses `{` and `}` for their commands, we want to e
 ```jinja
 os: {% raw %}%{{ matrix.os }}{% endraw %}
 ```
+
+## Removing/replacing a question
+
+!!! warn
+    This has only been tested with a single change
+
+Before removing a question, we should deprecate it for one major release.
+We also want to ensure a smooth transition when the user updates.
+
+Luckily, we do have one test that minimally simulates this situation:
+"Test updating from main to HEAD vs generate in HEAD" inside file `test/test-bestie-specific-api`.
+
+This test will run `generate` using the local `main` branch (which won't contain the changes), and run the `update` command, with `defaults=true`, and then compare the result to running `generate` directly.
+
+- Change the `help` field to start with "(Deprecated in VERSION)" (VERSION should be the next major release)
+- Set `when: false` in the question
+- Update the CHANGELOG
+  - Entry in `Deprecated` section
+  - Add or update a "Breaking notice" in the beginning to inform of the changes
+- Move the default questions answers in `src/debug/Data.jl` to the `deprecated` dictionary.
+- Make sure that nothing depends on the old question
+- If necessary, change some `default` values to use the deprecated questions, to ensure a smooth transition.
+- Remove the question in the next release

src/debug/Data.jl

@@ -2,7 +2,7 @@
 Fake data for testing
 
 - `Debug.Data`: NamedTuple of Dictionaries with default data
-  - `Debug.Data.minimum_defaults`: Required data if you use `defaults = true`
+  - `Debug.Data.required`: Required data if you use `defaults = true`
   - `Debug.Data.strategy_minimum`: Required data for strategy minimum, no defaults.
   - `Debug.Data.strategy_recommended`: Required data for strategy recommended, no defaults.
   - `Debug.Data.strategy_ask`: Required data for strategy ask, no defaults.
@@ -12,16 +12,21 @@ module Data
 using Random: MersenneTwister
 using UUIDs: uuid4
 
-const minimum_defaults = Dict(
-  "PackageName" => "FakePkg",
-  "PackageUUID" => string(uuid4(MersenneTwister(123))),
-  "PackageOwner" => "bestietemplate",
-  "AuthorName" => "Bestie Template",
-  "AuthorEmail" => "[email protected]",
+const deprecated = Dict()
+
+const required = merge(
+  Dict(
+    "PackageName" => "FakePkg",
+    "PackageUUID" => string(uuid4(MersenneTwister(123))),
+    "PackageOwner" => "bestietemplate",
+    "AuthorName" => "Bestie Template",
+    "AuthorEmail" => "[email protected]",
+  ),
+  deprecated,
 )
 
 const strategy_minimum = merge(
-  minimum_defaults,
+  required,
   Dict(
     "JuliaMinVersion" => "1.6",
     "License" => "MIT",

template/.github/workflows/ReusableTest.yml

@@ -35,6 +35,8 @@ jobs:
 
     steps:
       - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
       - uses: julia-actions/setup-julia@v2
         with:
           version: ${{ inputs.version }}

test/test-bad-usage-and-errors.jl

@@ -22,7 +22,6 @@ end
     @testset "It works if the dst_path is ." begin
       mkdir("some_folder2")
       cd("some_folder2") do
-        @show readdir(".")
         # Should not throw
         BestieTemplate.generate(
           C.template_path,

test/test-bestie-specific-api.jl

@@ -204,3 +204,42 @@ end
     end
   end
 end
+
+@testset "Test updating from main to HEAD vs generate in HEAD" begin
+  _with_tmp_dir() do dir
+    common_args = (defaults = true, quiet = true)
+
+    mkdir("gen_then_up")
+    cd("gen_then_up") do
+      # Generate the release version
+      BestieTemplate.generate(
+        C.template_path,
+        ".",
+        C.args.bestie.req;
+        vcs_ref = "main",
+        common_args...,
+      )
+      _git_setup()
+      _full_precommit()
+      # Update using the HEAD version
+      BestieTemplate.update(".", C.args.bestie.req; vcs_ref = "HEAD", common_args...)
+      _full_precommit()
+    end
+
+    mkdir("gen_direct")
+    cd("gen_direct") do
+      # Generate directly in the HEAD version
+      BestieTemplate.generate(
+        C.template_path,
+        ".",
+        C.args.bestie.req;
+        vcs_ref = "HEAD",
+        common_args...,
+      )
+      _git_setup()
+      _full_precommit()
+    end
+
+    _test_diff_dir("gen_then_up", "gen_direct")
+  end
+end

test/utils.jl

@@ -94,7 +94,7 @@ using BestieTemplate.Debug.Data: Data
 _bestie_args_to_copier_args(dict) = vcat([["-d"; "$k=$v"] for (k, v) in dict]...)
 
 "Arguments for the different calls"
-_bestie_args = (min = Data.strategy_minimum, ask = Data.strategy_ask_default)
+_bestie_args = (req = Data.required, min = Data.strategy_minimum, ask = Data.strategy_ask_default)
 args = (
   bestie = _bestie_args,
   copier = NamedTuple(