Document deprecation and add test for smooth update

.github/workflows/ReusableTest.yml

@@ -40,6 +40,10 @@ jobs:
       - run: |
           git config --global user.email "[email protected]"
           git config --global user.name "GitHub Action"
+          git branch this-pr
+          git checkout origin/main
+          git branch --track main origin/main
+          git checkout this-pr
       - uses: julia-actions/setup-julia@v2
         with:
           version: ${{ inputs.version }}

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",

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

@@ -60,6 +60,9 @@ function _test_diff_dir(dir1, dir2)
       end
 
       @testset "File $(nice_dir(file))" for file in files
+        if endswith(".rej")(file)
+          continue
+        end
         file1 = joinpath(root, file)
         file2 = replace(file1, dir1 => dir2)
         lines1 = readlines(file1)
@@ -94,7 +97,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(