Merge pull request #1108 from isaacsas/add_devdocs

Add devdocs

HISTORY.md

@@ -1,14 +1,30 @@
 # Breaking updates and feature summaries across releases
 
 ## Catalyst unreleased (master branch)
-- Array symbolics support is more consistent with ModelingToolkit v9. Parameter arrays are no longer scalarized by Catalyst, while species and variables arrays still are (as in ModelingToolkit). As such, parameter arrays should now be specified as arrays in value mappings, i.e.
+- The Catalyst release process is changing; certain core dependencies of
+  Catalyst will now be capped to ensure Catalyst releases are only installed
+  with versions of dependencies for which Catalyst CI and doc build tests pass
+  (at the time the release is made). If you need a dependency version increased,
+  please open an issue and we can update it and make a new Catalyst release once
+  testing against the newer dependency version is complete. 
+- Array symbolics support is more consistent with ModelingToolkit v9. Parameter
+  arrays are no longer scalarized by Catalyst, while species and variables
+  arrays still are (as in ModelingToolkit). As such, parameter arrays should now
+  be specified as arrays in value mappings, i.e.
   ```julia
   @parameters k[1:4]
   pmap = [k => rand(4)]
   ```
-  While one can still manually scalarize a parameter array, it is recommended *not* to do this as it has signifcant performance costs with ModelingToolkit v9.
-- The structural identifiability extension is currently disabled due to issues StructuralIdentifiability has with Julia 1.10.5 and 1.11.
+  While one can still manually scalarize a parameter array, it is recommended
+  *not* to do this as it has signifcant performance costs with ModelingToolkit
+  v9. Note, scalarized parameter arrays passed to the two-argument
+  `ReactionSystem` constructor may become unscalarized.
+- Scoped species/variables/parameters are now treated similar to the latest MTK
+  releases (≥ 9.49).
+- The structural identifiability extension is currently disabled due to issues
+  StructuralIdentifiability has with Julia 1.10.5 and 1.11.
 - A tutorial on making interactive plot displays using Makie has been added.
+- The BifurcationKit extension has been updated to v.4.
 
 ## Catalyst 14.4.1
 - Support for user-defined functions on the RHS when providing coupled equations 

docs/pages.jl

@@ -62,5 +62,6 @@ pages = Any[
         "spatial_modelling/spatial_jump_simulations.md"
     ],
     "FAQs" => "faqs.md",
-    "API" => "api.md"
+    "API" => "api.md",
+    "Developer Documentation" => "devdocs/dev_guide.md"
 ]

docs/src/devdocs/dev_guide.md

@@ -0,0 +1,33 @@
+# Catalyst Developer Documentation
+
+## Release Process
+Beginning with v15, Catalyst is using a new release process to try to ensure
+continuing stability of releases. Before making a release one should
+
+1. Create a new release branch, i.e. "release-15.0.0"
+2. On this branch, cap major dependencies to their latest version that works and
+   for which tests pass.
+   - Caps need to be included in both Project.toml and docs/Project.toml.
+   - Do not cap the master branch as this can prevent upstream libraries from
+     properly testing against Catalyst, and hide breaking changes that impact
+     Catalyst.
+3. Check docs build with the capped dependencies. Visually verify via checking
+   the artifact in the doc build that the docs actually look ok (since sometimes
+   issues can arise that do not lead to actual errors in the doc CI).
+4. Release via the [registration
+   issue](https://github.com/SciML/JumpProcesses.jl/issues/73) with the
+   command:
+    ```julia
+    @JuliaRegistrator register branch=release-15.0.0
+    ```
+    modifying as appropriate for the version you are releasing.
+
+If there is subsequently a need to increment the version of a dependency, this
+should be done via a new release that follows the above process, and modifies
+the [patch, minor, or major Catalyst version (as appropriate for the potential
+impact of the dependency change on Catalyst users)](https://semver.org/). If the
+dependency being updated is a non-breaking release, and would have automatically
+been installed by the package resolver had it not been capped, a patch release
+should be preferred. If the new release branch is branched from master, *it
+needs to ensure Project.toml caps are all ≥ to those listed in the previous
+Catalyst release branch*.

docs/src/index.md

@@ -97,6 +97,23 @@ Pkg.add("Plots")
 ```
 is also needed.
 
+It is **strongly** recommended to run Catalyst in its own environment with the
+minimal set of needed packages. For example, to install Catalyst and Plots in a
+new environment named `catalyst_project` (saved in the current directory) one
+can say
+```julia
+Pkg.activate("catalyst_project")
+Pkg.add("Catalyst")
+Pkg.add("Plots")
+```
+If one would rather just create a temporary environment that is not saved when
+exiting Julia you can say
+```julia
+Pkg.activate(; temp = true)
+Pkg.add("Catalyst")
+Pkg.add("Plots")
+```
+
 A more thorough guide for setting up Catalyst and installing Julia packages can be found [here](@ref catalyst_for_new_julia_users_packages).
 
 ## [Illustrative example](@id doc_index_example)