Developer’s Guide to Common Tasks#

Setting up and Typical Development Workflow#

  1. Clone the repository.

  2. Install the required packages. MontePy comes with the requirements specfied in pyproject.toml. Optional packages are also specified. To install all packages needed for development simply run:

    pip install .[develop]

  3. Tie your work to an issue. All work on MontePy is tracked through issues. If you are working on a new feature or bug that is not covered by an issue, please file an issue first.

  4. Work on a new branch. The branches: develop and main are protected. All new code must be accepted through a merge request or pull request. The easiest way to make this branch is to “create pull request” from github. This will create a new branch (though with an unwieldy name) that you can checkout and work on.

  5. Run the test cases. MontePy relies heavily on its over 380 tests for the development process. These are configured so if you run: pytest from the root of the git repository all tests will be found and ran.

  6. Develop test cases. This is especially important if you are working on a bug fix. A merge request will not be accepted until it can be shown that a test case can replicate the bug and does in deed fail without the bug fix in place. To achieve this, it is recommended that you commit the test first, and push it to gitlab. This way there will be a record of the CI pipeline failing that can be quickly reviewed as part of the merge request.

    MontePy is currently working on migrating from unittest to pytest for test fixtures. All new tests should use a pytest architecture. Generally unit tests of new features go in the test file with the closest class name. Integration tests have all been dumped in tests/test_integration.py. For integration tests you can likely use the tests/inputs/test.imcnp input file. This is pre-loaded as an MCNP_Problem stored as: self.simple_problem. If you need to mutate it at all you must first make a copy.deepcopy of it.

  7. Write the code.

  8. Document all new classes and functions. MontePy uses Sphinx docstrings.

  9. Format the code with black. You can simply run black montepy tests

  10. Add more test cases as necessary. The merge request should show you the code coverage. The general goal is near 100% coverage.

  11. Update the documentation. Read the “Getting Started” guide and the “Developer’s Guide”, and see if any information there should be updated. If you expect the feature to be commonly used it should be mentioned in the getting started guide. Otherwise just the docstrings may suffice. Another option is to write an example in the “Tips and Tricks” guide.

  12. Update the authors as necessary. The authors information is in AUTHORS and pyproject.toml.

  13. Start a merge request review. Generally Micah (@micahgale) or Travis (@tjlaboss) are good reviewers.

Deploy Process#

MontePy currently does not use a continuous deploy (CD) process. Changes are staged on the develop branch prior to a release. Both develop and main are protected branches. main is only be used for releases. If someone clones main they will get the most recent official release. Only a select few core-developers are allowed to approve a merge to main and therefore a new release. develop is for production quality code that has been approved for release, but is waiting on the next release. So all new features and bug fixes must first be merged onto develop.

The expectation is that features once merged onto develop are stable, well tested, well documented, and well-formatted.

Merge Checklist#

Here are some common issues to check before approving a merge request.

  1. If this is a bug fix did the new testing fail without the fix?

  2. Were the authors and credits properly updated?

  3. Check also the authors in pyproject.toml

  4. Is this merge request tied to an issue?

Deploy Checklist#

For a deployment you need to:

  1. Run the deploy script : .github/scripts/deploy.sh

  2. Manually merge onto main without creating a new commit. This is necessary because there’s no way to do a github PR that will not create a new commit, which will break setuptools_scm.

  3. Update the release notes on the draft release, and finalize it on GitHub.

  4. Update the Conda feedstock and deploy if it doesn’t happen automatically.

  5. Upload the release archive to Zenodo.