EnergyModelsX · JulStraus · Apr 19, 2024 · Apr 19, 2024
diff --git a/NEWS.md b/NEWS.md
@@ -3,6 +3,7 @@
 ## Unversioned
 
 * Updated a link in the documentation for the examples.
+* Provided a contribution section in the documentation.
 
 ## Version 0.5.5 (2024-03-21)
 
@@ -50,8 +51,7 @@
 
 ### Create a variable :spill for hydro storage node
 
-* This variable enables hydro storage nodes to spill water from the reservoir without
-   producing energy.
+* This variable enables hydro storage nodes to spill water from the reservoir without producing energy.
 
 ## Version 0.4.1 (2023-08-31)
 
@@ -65,10 +65,10 @@
 
 ## Version 0.4.0 (2023-06-06)
 
-### Switch to TimeStruct.jl
+### Switch to TimeStruct
 
-* Switched the time structure representation to [TimeStruct.jl](https://github.com/sintefore/TimeStruct.jl).
-* TimeStruct.jl is implemented with only the basis features that were available in TimesStructures.jl. This implies that neither operational nor strategic uncertainty is included in the model.
+* Switched the time structure representation to [`TimeStruct`](https://github.com/sintefore/TimeStruct.jl).
+* `TimeStruct` is implemented with only the basis features that were available in `TimeStructures`. This implies that neither operational nor strategic uncertainty is included in the model.
 
 Version 0.3.0 (2023-05-30)
 

diff --git a/docs/make.jl b/docs/make.jl
@@ -18,7 +18,7 @@ cp("NEWS.md", news; force=true)
 
 makedocs(
     modules = [EnergyModelsRenewableProducers],
-    sitename = "EnergyModelsRenewableProducers.jl",
+    sitename = "EnergyModelsRenewableProducers",
     format = Documenter.HTML(
         prettyurls = get(ENV, "CI", "false") == "true",
         edit_link = "main",
@@ -33,6 +33,9 @@ makedocs(
             "Examples"=>"manual/simple-example.md",
             "Release notes" => "manual/NEWS.md",
         ],
+        "How to" => Any[
+            "Contribute to EnergyModelsRenewableProducers" => "how-to/contribute.md",
+        ],
         "Library" =>
             Any["Public"=>"library/public.md", "Internals"=>"library/internals.md"],
     ],

diff --git a/docs/src/how-to/contribute.md b/docs/src/how-to/contribute.md
@@ -0,0 +1,36 @@
+# Contribute to EnergyModelsRenewableProducers
+
+Contributing to `EnergyModelsRenewableProducers` can be achieved in several different ways.
+
+## File a bug report
+
+Another approach to contributing to `EnergyModelsRenewableProducers` is through filing a bug report as an [_issue_](https://github.com/EnergyModelsX/EnergyModelsRenewableProducers.jl/issues/new) when unexpected behaviour is occuring.
+
+When filing a bug report, please follow the following guidelines:
+
+1. Be certain that the bug is a bug and originating in `EnergyModelsRenewableProducers`:
+    - If the problem is within the results of the optimization problem, please check first that the nodes are correctly linked with each other.
+      Frequently, missing links (or wrongly defined links) restrict the transport of energy/mass.
+      If you are certain that all links are set correctly, it is most likely a bug in `EnergyModelsRenewableProducers` and should be reported.
+    - If the problem occurs in model construction, it is most likely a bug in either `EnergyModelsBase` or `EnergyModelsRenewableProducers` and should be reported in the respective package.
+      The error message of Julia should provide you with the failing function and whether the failing function is located in `EnergyModelsBase` or `EnergyModelsRenewableProducers`.
+      It can occur, that the last shown failing function is within `JuMP` or `MathOptInterface`.
+      In this case, it is best to trace the error to the last called `EnergyModelsBase` or `EnergyModelsRenewableProducers` function.
+    - If the problem is only appearing for specific solvers, it is most likely not a bug in `EnergyModelsRenewableProducers`, but instead a problem of the solver wrapper for `MathOptInterface`.
+      In this case, please contact the developers of the corresponding solver wrapper.
+2. Label the issue as bug, and
+3. Provide a minimum working example of a case in which the bug occurs.
+
+## Feature requests
+
+`EnergyModelsRenewableProducers` includes several new nodal descriptions for renewable energy producers.
+However, there can be a demand for additional requirements for the existing nodes or for new descriptions which fall below the umbrella of renewable energy producers.
+In this case, you can contribute through a feature request.
+
+Feature requests for `EnergyModelsRenewableProducers` should follow the guidelines developed for [`EnergyModelsBase`](https://energymodelsx.github.io/EnergyModelsBase.jl/stable/how-to/contribute/).
+
+!!! note
+    `EnergyModelsRenewableProducers` is slightly different than `EnergyModelsBase`.
+
+    Contrary to the other package, we consider that it is beneficial to have all potential features of renewable energy production within `EnergyModelsRenewableProducers`.
+    Hence, if you have a requirement for a new nodal description, do not hesitate to create an [_issue_](https://github.com/EnergyModelsX/EnergyModelsRenewableProducers.jl/issues/new).
diff --git a/docs/src/index.md b/docs/src/index.md
@@ -1,11 +1,11 @@
-# EnergyModelsRenewableProducers.jl
+# EnergyModelsRenewableProducers
 
 ```@docs
 EnergyModelsRenewableProducers
 ```
 
 This Julia package implements two main nodes with corresponding JuMP constraints, extending the package
-[`EnergyModelsBase.jl`](https://energymodelsx.github.io/EnergyModelsBase.jl/)
+[`EnergyModelsBase`](https://energymodelsx.github.io/EnergyModelsBase.jl/)
 with more detailed representation of *renewable energy sources*.
 
 The first node, [`NonDisRES`](@ref), models a non-dispatchable renewable energy source, like wind power, solar power, or run of river hydropower.
@@ -27,6 +27,14 @@ Pages = [
 ]
 ```
 
+## How to guides
+
+```@contents
+Pages = [
+    "how-to/contribute.md",
+]
+```
+
 ## Library outline
 
 ```@contents

diff --git a/docs/src/manual/NEWS.md b/docs/src/manual/NEWS.md
@@ -1,83 +1,119 @@
-Release notes
-=============
+# Release notes
 
-Version 0.5.2 (2024-01-19)
---------------------------
- * Updated the documenation to be in line with the updated done in `EnergyModelsBsae`.
- * Moved `RegHydroStor` to a new file, `legacy_constructors.jl` to highlight that a user should use the new types, namely `HydroStor` and `PumpedHydroStor`.
+## Unversioned
 
-Version 0.5.1 (2024-01-17)
---------------------------
- * Update the method `constraints_level` to match the signature updates for these methods in `EnergyModelsBase`. This includes renaming `constraints_level` to `constraints_level_sp`.
- * Moved the function to `EMB.constraints_level_sp` to avoid problems.
+* Updated a link in the documentation for the examples.
+* Provided a contribution section in the documentation.
+
+## Version 0.5.5 (2024-03-21)
+
+* Minor changes to the checks to be consistent with `EnergyModelsBase` v0.6.7.
+
+## Version 0.5.4 (2024-03-04)
+
+### Examples
+
+* Fixed a bug when running the examples from a non-cloned version of `EnergyModelsRenewableProducers`.
+* This was achieved through a separate Project.toml in the examples.
+
+### NonDIsRes node
+
+* Moved the capacity constraints through the profile to the function `EMB.constraints_capacity(n::NonDisRES, ...)`, and hence, removed the function `EMB.create_node(n::NonDisRES, ...)`.
+
+### Minor updates
+
+* Added some checks and tests to the checks.
+* Restructured the test folder.
+
+## Version 0.5.3 (2024-01-30)
+
+* Updated the restrictions on the fields of individual types to be consistent.
+* Added option to not include the field `data` for the individual introduced `Node`s.
+
+## Version 0.5.2 (2024-01-19)
+
+* Updated the documenation to be in line with the updated done in `EnergyModelsBsae`.
+* Moved `RegHydroStor` to a new file, `legacy_constructors.jl` to highlight that a user should use the new types, namely `HydroStor` and `PumpedHydroStor`.
+
+## Version 0.5.1 (2024-01-17)
+
+* Update the method `constraints_level` to match the signature updates for these methods in `EnergyModelsBase`. This includes renaming `constraints_level` to `constraints_level_sp`.
+* Moved the function to `EMB.constraints_level_sp` to avoid problems.
+
+## Version 0.5.0 (2023-12-18)
 
-Version 0.5.0 (2023-12-18)
---------------------------
 ### Adjustment to release in EMB 0.6.0
- * Adjusted the code for the new release.
- * Implementation of support for `RepresentativePeriods` for `HydroStorage` nodes.
 
-Version 0.4.2 (2023-09-01)
---------------------------
-### Create a variable :spill for hydro storage node.
- * This variable enables hydro storage nodes to spill water from the reservoir without
-   producing energy.
+* Adjusted the code for the new release.
+* Implementation of support for `RepresentativePeriods` for `HydroStorage` nodes.
+
+## Version 0.4.2 (2023-09-01)
+
+### Create a variable :spill for hydro storage node
+
+* This variable enables hydro storage nodes to spill water from the reservoir without producing energy.
+
+## Version 0.4.1 (2023-08-31)
 
-Version 0.4.1 (2023-08-31)
---------------------------
 ### Split the hydro storage node into to separate nodes
- * Split `RegHydroStor` into to types `PumpedHydroStor` and `HydroStor`. Both are subtypes
+
+* Split `RegHydroStor` into to types `PumpedHydroStor` and `HydroStor`. Both are subtypes
  of the new abstract type `HydroStorage <: EMB.Storage`.
- * Fix: variational OPEX for `HydroStor` now depends on `flow_out` instead of
+* Fix: variational OPEX for `HydroStor` now depends on `flow_out` instead of
  `flow_in`. The new type `PumpedHydroStor` has a separate parameter for variational OPEX
  for the pumps, which depends on `flow_in`.
 
-Version 0.4.0 (2023-06-06)
---------------------------
-### Switch to TimeStruct.jl
- * Switched the time structure representation to [TimeStruct.jl](https://github.com/sintefore/TimeStruct.jl)
- * TimeStruct.jl is implemented with only the basis features that were available in TimesStructures.jl. This implies that neither operational nor strategic uncertainty is included in the model
+## Version 0.4.0 (2023-06-06)
+
+### Switch to TimeStruct
+
+* Switched the time structure representation to [`TimeStruct`](https://github.com/sintefore/TimeStruct.jl).
+* `TimeStruct` is implemented with only the basis features that were available in `TimeStructures`. This implies that neither operational nor strategic uncertainty is included in the model.
 
 Version 0.3.0 (2023-05-30)
---------------------------
- * Adjustment to changes in `EnergyModelsBase` v0.4.0 related to extra input data
 
-Version 0.2.2 (2023-05-15)
---------------------------
- * Adjustment to changes in `EnergyModelsBase` v 0.3.3 related to the calls for the constraint functions
+* Adjustment to changes in `EnergyModelsBase` v0.4.0 related to extra input data.
+
+## Version 0.2.2 (2023-05-15)
+
+* Adjustment to changes in `EnergyModelsBase` v 0.3.3 related to the calls for the constraint functions.
+
+## Version 0.2.1 (2023-02-03)
 
-Version 0.2.1 (2023-02-03)
---------------------------
 * Take the examples out to the folder `examples`.
 
-Version 0.2.0 (2023-02-03)
---------------------------
+## Version 0.2.0 (2023-02-03)
+
 ### Adjustmends to updates in EnergyModelsBase
+
 Adjustment to version 0.3.0, namely:
-* Changed type (`Node`) calls in tests to be consistent with version 0.3.0
-* Removal of the type `GlobalData` and replacement with fields in the type `OperationalModel` in all tests
-* Changed type structure to be consistent with EMB version 0.3.0
-* Substitution of certain constraints in `create_node` through functions which utilize dispatching on `node` types
-* Changed the input to the function `variables_node`
-
-Version 0.1.3 (2022-12-12)
---------------------------
+
+* Changed type (`Node`) calls in tests to be consistent with version 0.3.0.
+* Removal of the type `GlobalData` and replacement with fields in the type `OperationalModel` in all tests.
+* Changed type structure to be consistent with EMB version 0.3.0.
+* Substitution of certain constraints in `create_node` through functions which utilize dispatching on `node` types.
+* Changed the input to the function `variables_node`.
+
+## Version 0.1.3 (2022-12-12)
+
 ### Internal release
-* Renamed to follow common prefix naming scheme
-* Update README
 
-Version 0.1.2 (2022-12-02)
---------------------------
-* Minor test fixes in preparation of internal release
+* Renamed to follow common prefix naming scheme.
+* Update README.
+
+## Version 0.1.2 (2022-12-02)
+
+* Minor test fixes in preparation of internal release.
+
+## Version 0.1.1 (2021-09-07)
 
-Version 0.1.1 (2021-09-07)
---------------------------
 ### Changes in naming
-* Major changes in both variable and parameter naming, check the commit message for an overview
-* Change of structure in composite type "RegHydroStor"
 
-Version 0.1.0 (2021-08-23)
---------------------------
+* Major changes in both variable and parameter naming, check the commit message for an overview.
+* Change of structure in composite type "RegHydroStor".
+
+## Version 0.1.0 (2021-08-23)
+
 * Initial version with inclusion of nodes for:
-    * nondispatchable renewable energy sources (NonDisRES)
-    * regulated hydro generation (RegHydroStor, can be used for pumped hydro storage)
+  * nondispatchable renewable energy sources (NonDisRES) and
+  * regulated hydro generation (RegHydroStor, can be used for pumped hydro storage).
diff --git a/docs/src/manual/constraint-functions.md b/docs/src/manual/constraint-functions.md
@@ -1,6 +1,6 @@
 # [Constraint functions](@id constraint_functions)
 
-The [`HydroStorage`](@ref) types dispatch on individual functions from within `EnergyModelsBase.jl` ti extend the functionality
+The [`HydroStorage`](@ref) types dispatch on individual functions from within `EnergyModelsBase` ti extend the functionality
 
 ## Storage level constraints
 
@@ -22,7 +22,7 @@ EMB.constraints_level_sp(m, n::HydroStorage, t_inv, 𝒫, modeltype::EnergyModel
 ```
 
 are similar to the function used for `RefStorage{T} where {T<:ResourceCarrier}`.
-It is however necessary to reintroduce it due to the declaration for `RefStorage` in `EnergyModelsBase.jl`.
+It is however necessary to reintroduce it due to the declaration for `RefStorage` in `EnergyModelsBase`.
 This will most likely be adjusted in later versions, although it will not impact the user directly.
 
 ## Operational expenditure constraints

diff --git a/docs/src/manual/optimization-variables.md b/docs/src/manual/optimization-variables.md
@@ -1,13 +1,13 @@
 # [Optimization variables](@id optimization_variables)
 
-`EnergyModelsRenewableProduces.jl` declares new variables for the introduced `Nodes`.
+`EnergyModelsRenewableProduces` declares new variables for the introduced `Nodes`.
 The different variables are explained below including how they are introduced in different constraints.
-Thes variables are created by the method [`EMB.variables_node`](@ref) which is a method dispatched on from `EnergyModelsBase.jl`.
+Thes variables are created by the method [`EMB.variables_node`](@ref) which is a method dispatched on from `EnergyModelsBase`.
 
 ## [`NonDisRES`](@ref)
 
-`NonDisRES` is a subtype of the `Source` node declared in `EnergyModelsBase.jl`.
-Hence, it has by default the same variables as a `RefSource` node declared in `EnergyModelsBase.jl`.
+`NonDisRES` is a subtype of the `Source` node declared in `EnergyModelsBase`.
+Hence, it has by default the same variables as a `RefSource` node declared in `EnergyModelsBase`.
 
 In addition, the following new optimization variable is added:
 
@@ -24,8 +24,8 @@ The variable is used in the following constraint within [`EMB.create_node(m, n::
 
 ## [`HydroStorage`](@ref)
 
-Both [`PumpedHydroStor`](@ref) and [`HydroStor`](@ref) are in a fist instance subtypes of [`HydroStorage`](@ref), and hence, subtypes of the `Storage` node declared in `EnergyModelsBase.jl`.
-Hence, it has by default the same variables as a `RefStorage` node declared in `EnergyModelsBase.jl`.
+Both [`PumpedHydroStor`](@ref) and [`HydroStor`](@ref) are in a fist instance subtypes of [`HydroStorage`](@ref), and hence, subtypes of the `Storage` node declared in `EnergyModelsBase`.
+Hence, it has by default the same variables as a `RefStorage` node declared in `EnergyModelsBase`.
 
 In addition, the following new optimization variable is added: