Contributing to development
We welcome contributions to the code base and development of new features for the MESSAGEix framework. This page contains guidelines for making such contributions. Each section requires some of the listed prerequisite knowledge and skills; use the links there to external resources about git, Github, Python, etc. to ensure you are able to understand and complete the steps.
On this page:
On separate pages:
We use Github issues for several purposes:
Ask and answer questions about intended behaviour or issues running the framework or related models.
Report bugs, i.e. unintended or undocumented behaviour.
Request changes to exiting behaviour.
Request specific enhancements and new features, both urgent and long-term/low-priority.
Discuss and design of other improvements.
Decide which part of the MESSAGEix software stack is the appropriate location for your code:
Contributions not specific to MESSAGEix model framework, e.g. that could be used for other, non-MESSAGE models.
- ixmp_source (closed source)
Java / JDBC backend for
Contributions not specific to any particular MESSAGEix model instance. Additions to
message_ixshould be usable in any MESSAGE-scheme model.
Contributions to the MESSAGE-GLOBIOM family of models, including the global model, and its documentation.
Register a Github account, if you do not already have one. Fork the chosen repository to your own Github account. Create a branch with an appropriate name:
_) are slower to type; don’t use them.
issue/1234if you are addressing a specific issue.
feature/do-somethingif you are adding a new feature.
Don’t use the
mainbranch in your fork for a PR. This makes it hard for others to check out and play with your code.
Open a PR (e.g. on message_ix) to merge your code into the
ixmp repositories each have a template for the text of the PR that is designed to help you write a clear description.
A title and one-sentence summary of the change. This is like the abstract of a publication: it should help a developer/reviewer/user quickly learn what the PR is about.
Confirm that unit or integration tests have been added or revised to cover the changed code, and that the tests pass (see below).
Confirm that documentation of the API and its usage is added or revised as necessary.
Add a line to
RELEASE_NOTES.rstdescribing the changes (use the same title or one-sentence summary as above) and linking to the PR.
Assign yourself and anyone else who will actually commit changes to the PR branch, or be actively involved in discussing/designing the code.
Include a longer description of the design, or any changes whose purpose is not clear by inspecting code.
Put “WIP:” or the construction sign Unicode character (🚧) at the start of the PR title to indicate “work in progress” while you continue to add commits; or use GitHub’s ‘draft’ pull requests feature. This is good development practice: it ensures the automatic checks pass as you add to the code on your branch.
MESSAGEix has several kinds of automatic, or continuous integration, checks:
The CLA Assistant ensures you have signed the Contributor License Agreement (follow link for text). All contributors are required to sign the CLA before any pull request can be reviewed. This ensures that all future users can benefit from your contribution, and that your contributions do not infringe on anyone else’s rights.
GitHub Actions is used to run several workflows. These are defined by YAML files in
This workflow runs all Python and R tests; on Linux, macOS, and Windows; and for multiple versions of Python.
Checks that the documentation can be built without fatal errors.
Checks that the code style is applied.
This workflow checks that the Python package (for upload to PyPI) can be built cleanly and without errors.
The package is not actually uploaded, unless this workflow is started from a release candidate tag or on the creation of a new release on GitHub.
These tests run daily at 05:00 UTC. They download a particular package of full-scale, MESSAGEix-GLOBIOM global model scenarios from IIASA servers. Each scenario’s outputs are compared to an expected value listed in
message_ix/tests/data/scenarios.yaml. PRs that touch the GAMS code may cause the these objective function values to change; the values must be updated as part of such PRs. See the comments in the file for how to temporarily enable these checks for every commit on a PR branch.
- anaconda, miniconda
These workflows check that the package can be installed from conda-forge using Anaconda and Miniconda, respectively, on Windows only.
Resolve any non-passing checks—seeking help if needed.
If your PR updates the documentation, the
lint check will confirm that it can be built.
However, you should also manually build and view the HTML documentation on your machine to confirm that the generated HTML is as expected, and address any warnings generated by Sphinx during the build phase.
Using the GitHub sidebar on your PR, request a review from another MESSAGEix contributor. GitHub suggests reviewers; optionally, contact the IIASA ECE Program to ask who should review your code.
If you want them to follow along with progress, tag them in the PR description, like “FYI @Alice @Bob”.
Only formally request review once the code is ready to review. Doing this sends e-mail and other notifications (e.g. in Slack, the “Pull Reminders” bot sends notices every day). If the code is not yet complete and ready for review, these notifications are noise.
Address any comments raised by the reviewer.
GitHub provides three ways to incorporate a pull request: merge, rebase, and squash.
Current practice for the
message_data repositories is:
Use squash and merge…
if the commit history for the PR is “messy”, e.g. there are many merge commits from other branches, or the author did not write well-formatted commit messages (see “Code style”, below).
if the PR is very old, i.e. it starts at an old commit on
main. However, it is better to rebase the PR branch on the HEAD of
mainand then use a merge commit (below).
Use rebase and merge…
if the PR is only one or a few commits that are obviously related.
if the PR does not involve user-facing changes, i.e. does not need to be linked from the release notes.
Use merge pull request (also written “create a merge commit”) in all other cases.
PR branches should be rebased on the HEAD of
mainbefore merging. This is because some git-based tools will display commits from
mainand the PR branch interleaved if their dates and times are mixed, which makes it harder to read the commit history. Rebasing avoids this problem by ensuring each PR’s commits are displayed together & in sequence.
For both commit messages and pull request (PR) titles, memorize and use the “7 rules of a great Git commit message”.
Follow the PEP 8 naming conventions.
Apply black code formatting.
Add type hints to new or changed functions, methods, and global variables, and check these using the mypy static type checker.
To simplify the use of these tools:
Black, ruff, and mypy can each be configured to run automatically within your code editor with an extension, plugin, or script (see their respective documentation for links and details). These tools help apply the code style every time a file is saved, or even as you type.
The source repository contains configuration for pre-commit, a tool that invokes multiple actions via git hooks. This runs all of the above checks every time you do a git commit. To use this tool, install pre-commit and install it in your local checkout of the Git repository:
pip install pre-commit pre-commit install -f # Run the tools on all files to confirm they are working pre-commit run --all-files
To force mypy type checking to use packages from an existing Python virtual environment on your system (for instance, with development code), set the
PRE_COMMIT_MYPY_VENVenvironment variable to the path to that environment.
The “Code quality” job in the “pytest” workflow described above applies exactly the same checks for PR branches. PRs that fail the checks must be corrected before they can be merged.
Wrap lines at 121 characters, except for inline documentation (see above).
R code: follow the style of the existing code base.
Jupyter notebooks (
.ipynb): see Developing tutorials.
Other (file names, CLI, etc.): follow the style of the existing code base, e.g.:
Use lower-case file names and extensions.
Except for Python source files, prefer hyphens to underscores.
Write documentation in ReStructuredText formats for:
Inline documentation in
For (2) and (3), start each sentence on a new line, and do not hard-wrap within sentences. For (1), wrap at the same 88 characters as black enforces for code.
Ensure Sphinx does not give warnings about ReST syntax for new or modified documentation.
sphinx.ext.intersphinx(click for docs) to create cross-links within one project’s documentation, or across projects.
Understand the use of the
.characters to resolve references across the project. See Cross-referencing syntax in the Sphinx docs.
See example usage in existing code.
Check that intersphinx links are correctly resolved, by building the docs and attempting to click new or modified links.
Use single backticks to refer to function arguments, and asterisks for italics:
def func(foo: str, bar: str) -> float: """Perform some action. If `foo` and `bar` have the same value, ``42.1`` is returned. *Nice!* """
reStructuredText Primer in the Sphinx docs.
Assign an issue or PRs to the person(s) who must take the next action towards completing it. For example:
Comment on the issue to provide information/decisions needed to move forward.
Implement the requested changes in code.
This might be different from the person who opened the issue/PR.
Use the GitHub auto-linking feature to make clear the connection between related issues and PRs.
Look at the labels, milestones, and projects in the right sidebar. Associate the issue with the correct one(s).
Follow-up on old issues (ones with no activity for a month or more):
Ask (in a new comment, on Slack, in person) the assignee or last commenter what the status is.
Close or re-assign, with a comment that describes your reasoning.