Description of Branches
There are several primary repository branches for specific development tracks.
This is the stable release branch. It is updated from the develop branch and tagged prior to each release. The melodies-monet conda package is created from main.
This is the parent branch in which to consolidate the various development tracks. General practice, when working within the central repository, is to create a working branch, branched from develop, with a naming convention such as develop_topic. The develop_topic branches are merged back to develop via pull requests. Forks of the central repository should follow the same branching conventions.
The develop_aircraft branch is the place for adding new features related to aircraft observations.
The develop_satellite branch is intended for adding support for reading and processing satellite observations. This includes both gridded satellite data products and swath or geostationary disk data products. Sub-branches are sometimes created off of develop_satellite, such as develop_satellite_swath.
The develop_testsuite branch holds modules under development for unit tests and regression tests.
Setting up your development environment
In order to prepare for developing MELODIES MONET, we clone the repositories and create a conda environment that references them.
If you are installing MELODIES MONET on NCAR Cheyenne or NOAA Hera follow these machine specific instructions instead.
The instructions below are for cloning a repository using SSH. If you prefer, you can also clone the monet, monetio, and MELODIES-MONET repositories using HTTPS 1.
To install MELODIES MONET on your laptop or on HPC machines in general follow these instructions:
Set up a conda environment with all the dependencies, including MONET and MONETIO:
$ conda create --name melodies-monet python=3.9 $ conda activate melodies-monet $ conda install -y -c conda-forge pyyaml monet monetio netcdf4 wrf-python click pooch jupyterlab
Clone 1 and link the latest development versions of MONET and MONETIO from GitHub to your conda environment:
$ git clone firstname.lastname@example.org:noaa-oar-arl/monet.git $ cd monet $ git checkout develop $ pip install --force-reinstall --no-deps --editable . $ git clone email@example.com:noaa-oar-arl/monetio.git $ cd monetio $ git checkout develop $ pip install --force-reinstall --no-deps --editable .
Clone 1 and link the latest development version of the MELODIES MONET:
$ git clone firstname.lastname@example.org:NOAA-CSL/MELODIES-MONET.git $ cd MELODIES-MONET $ git checkout develop $ pip install --force-reinstall --no-deps --editable .
How to incorporate updates to MELODIES MONET
In order to contribute code to MELODIES MONET, you will need to fork the repository, make changes on your fork, and submit a pull request with your changes.
Fork the GitHub repository to your own GitHub account using the “Fork” button near the top right:
You can pull updates from the main NOAA repository by using the “Fetch Upstream” button on your fork. Alternatively: 1
$ git remote add upstream email@example.com:NOAA-CSL/MELODIES-MONET.git $ git pull upstream main $ git push origin main
Navigate on your working machine to where you would like to keep the MELODIES-MONET code (e.g. in your work location) and clone 1 your fork:
$ git clone firstname.lastname@example.org:$GitHubUsername/$ForkName.git
Checkout the develop branch — you need to do this with the remote branch as well as create a local tracking branch:
$ git checkout origin/develop $ git checkout develop
Then all development work will be in the
$ cd melodies_monet
Make changes to your fork.
Submit a pull request back to the main MELODIES MONET repository with your changes.
User’s Guide Development
If you add a component to MELODIES MONET, please follow the instructions below to update the readthedocs user guide.
This User’s Guide has been generated by the Sphinx documentation system. This requires adding the following packages to your conda environment in order to build the HTML docs.
Either use the
docs/environment-docs.yml file 2
from the MELODIES MONET repository,
or add the following packages to your conda environment manually:
$ conda install -y -c conda-forge sphinx sphinx_rtd_theme myst-nb sphinx-design
The restructured text sources (rst) are located in the MELODIES-MONET/docs folders. The rst files may be edited and new files added to document any package modifications or new MELODIES MONET components.
To build the HTML docs:
$ cd docs $ make clean $ make html
The generated HTML will be created in
docs/_build/html/index.html the main page that can be
viewed in any browser.
Please see the Documentation project on GitHub to learn about current and future development.
Note that in order to do an SSH clone, e.g.
$ git clone email@example.com:noaa-oar-arl/monet.git
you must have already added an SSH key to your GitHub account for your current machine. If you are new to GitHub, check out this GitHub tutorial. We recommend the SSH method, but if you don’t add an SSH key you can still clone the repositories via HTTPS, e.g.
$ git clone https://github.com/noaa-oar-arl/monet.git
That is, use:
$ conda env update -n melodies-monet -f docs/environment-docs.yml
to update your existing conda environment, or:
$ conda env create -f docs/environment-docs.yml
to create a new conda environment (