docs: minor enhancements in immutability control behaviour in deploy (#144)

* docs: further clarifications on v3 deploy behaviour

* docs: extra notes on deploy time immutability control

* docs: apply suggestions from code review

Co-authored-by: Neil Campbell <neil.campbell@makerx.com.au>

---------

Co-authored-by: Neil Campbell <neil.campbell@makerx.com.au>

Author: aorumbayev

docs/html/_sources/capabilities/app-deploy.md.txt

@@ -68,6 +68,8 @@ An example of the ARC-2 transaction note that is attached as an app creation / u
 ALGOKIT_DEPLOYER:j{name:"MyApp",version:"1.0",updatable:true,deletable:false}
 ```
 
+> NOTE: Starting from v3.0.0, AlgoKit Utils no longer automatically increments the contract version by default. It is the user's responsibility to explicitly manage versioning of their smart contracts (if desired).
+
 ## Lookup deployed apps by name
 
 In order to resolve what apps have been previously deployed and their metadata, AlgoKit provides a method that does a series of indexer lookups and returns a map of name to app metadata via `get_creator_apps_by_name(creator_address)`.
@@ -179,8 +181,6 @@ In order for a smart contract to opt-in to use this functionality, it must have
 - `TMPL_UPDATABLE` - Which will be replaced with a `1` if an app should be updatable and `0` if it shouldn't (immutable)
 - `TMPL_DELETABLE` - Which will be replaced with a `1` if an app should be deletable and `0` if it shouldn't (permanent)
 
-If you are building a smart contract using the production [AlgoKit init templates](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/init.md) provide a reference implementation out of the box for the deploy-time immutability and permanence control.
-
 If you passed in a TEAL template for the `approval_program` or `clear_state_program` (i.e. a `str` rather than a `bytes`) then `deploy` will return the {py:obj}`CompiledTeal <algokit_utils.models.app_deployer.CompiledTeal>` of substituting then compiling the TEAL template(s) in the following properties of the return value:
 
 - `compiled_approval: CompiledTeal | None`
@@ -193,6 +193,50 @@ Template substitution is done by executing `algorand.app.compile_teal_template(t
 - `AppManager.replace_teal_template_deploy_time_control_params(teal_template_code, params)` - If `params` is provided, it allows for deploy-time immutability and permanence control by replacing `TMPL_UPDATABLE` with `params.get("updatable")` if not `None` and replacing `TMPL_DELETABLE` with `params.get("deletable")` if not `None`
 - `algorand.app.compile_teal(teal_code)` - Sends the final TEAL to algod for compilation and returns the result including the source map and caches the compilation result within the `AppManager` instance
 
+#### Making updatable/deletable apps
+
+Below is a sample in [Algorand Python SDK](https://github.com/algorandfoundation/puya) that demonstrates how to make an app updatable/deletable smart contract with the use of `TMPL_UPDATABLE` and `TMPL_DELETABLE` template parameters.
+
+```python
+# ... your contract code ...
+@arc4.baremethod(allow_actions=["UpdateApplication"])
+def update(self) -> None:
+    assert TemplateVar[bool]("UPDATABLE")
+
+@arc4.baremethod(allow_actions=["DeleteApplication"])
+def delete(self) -> None:
+    assert TemplateVar[bool]("DELETABLE")
+# ... your contract code ...
+```
+
+Alternative example in [Algorand TypeScript SDK](https://github.com/algorandfoundation/puya-ts):
+
+```typescript
+// ... your contract code ...
+@baremethod({ allowActions: 'UpdateApplication' })
+public onUpdate() {
+    assert(TemplateVar<boolean>('UPDATABLE'))
+}
+
+@baremethod({ allowActions: 'DeleteApplication' })
+public onDelete() {
+    assert(TemplateVar<boolean>('DELETABLE'))
+}
+// ... your contract code ...
+```
+
+With the above code, when deploying your application, you can pass in the following deploy-time parameters:
+
+```python
+my_factory.deploy(
+    ... # other deployment parameters ...
+    compilation_params={
+        "updatable": True, # resulting app will be updatable, and this metadata will be set in the ARC-2 transaction note
+        "deletable": False, # resulting app will not be deletable, and this metadata will be set in the ARC-2 transaction note
+    }
+)
+```
+
 ### Return value
 
 When `deploy` executes it will return a {py:obj}`AppDeployResult <algokit_utils.models.app_deployer.AppDeployResult>` object that describes exactly what it did and has comprehensive metadata to describe the end result of the deployed app.

docs/html/_sources/v3-migration-guide.md.txt

@@ -249,6 +249,7 @@ result = algorand.send.asset_opt_in(
 4. **Application Client**
 
    - Split into `AppClient`, `AppDeployer` and `AppFactory`
+   - `deploy` method in `AppFactory`/`AppDeployer` no longer auto increments the contract version by default. It is the user's responsibility to explicitly manage versioning of their smart contracts (if desired).
    - New intuitive structured interface for creating or sending `AppCall`|`AppMethodCall` transactions
    - ARC-56 support along with automatic conversion of specs from ARC-32 to ARC-56
 

docs/html/capabilities/app-deploy.html

@@ -385,6 +385,9 @@ <h2>Deployment metadata<a class="headerlink" href="#deployment-metadata" title="
 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">ALGOKIT_DEPLOYER</span><span class="p">:</span><span class="n">j</span><span class="p">{</span><span class="n">name</span><span class="p">:</span><span class="s2">&quot;MyApp&quot;</span><span class="p">,</span><span class="n">version</span><span class="p">:</span><span class="s2">&quot;1.0&quot;</span><span class="p">,</span><span class="n">updatable</span><span class="p">:</span><span class="n">true</span><span class="p">,</span><span class="n">deletable</span><span class="p">:</span><span class="n">false</span><span class="p">}</span>
 </pre></div>
 </div>
+<blockquote>
+<div><p>NOTE: Starting from v3.0.0, AlgoKit Utils no longer automatically increments the contract version by default. It is the user’s responsibility to explicitly manage versioning of their smart contracts (if desired).</p>
+</div></blockquote>
 </section>
 <section id="lookup-deployed-apps-by-name">
 <h2>Lookup deployed apps by name<a class="headerlink" href="#lookup-deployed-apps-by-name" title="Link to this heading">¶</a></h2>
@@ -491,7 +494,6 @@ <h3>Compilation and template substitution<a class="headerlink" href="#compilatio
 <li><p><code class="docutils literal notranslate"><span class="pre">TMPL_UPDATABLE</span></code> - Which will be replaced with a <code class="docutils literal notranslate"><span class="pre">1</span></code> if an app should be updatable and <code class="docutils literal notranslate"><span class="pre">0</span></code> if it shouldn’t (immutable)</p></li>
 <li><p><code class="docutils literal notranslate"><span class="pre">TMPL_DELETABLE</span></code> - Which will be replaced with a <code class="docutils literal notranslate"><span class="pre">1</span></code> if an app should be deletable and <code class="docutils literal notranslate"><span class="pre">0</span></code> if it shouldn’t (permanent)</p></li>
 </ul>
-<p>If you are building a smart contract using the production <a class="reference external" href="https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/init.md">AlgoKit init templates</a> provide a reference implementation out of the box for the deploy-time immutability and permanence control.</p>
 <p>If you passed in a TEAL template for the <code class="docutils literal notranslate"><span class="pre">approval_program</span></code> or <code class="docutils literal notranslate"><span class="pre">clear_state_program</span></code> (i.e. a <code class="docutils literal notranslate"><span class="pre">str</span></code> rather than a <code class="docutils literal notranslate"><span class="pre">bytes</span></code>) then <code class="docutils literal notranslate"><span class="pre">deploy</span></code> will return the <code class="xref py py-obj docutils literal notranslate"><span class="pre">CompiledTeal</span></code> of substituting then compiling the TEAL template(s) in the following properties of the return value:</p>
 <ul class="simple">
 <li><p><code class="docutils literal notranslate"><span class="pre">compiled_approval:</span> <span class="pre">CompiledTeal</span> <span class="pre">|</span> <span class="pre">None</span></code></p></li>
@@ -504,6 +506,45 @@ <h3>Compilation and template substitution<a class="headerlink" href="#compilatio
 <li><p><code class="docutils literal notranslate"><span class="pre">AppManager.replace_teal_template_deploy_time_control_params(teal_template_code,</span> <span class="pre">params)</span></code> - If <code class="docutils literal notranslate"><span class="pre">params</span></code> is provided, it allows for deploy-time immutability and permanence control by replacing <code class="docutils literal notranslate"><span class="pre">TMPL_UPDATABLE</span></code> with <code class="docutils literal notranslate"><span class="pre">params.get(&quot;updatable&quot;)</span></code> if not <code class="docutils literal notranslate"><span class="pre">None</span></code> and replacing <code class="docutils literal notranslate"><span class="pre">TMPL_DELETABLE</span></code> with <code class="docutils literal notranslate"><span class="pre">params.get(&quot;deletable&quot;)</span></code> if not <code class="docutils literal notranslate"><span class="pre">None</span></code></p></li>
 <li><p><code class="docutils literal notranslate"><span class="pre">algorand.app.compile_teal(teal_code)</span></code> - Sends the final TEAL to algod for compilation and returns the result including the source map and caches the compilation result within the <code class="docutils literal notranslate"><span class="pre">AppManager</span></code> instance</p></li>
 </ul>
+<section id="making-updatable-deletable-apps">
+<h4>Making updatable/deletable apps<a class="headerlink" href="#making-updatable-deletable-apps" title="Link to this heading">¶</a></h4>
+<p>Below is a sample in <a class="reference external" href="https://github.com/algorandfoundation/puya">Algorand Python SDK</a> that demonstrates how to make an app updatable/deletable smart contract with the use of <code class="docutils literal notranslate"><span class="pre">TMPL_UPDATABLE</span></code> and <code class="docutils literal notranslate"><span class="pre">TMPL_DELETABLE</span></code> template parameters.</p>
+<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># ... your contract code ...</span>
+<span class="nd">@arc4</span><span class="o">.</span><span class="n">baremethod</span><span class="p">(</span><span class="n">allow_actions</span><span class="o">=</span><span class="p">[</span><span class="s2">&quot;UpdateApplication&quot;</span><span class="p">])</span>
+<span class="k">def</span><span class="w"> </span><span class="nf">update</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="kc">None</span><span class="p">:</span>
+    <span class="k">assert</span> <span class="n">TemplateVar</span><span class="p">[</span><span class="nb">bool</span><span class="p">](</span><span class="s2">&quot;UPDATABLE&quot;</span><span class="p">)</span>
+
+<span class="nd">@arc4</span><span class="o">.</span><span class="n">baremethod</span><span class="p">(</span><span class="n">allow_actions</span><span class="o">=</span><span class="p">[</span><span class="s2">&quot;DeleteApplication&quot;</span><span class="p">])</span>
+<span class="k">def</span><span class="w"> </span><span class="nf">delete</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="kc">None</span><span class="p">:</span>
+    <span class="k">assert</span> <span class="n">TemplateVar</span><span class="p">[</span><span class="nb">bool</span><span class="p">](</span><span class="s2">&quot;DELETABLE&quot;</span><span class="p">)</span>
+<span class="c1"># ... your contract code ...</span>
+</pre></div>
+</div>
+<p>Alternative example in <a class="reference external" href="https://github.com/algorandfoundation/puya-ts">Algorand TypeScript SDK</a>:</p>
+<div class="highlight-typescript notranslate"><div class="highlight"><pre><span></span><span class="c1">// ... your contract code ...</span>
+<span class="kd">@baremethod</span><span class="p">({</span><span class="w"> </span><span class="nx">allowActions</span><span class="o">:</span><span class="w"> </span><span class="s1">&#39;UpdateApplication&#39;</span><span class="w"> </span><span class="p">})</span>
+<span class="k">public</span><span class="w"> </span><span class="nx">onUpdate</span><span class="p">()</span><span class="w"> </span><span class="p">{</span>
+<span class="w">    </span><span class="nx">assert</span><span class="p">(</span><span class="nx">TemplateVar</span><span class="o">&lt;</span><span class="kt">boolean</span><span class="o">&gt;</span><span class="p">(</span><span class="s1">&#39;UPDATABLE&#39;</span><span class="p">))</span>
+<span class="p">}</span>
+
+<span class="kd">@baremethod</span><span class="p">({</span><span class="w"> </span><span class="nx">allowActions</span><span class="o">:</span><span class="w"> </span><span class="s1">&#39;DeleteApplication&#39;</span><span class="w"> </span><span class="p">})</span>
+<span class="k">public</span><span class="w"> </span><span class="nx">onDelete</span><span class="p">()</span><span class="w"> </span><span class="p">{</span>
+<span class="w">    </span><span class="nx">assert</span><span class="p">(</span><span class="nx">TemplateVar</span><span class="o">&lt;</span><span class="kt">boolean</span><span class="o">&gt;</span><span class="p">(</span><span class="s1">&#39;DELETABLE&#39;</span><span class="p">))</span>
+<span class="p">}</span>
+<span class="c1">// ... your contract code ...</span>
+</pre></div>
+</div>
+<p>With the above code, when deploying your application, you can pass in the following deploy-time parameters:</p>
+<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">my_factory</span><span class="o">.</span><span class="n">deploy</span><span class="p">(</span>
+    <span class="o">...</span> <span class="c1"># other deployment parameters ...</span>
+    <span class="n">compilation_params</span><span class="o">=</span><span class="p">{</span>
+        <span class="s2">&quot;updatable&quot;</span><span class="p">:</span> <span class="kc">True</span><span class="p">,</span> <span class="c1"># resulting app will be updatable, and this metadata will be set in the ARC-2 transaction note</span>
+        <span class="s2">&quot;deletable&quot;</span><span class="p">:</span> <span class="kc">False</span><span class="p">,</span> <span class="c1"># resulting app will not be deletable, and this metadata will be set in the ARC-2 transaction note</span>
+    <span class="p">}</span>
+<span class="p">)</span>
+</pre></div>
+</div>
+</section>
 </section>
 <section id="return-value">
 <h3>Return value<a class="headerlink" href="#return-value" title="Link to this heading">¶</a></h3>
@@ -593,7 +634,10 @@ <h3>Return value<a class="headerlink" href="#return-value" title="Link to this h
 <li><a class="reference internal" href="#performing-a-deployment">Performing a deployment</a><ul>
 <li><a class="reference internal" href="#input-parameters">Input parameters</a></li>
 <li><a class="reference internal" href="#idempotency">Idempotency</a></li>
-<li><a class="reference internal" href="#compilation-and-template-substitution">Compilation and template substitution</a></li>
+<li><a class="reference internal" href="#compilation-and-template-substitution">Compilation and template substitution</a><ul>
+<li><a class="reference internal" href="#making-updatable-deletable-apps">Making updatable/deletable apps</a></li>
+</ul>
+</li>
 <li><a class="reference internal" href="#return-value">Return value</a></li>
 </ul>
 </li>

docs/html/objects.inv

@@ -577,6 +577,7 @@ <h2>Breaking Changes<a class="headerlink" href="#breaking-changes" title="Link t
 <li><p><strong>Application Client</strong></p>
 <ul class="simple">
 <li><p>Split into <code class="docutils literal notranslate"><span class="pre">AppClient</span></code>, <code class="docutils literal notranslate"><span class="pre">AppDeployer</span></code> and <code class="docutils literal notranslate"><span class="pre">AppFactory</span></code></p></li>
+<li><p><code class="docutils literal notranslate"><span class="pre">deploy</span></code> method in <code class="docutils literal notranslate"><span class="pre">AppFactory</span></code>/<code class="docutils literal notranslate"><span class="pre">AppDeployer</span></code> no longer auto increments the contract version by default. It is the user’s responsibility to explicitly manage versioning of their smart contracts (if desired).</p></li>
 <li><p>New intuitive structured interface for creating or sending <code class="docutils literal notranslate"><span class="pre">AppCall</span></code>|<code class="docutils literal notranslate"><span class="pre">AppMethodCall</span></code> transactions</p></li>
 <li><p>ARC-56 support along with automatic conversion of specs from ARC-32 to ARC-56</p></li>
 </ul>