-
Notifications
You must be signed in to change notification settings - Fork 64
Development Workflow
We are in the process of updating and modernizing these instructions. Please bear with us as we work through these updates.
- Open an Issue
- Develop new feature or bug fix
- Test! Test! Test!
- Submit Pull Request
- Code Merged to Main
- Post-merge Testing
All development, whether for a new feature, bug fix, re-engineering task, or documentation or data update, MUST begin with opening an issue. An open issue allows for transparency, developer and community input, assignment of the task, and progress tracking.
To open an issue, follow these steps
Coding should take place in a branch in your GitHub fork. If you have not yet created a fork of ccpp-framework, you can create one at https://github.com/NCAR/ccpp-framework/fork by selecting your username from the "Owner" dropdown menu.
A number of tests are required to pass prior to a PR being merged, and it is highly recommended that you run as many of these tests as possible prior to opening your PR.
CI tests (found in ccpp-framework/.github/workflows/) are set to run automatically once a PR is opened. These are mainly unit tests for exercising various parts of the framework system, but there are also "smoke tests" for certain components, such as the ccpp_track_variables.py script. More testing may be rolled into continuous integration in the future as well.
Tests specific to "prebuild" (ccpp_prebuild.py) are contained in the top-level test_prebuild/ directory. Other tests, including those specific to "capgen" (ccpp_capgen.py), are contained in the top-level test/ directory. To run these tests, navigate to the appropriate directory and run the test scripts; in test_prebuild/ this script is ./run_all_tests.sh, in test/ these scripts are run_fortran_tests.sh and pylint_test.sh. You will need to have all of the framework prerequisites installed (Python 3.8 or higher, a compatible C and Fortran compiler, with MPI enabled) as well as cmake, make, and the python package pytest.
Because the CCPP framework does not generate data on its own except to create software caps, regression testing is done in the context of a host model utilizing the framework. When opening a PR to the develop branch, you should ensure regression testing is passing (or at least, has expected differences with no errors) in one or more host models with your latest code.
The CCPP Single-Column Model (SCM) has a regression test that is run automatically on all PRs that are opened to the SCM repository. To run the tests manually, you can reference the GitHub CI file for running the tests
The UFS Weather Model has a regression test documented here: https://github.com/ufs-community/ufs-weather-model/wiki/Running-regression-test-using-rt.sh
The Community Earth System Model has a regression test documented here:
To submit a pull request, use GitHub's "New pull request" button and set the proper compare (your development) and base (the branch on this repository to which to merge your development). All development should be committed to the develop branch outside of special cases (like release branches).
- Enter a short description in the title bar
- In the description text box, enter a longer description with information about the change.
- Using proper syntax, enter the issues which are resolved by this pull request (e.g., fixes #42). If there is no issue, create one to describe the problem this PR is solving.
- Add appropriate labels
- Add an appropriate set of reviewers including, at least, the CODEOWNERS.
- Assign the PR to yourself or to a member of CODEOWNERS.
If you are assigned as a reviewer of a pull request, please review the code as soon as possible. If you feel that you do not have the time or expertise to review the PR, you may remove your name from the list of reviewers unless you are the last reviewer from your organization. One person from each participating organization must review each PR.
After a PR has received the required approvals, and there are no additional requested changes or failing tests, a code manager should merge the PR to the develop branch. This merge should be performed via the "Squash-and-Merge" method. This method keeps the commit history concise, with only one commit per pull request, allowing for an easy-to-navigate code history.
After a PR is merged, the changes have been incorporated into the develop branch. However, most host models will not point to the top of develop directly, but rather to tags or hashes from the main branch. This main branch is updated occasionally (on a weekly-to-monthly basis) when a stable hash is available that can pass required tests (regression tests and any others as specified by each host's code management policies). These changes should be made via a pull request from the develop branch to main. However, when merging a PR for these main-branch updates, the traditional merge strategy should be used, to preserve the history of each pull request as a separate commit in the main branch.
The develop branch represents the "latest and greatest" CCPP Framework developments. While the top of develop should have passed all framework-specific tests, it has not necessarily been tested with all host models. Because it is a heavy lift to run all regression tests for the hosts, especially the UFS Weather Model, the main branch will only occasionally (on a weekly-to-monthly basis)