Steps to register a new version of the REopt package - NatLabRockies/REopt.jl GitHub Wiki

Steps for REopt.jl

  • Branch off of REopt.jl master branch to make a [feature_branch] and add features/changes
    • Keep the [feature_branch] up to date with master periodically, and right before opening a PR
  • Non-exhaustive list of things to consider in your development:
    • Include tests of new features/changes in runtests.jl or a separate file that get's loaded into runtests.jl (e.g. test_chp.jl)
    • Add or update REopt.jl help text/doc strings, descriptive of model behavior
    • Add a section in the CHANGELOG.md file under the title of [feature_branch]. Add any new files to REopt.jl/docs. Writing up documentation and the tests can help inform development.
    • Check if your changes require updates to the function initial_capex_no_incentives() or function proforma_results()
    • Check if your changes require updates to the inputs, outputs, and/or results downloads Excel or Proforma Excel code, both are which are in REopt_API (see reoptjl/ -> models.py and custom_table_config.py, proforma/proforma_generator.py)
    • If your changes require update to the REopt_API (for whenever the API updates the version of REopt.jl that it uses), either flag this in the PR comment for another developer to help update the API or you can make the API updates yourself (see farther below).
  • Open a PR: master <- [feature_branch]
    • Have copilot first do a "lite" review and address comments before adding a person reviewer.
    • Have at least one person reviewer approve the PR.
    • If you've added a new dependency, the Julia Pkg manager won’t manually update the [compat] section of Project.toml (you will see the new dependency under [deps] but not [compat]). You must manually update [compat] with packages and version #(s). See guidance here.
    • Note, keep the [feature_branch] section of the CHANGELOG.md separate with a space before and after the section, to avoid conflicts.
    • Merge into master, then delete the [feature_branch] at the bottom of the closed PR.
    • An admin will merge the feature branch sections of the CHANGELOG.md file when a new registered version is released (see below).
    • Note, this does not yet publicly release a new REopt.jl version in Julia (see next step).
  • Once a new version release is wanted (possibly after multiple feature_branch merges), an admin can help update the master branch with:
    • Merge the feature branch section(s) of CHANGELOG.md into a single heading with the new version # (following Semantic Versioning rules).
    • Change the REopt version # manually in Project.toml.
    • Go to repo landing page → go to last merge commit → comment at bottom: @JuliaRegistrator register. Note:
    • If you are updating a Minor version, e.g. 0.52.0 to 0.53.0, and REopt.jl is still not a "stable" package (1.0 +), the JuliaRegistrator requires an explanation of the "breaking change", i.e.:
@JuliaRegistrator register

Release notes:
- Non-breaking release note 1

## Breaking changes

- Explanation of breaking change, ideally with upgrade tips
- ...
  • Go to Releases → Draft new release
    • Tag = version #
    • Target = master
    • Summary can be from the Changelog (or can use "Generate release notes" functionality); title can be same as PR title
    • This creates a GitHub tag; doesn’t affect Julia pkg version (the @JuliaRegistrator register command does this)
  • Important Note: The REopt_API calls a specified version of this REopt.jl package (see here), typically the officially-registered version. If you change or add inputs or outputs to REopt.jl, you'll need to update/add the linkages between the REopt_API and REopt.jl before updating the REopt.jl version used by the API. (See steps below)

Steps for REopt_API

  • Branch off of REopt_API master branch to make a [feature-branch] (use hyphens/dashes instead of underscores, if needed, to avoid URL weirdness)
  • In reoptjl/models.py, add or modify any inputs or outputs to align with the changes made in REopt.jl (see steps above).
  • To update the REopt.jl version (or branch, for testing) from within the Docker environment in the julia_src/ directory:
    • Run from the REopt_API directory: docker compose build (if not built already), docker compose up (see more here on building Docker images)
    • In the Docker plugin in VSCode or Docker Desktop: attach shell to the julia_api container. (If in VSCode, click the whale (or container symbol), right click the julia_api container and click "Attach Shell")
    • Spin up Julia and activate this directory with: julia --project=.
    • Open package manager with ]
    • Do one of the following:
      • pkg> update REopt to update the version called by the API to the officially registered version.
      • pkg> add REopt#branchname to point to your dev branch for testing
      • Ensure you "update REopt" and free REopt prior to merging into master.
      • pkg> update to reset any changes you may have accidentally made to the Manifest.
  • If any inputs or outputs are modified in any way (i.e., if any classes or fields in models.py are changed), make sure to make database migrations. Do docker compose up (potentially need to "build" first) from the root REopt_API directory, attach shell to the django or celery container, and run:
python manage.py makemigrations
python manage.py migrate

A new migration file should appear under reoptjl/migrations. Note: If you cannot start the django or celery servers, in the root directory do docker compose down -v, then docker compose build and repeat the steps.

  • Make sure your updates don't break any tests by pushing commits to the remote github.com which will run the CI tests (reoptjl.test.test_job_endpoint and reoptjl.test.test_http_endpoints files).
  • Create a draft PR for master <- [feature-branch].
  • See these steps for API staging testing with a snapshot of the production database, and web development (if needed), before merging into master for production/public deployment: Pull-Request,-Staging,-and-Production-Deployment-Process
  • Think about web tool updates related to your branch: Did you change defaults, input or output names, or endpoints?, Do you need to update tooltips for inputs or outputs?, Do you need to update input or output fields? Work with the web tool team on these changes as soon as possible.
  • Update PR from draft to "ready for review"
    • Update CHANGELOG with changes, make the header the new REopt_API version (this is distinct from the REopt.jl version)
    • Make sure the new REopt.jl version is updated in julia_src as described above
  • Ensure any changes to defaults are also reflected in the web tool, and deployed at the same time as the API deploy
  • Merge into master and then wait for the CI Actions to pass. This has not yet deployed the API to production (see next step).
  • Once ready to deploy to production (and CI Actions tests have passed), merge the branch's PR in the mirrored repository to auto-deploy to staging then production
  • Once merged, publish a new release of the API with a description of the changes.

Additional Checklist