From 0a6b9a3e5c093969b0c274ae63c2d6732954659d Mon Sep 17 00:00:00 2001 From: Sam Isaacson Date: Fri, 1 Nov 2024 14:46:52 -0400 Subject: [PATCH 1/5] start on release process devdoc --- docs/pages.jl | 3 ++- docs/src/devdocs/dev_guide.md | 32 ++++++++++++++++++++++++++++++++ 2 files changed, 34 insertions(+), 1 deletion(-) create mode 100644 docs/src/devdocs/dev_guide.md diff --git a/docs/pages.jl b/docs/pages.jl index bfb450d301..79525e3f81 100644 --- a/docs/pages.jl +++ b/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" ] diff --git a/docs/src/devdocs/dev_guide.md b/docs/src/devdocs/dev_guide.md new file mode 100644 index 0000000000..b2a998951e --- /dev/null +++ b/docs/src/devdocs/dev_guide.md @@ -0,0 +1,32 @@ +# 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 + passes test. + - 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. +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). 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*. \ No newline at end of file From 7228fd37941fe0730e26b1d26974fcfefcf2d5b6 Mon Sep 17 00:00:00 2001 From: Sam Isaacson Date: Fri, 1 Nov 2024 14:55:41 -0400 Subject: [PATCH 2/5] add more detail on creating environments --- docs/src/index.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/docs/src/index.md b/docs/src/index.md index 1db58e8c6d..49533f9f43 100644 --- a/docs/src/index.md +++ b/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) From 8a3379c49980233dc5c092f6fa2049078a4f9fe8 Mon Sep 17 00:00:00 2001 From: Sam Isaacson Date: Fri, 1 Nov 2024 15:06:55 -0400 Subject: [PATCH 3/5] updates --- HISTORY.md | 7 ++++++- docs/src/devdocs/dev_guide.md | 5 +++-- 2 files changed, 9 insertions(+), 3 deletions(-) diff --git a/HISTORY.md b/HISTORY.md index afdb28ebea..aeb6e3dcde 100644 --- a/HISTORY.md +++ b/HISTORY.md @@ -1,14 +1,19 @@ # Breaking updates and feature summaries across releases ## Catalyst unreleased (master branch) +- Scoped species/variables/parameters are now treated similar to the latest MTK releases (≥ 9.49). - 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. + 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 constructor + `ReactionSystem` may become unscalarized. - 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 diff --git a/docs/src/devdocs/dev_guide.md b/docs/src/devdocs/dev_guide.md index b2a998951e..25a6ca95df 100644 --- a/docs/src/devdocs/dev_guide.md +++ b/docs/src/devdocs/dev_guide.md @@ -6,10 +6,11 @@ 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 - passes test. + 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. + 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). From 95f80b1f4f81609687232f12394da6cb56fe4b08 Mon Sep 17 00:00:00 2001 From: Sam Isaacson Date: Fri, 1 Nov 2024 15:11:50 -0400 Subject: [PATCH 4/5] update HISTORY --- HISTORY.md | 21 ++++++++++++++++----- 1 file changed, 16 insertions(+), 5 deletions(-) diff --git a/HISTORY.md b/HISTORY.md index aeb6e3dcde..2039c44398 100644 --- a/HISTORY.md +++ b/HISTORY.md @@ -1,17 +1,28 @@ # Breaking updates and feature summaries across releases ## Catalyst unreleased (master branch) -- Scoped species/variables/parameters are now treated similar to the latest MTK releases (≥ 9.49). -- 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. Note, scalarized parameter arrays passed to the two-argument constructor - `ReactionSystem` may become unscalarized. -- The structural identifiability extension is currently disabled due to issues StructuralIdentifiability has with Julia 1.10.5 and 1.11. + 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. From ac2f251dad9ab02c4d66d3f2dc2578f13b580207 Mon Sep 17 00:00:00 2001 From: Sam Isaacson Date: Sat, 2 Nov 2024 15:44:33 -0400 Subject: [PATCH 5/5] link semver --- docs/src/devdocs/dev_guide.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/src/devdocs/dev_guide.md b/docs/src/devdocs/dev_guide.md index 25a6ca95df..691b5b3e3f 100644 --- a/docs/src/devdocs/dev_guide.md +++ b/docs/src/devdocs/dev_guide.md @@ -24,10 +24,10 @@ continuing stability of releases. Before making a release one should 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). 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*. \ No newline at end of file +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*. \ No newline at end of file