Developer documentation
If you haven't, please read the Contributing guidelines first.
If you want to make contributions to this package that involves code, then this guide is for you.
Current branch plan
The repository branch transition is complete:
mainis the active development branch. All contributions go here.- The legacy
master(pre-v2, Maryland-focused) is archived as a separate repository: HOPE-MD.
Contributors should branch from and open pull requests into main.
First time clone
If you have write access to the main repository, you can clone it directly and skip the fork workflow.
If this is the first time you work with this repository, the safest setup is:
Fork the repository if you do not have write access.
Clone your fork, which creates a git remote called
origin.Add the main repository as
upstream:git remote add upstream https://github.com/HOPE-Model-Project/HOPE.jl.gitFetch the latest branches:
git fetch upstreamCreate your working branch from
upstream/main:git switch -c my-change upstream/main
Linting and formatting
Install a plugin on your editor to use EditorConfig. This will ensure that your editor is configured with important formatting settings.
We use https://pre-commit.com to run the linters and formatters. In particular, the Julia code is formatted using JuliaFormatter.jl, so please install it globally first:
julia> # Press ]
pkg> activate
pkg> add JuliaFormatterTo install pre-commit, we recommend using pipx as follows:
# Install pipx following the link
pipx install pre-commitWith pre-commit installed, activate it as a pre-commit hook:
pre-commit installTo run the linting and formatting manually, enter the command below:
pre-commit run -aNow, you can only commit if all the pre-commit tests pass.
Testing
For standard validation, open Julia in the repository folder, activate the environment, and run test:
julia> # press ]
pkg> activate .
pkg> testFor documentation changes, also validate the docs environment when practical:
julia --project=docs docs/make.jlIf your change touches workflow files, verify the target branch names and trigger conditions at the same time.
Working on a new issue
We try to keep a linear history in this repo, so it is important to keep your branches up-to-date.
Fetch from the remote and fast-forward your local
maingit fetch upstream git switch main git merge --ff-only upstream/mainBranch from
mainto address the issue (see below for naming)git switch -c 42-add-answer-universePush the new local branch to your personal remote repository
git push -u origin 42-add-answer-universeCreate a pull request targeting
main.
Branch naming
- If there is an associated issue, add the issue number.
- If there is no associated issue, and the changes are small, add a prefix such as "typo", "hotfix", "small-refactor", according to the type of update.
- If the changes are not small and there is no associated issue, then create the issue first, so we can properly discuss the changes.
- Use dash separated imperative wording related to the issue (e.g.,
14-add-tests,15-fix-model,16-remove-obsolete-files).
Commit message
- Use imperative or present tense, for instance: Add feature or Fix bug.
- Have informative titles.
- When necessary, add a body with details.
- If there are breaking changes, add the information to the commit message.
Before creating a pull request
Try to create "atomic git commits" (recommended reading: The Utopic Git History by Carlos Martinez Ortiz, Netherlands eScience Center).
Make sure the tests pass.
Make sure the pre-commit tests pass.
Fetch any
mainupdates from upstream and rebase your branch, if necessary:git fetch upstream git rebase upstream/main BRANCH_NAMEThen you can open a pull request and work with the reviewer to address any issues.
Building and viewing the documentation locally
Following the latest suggestions, we recommend using LiveServer to build the documentation. Here is how you do it:
- Run
julia --project=docsto open Julia in the environment of the docs. - If this is the first time building the docs
- Press
]to enterpkgmode - Run
pkg> dev .to use the development version of your package - Press backspace to leave
pkgmode
- Press
- Run
julia> using LiveServer - Run
julia> servedocs()
Making a new release
- Create a branch
release-x.y.zfrommain - Update
versioninProject.toml - Update release notes or changelog material if you are maintaining one for the release.
- Create a release PR targeting
main. - Verify test, lint, and docs workflows on that PR.
- Merge only after the release branch strategy, docs deployment branch, and badges all agree.
Initial registration in General
HOPE's existing GitHub tags predate registration in Julia's General registry. The first registry submission is therefore a new-package registration, not a new-version registration.
After the final release commit is reviewed and merged to main:
Confirm that the JuliaRegistrator GitHub App is installed for this repository. Only a repository collaborator or a public member of the owning organization can trigger it.
Open the final commit on GitHub and add this comment:
@JuliaRegistrator register Release notes: HOPE 2.0 adds the DART SCUC/SCED and settlement APIs, EREC postprocessing, representative-day and resource-aggregation workflows, and the holistic GTEP-to-PCM handoff. This is a breaking release: transmission cases must replace `Capacity (MW)` with `Forward Capacity (MW)` and `Reverse Capacity (MW)`; see CHANGELOG.md.On the General registration pull request, explain that HOPE is the established, published name for the Holistic Optimization Program for Electricity. Its four-letter uppercase acronym and repository URL without a
.jlsuffix do not satisfy the conservative automatic-name checks, so the initial registration needs manual review. Do not change the package UUID.Wait for the required new-package review period and address RegistryCI or maintainer feedback. Registration is permanent; do not merge around a substantive unresolved concern.
After the General pull request merges, let TagBot create
v2.0.0and the GitHub release. Confirm that theDOCUMENTER_KEYsecret contains the private half of a write-enabled deploy key so the tag-triggered docs workflow can run. Do not create the release tag before registration.
If the GitHub App cannot be installed, use Registrator's JuliaHub web interface with the same final commit and release notes.