diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index f63c7e90b..e01a574bc 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -21,6 +21,7 @@ - [ ] All new and existing tests passed. - [ ] CI tests pass - [ ] Local tests pass (including Serpent2 integration tests) +- [ ] I have recorded my changes in the changelog for the upcoming release ## Associated Issues and PRs diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml index c091583cc..31b715782 100644 --- a/.github/workflows/deploy-docs.yml +++ b/.github/workflows/deploy-docs.yml @@ -5,8 +5,6 @@ on: release: type: [published] push: - branches: - - master paths: - 'doc/**' - 'saltproc/**' diff --git a/.github/workflows/next-release-minor.yml b/.github/workflows/next-release-minor.yml new file mode 100644 index 000000000..df6b82158 --- /dev/null +++ b/.github/workflows/next-release-minor.yml @@ -0,0 +1,79 @@ +# Preamble +name: Create next minor release + +on: + release: + type: [published] + # enable worflow to be run manually + workflow_dispatch: + +jobs: + next-release-minor: + runs-on: ubuntu-latest + defaults: + run: + shell: bash -l {0} + + steps: + - uses: actions/checkout@v2 + with: + token: ${{ secrets.GITHUB_TOKEN }} + + - name: Get most recent release version + run: | + echo "RELEASE_VERSION=$(gh api repos/${{ github.repository }}/tags --jq '.[0] | .name')" >> $GITHUB_ENV + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + + - name: Increment minor version + run: | + IFS='.' read -ra arr <<< ${{ env.RELEASE_VERSION }} + MINOR_VERSION=$((${arr[1]}+1)) + arr[1]=$MINOR_VERSION + NEW_RELEASE_VERSION="${arr[0]}.${arr[1]}.${arr[2]}" + echo "NEW_RELEASE_VERSION="$NEW_RELEASE_VERSION >> $GITHUB_ENV + + - name: Create a new release + run: | + gh api repos/${{ github.repository }}/releases \ + -H "Authorize: token ${{ secrets.GITHUB_TOKEN }}" \ + -H "Accept: application/vnd.github.v3+json" \ + -X POST \ + -F name=${{ env.NEW_RELEASE_VERSION }} \ + -F tag_name=${{ env.NEW_RELEASE_VERSION }} \ + -F draft=true + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + + + - name: Create a new milestone. + run: | + gh api repos/${{ github.repository }}/milestones \ + -H "Authorize: token ${{ secrets.GITHUB_TOKEN }}" \ + -H "Accept: application/vnd.github.v3+json" \ + -X POST \ + -F title=${{ env.NEW_RELEASE_VERSION }} + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + + - name: Create new release notes + run: | + echo "Configure git" + git config --local user.email "github-actions[bot]@users.noreply.github.com" + git config --local user.name "github-actions[bot]" + echo "Make edits to docfiles" + cp doc/releasenotes/template.rst doc/releasenotes/${{ env.NEW_RELEASE_VERSION }}.rst + sed -i "s/vx.x.x/${{ env.NEW_RELEASE_VERSION }}/g" doc/releasenotes/${{ env.NEW_RELEASE_VERSION }}.rst + sed -i "s/${{ env.RELEASE_VERSION }}/${{ env.NEW_RELEASE_VERSION }}\n ${{ env.RELEASE_VERSION }}/g" doc/releasenotes/index.rst + echo "Make edits to version.py" + sed -i "s/_version_micro = *'*[0-9]*'/_version_micro = ''/g" saltproc/version.py + sed -i "s/_version_minor = *'*[0-9]*'/_version_minor = ${{ env.MINOR_VERSION }}/g" saltproc/version.py + sed -i "s/^# _version_extra = 'dev'/_version_extra = 'dev'/g" saltproc/version.py + sed -i "s/^_version_extra = ''# _version_extra = ''/g" saltproc/version.py + echo "Add, commit, and push changes" + git add doc/releasenotes/${{ env.NEW_RELEASE_VERSION }}.rst + git add doc/releasenotes/index.rst + git commit -am "created ${{ env.NEW_RELEASE_VERSION }} release notes" + git add saltproc/version.py + git commit -am "updated version to ${{ env.NEW_RELEASE_VERSION }}-dev" + git push diff --git a/.github/workflows/populate-releasenotes.yml b/.github/workflows/populate-releasenotes.yml new file mode 100644 index 000000000..1fe2991e2 --- /dev/null +++ b/.github/workflows/populate-releasenotes.yml @@ -0,0 +1,54 @@ +# Preamble +name: Populate SaltProc release notes + +on: + push: + paths: + - 'doc/releasenotes/v**.rst' + # enable worflow to be run manually + workflow_dispatch: + +jobs: + populate-releasenotes: + runs-on: ubuntu-latest + defaults: + run: + shell: bash -l {0} + + steps: + - uses: actions/checkout@v2 + + - name: Set up Python 3.9 + uses: actions/setup-python@v2 + with: + python-version: 3.9 + - name: Add conda to system path + run: | + # $CONDA is an environment variable pointing to the root of the miniconda directory + echo $CONDA/bin >> $GITHUB_PATH + + - name: install pandoc + run: | + conda install -c conda-forge pandoc + pip install --upgrade pandoc + + - name: Get most recent draft release version + run: | + echo "RELEASE_VERSION=$(gh api repos/${{ github.repository }}/releases --jq '.[0] | .name')" >> $GITHUB_ENV + echo "RELEASE_ID=$(gh api repos/${{ github.repository }}/releases --jq '.[0] | .id')" >> $GITHUB_ENV + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + + - name: Convert .rst to .md + run: pandoc -s -o RELEASENOTES.md -f rst -t gfm doc/releasenotes/${{ env.RELEASE_VERSION }}.rst --columns 1000 + + + - name: Populate the release description with RELEASENOTES.md + run: | + gh api repos/${{ github.repository }}/releases/${{ env.RELEASE_ID }} \ + -H "Authorize: token ${{ secrets.GITHUB_TOKEN }}" \ + -H "Accept: application/vnd.github.v3+json" \ + -X PATCH \ + -F body="$(cat RELEASENOTES.md)" + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0b085d42c..d01eb7b59 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,3 +1,5 @@ +# Contributing + ### Thanks for Your Help! Contributing is so kind of you. In SaltProc, all contributions, bug reports, @@ -87,6 +89,9 @@ Please use the provided pull request template. In particular: - **Make sure the test suite passes** on your computer. To do so, run `py.test saltproc` in the repository directory. At a minumum, you must run the tests requring serpent locally as they are not tested by our CI + - Describe your feature/change/fix in the release notes (located in `doc/releasenotes`) + for the currently in-development release version. Use the descriptive comments and + examples as reference. - Please reference relevant Github issues in your commit message using `GH1234` or `#1234`. - Changes should be PEP8 compatible [PEP8](http://www.python.org/dev/peps/pep-0008/). diff --git a/doc/devguide/contributing.rst b/doc/devguide/contributing.rst new file mode 100644 index 000000000..5674d7819 --- /dev/null +++ b/doc/devguide/contributing.rst @@ -0,0 +1,110 @@ +Contributing +============ + +Thanks for Your Help! +--------------------- + +Contributing is so kind of you. In SaltProc, all contributions, bug reports, bug fixes, documentation improvements, enhancements and ideas are welcome. + +The `GitHub "issues" tab `__ contains some issues labeled "Difficulty:1-Beginner". Those are open issues that would be a good quick way to get started. Browse them to see if you want to get started on one. + +Bug Reports +~~~~~~~~~~~ + +Is something in the code not working? Consider making a bug report! In particular: + +- Please include a short but detailed, self-contained Python snippet or explanation for reproducing the problem. + +- Explain what the expected behavior was, and what you saw instead. + +Feature Requests +~~~~~~~~~~~~~~~~ + +If you have an idea that could add to or improve SaltProc, and know how to implement it, consider making a Feature Request! + +Discussion +~~~~~~~~~~ + +If you + +- have feedback or a feature idea that aren't concrete/focused enough to go into a Feature Request Issue +- want to show off cool work you have done with the software + +please use our `Discussions page `__! + +Instructions for setting up a development environment +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The SaltProc is compatible with Python >=3.5. Anaconda is the recommended distribution to use to work on SAltProc; we will assume that if you want to use another distribution or your own set up, you can translate the instructions. + +You can download Anaconda at https://www.continuum.io/Downloads for the full install. You can also download a mini Anaconda install for a bare-bones install -- this is good for a build server or if you don't have much space. The mini Anaconda installs are available at https://conda.io/miniconda.html. + +Once your Anaconda package is installed and available, create a Python 3.6 environment in Anaconda -- + +:: + + conda create -q -n saltproc-test-environment python=3.6 scipy numpy matplotlib pytest pytables flake8 + +Each of these commands will take a bit of time -- give it a few minutes to download and install the packages and their dependences. Once complete, switch to each and install additional packages needed to run and test. + +Activate the 3.6 environment and install pyne, networkx and pydotplus + +:: + + source activate saltproc-test-environment + conda install -c conda-forge pyne networkx pydotplus + +Setup Serpent Monte Carlo code environment +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The SaltProc assumes that Serpent directory is added in ``$PATH`` as follows: + +:: + + export PATH="/path/to/serpent/executable:$PATH" + +Run the tests +^^^^^^^^^^^^^ + +Tests are automatically detected and run with pytest. Start in the root directory where you have cloned the saltproc repository and run in development environment + +:: + + source active saltproc-test-environment + py.test saltproc + +Run style tests with flake8 +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Adherance to style checks in flake8 is encouraged though not strictly enforced. While you should not feel compelled to fix existing failures, please do not add additional flake8 issues. + +:: + + run flake8 from the root of the pyrk working directory to get all flake8 issues + run flake8 and provide a filename to just run checks on that file + +Pull Requests +^^^^^^^^^^^^^ + +Please use the provided pull request template. In particular: + +- **Make sure the test suite passes** on your computer. To do so, run ``py.test saltproc`` in the repository directory. At a minumum, you must run the tests requring serpent locally as they are not tested by our CI +- Describe your feature/change/fix in the release notes (located in ``doc/releasenotes``) for the currently in-development release version. Use the descriptive comments and examples as reference. +- Please reference relevant Github issues in your commit message using ``GH1234`` or ``#1234``. +- Changes should be PEP8 compatible `PEP8 `__. +- Keep style fixes to a separate commit to make your PR more readable. +- Docstrings ideally follow the `sphinx autodoc `__ +- Write tests. +- When writing tests, please make sure they are in a ``tests`` directory. +- When you start working on a PR, start by creating a new branch pointing at the latest commit on github master. +- The SaltProc copyright policy is detailed in the `LICENSE `__. + +More developer docs +~~~~~~~~~~~~~~~~~~~ + +- We are working on it. + +Meta +~~~~ + +Note, this contributing file was adapted from the one at the `pandas `__ repo. Thanks pandas! diff --git a/doc/devguide/index.rst b/doc/devguide/index.rst new file mode 100644 index 000000000..e3141e898 --- /dev/null +++ b/doc/devguide/index.rst @@ -0,0 +1,23 @@ +.. _devguide: + +================= +Developer's Guide +================= +.. _git workflow: https://git-scm.com/book/en/v2/Getting-Started-About-Version-Control + +Welcome to the SaltProc developer's guide. Here you'll find +all the information you need to be an efficient and effective contributor +to SaltProc. + +.. note:: The SaltProc developer's guide is a work in progress. + Information contained within may change, so make sure to check the + release notes for updates! + +If you're new to software development, please familiarize yourself with the +`git workflow`_ before getting started. We'll be using terminoigy +in this developer's guide that relies on understanding it. + +.. toctree:: + :maxdepth: 1 + + contributing diff --git a/doc/index.rst b/doc/index.rst index dd5ad5830..a6e961d8e 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -32,6 +32,8 @@ Documentation installation examples src/index + releasenotes/index + devguide/index How to cite Indices and tables @@ -69,6 +71,12 @@ Acknowledgment SaltProc uses `Shablona`_ template which is universal solution for small scientific python projects developed at University of Washington `eScience Insititute`_. +`OpenMC's docpages`_ heavily inspired the strucutre and format for SaltProc's docpages. + +We make our versioned documentation using `sphinx-multiversion`_. + +.. _sphinx-multiversion: https://github.com/Holzhaus/sphinx-multiversion +.. _OpenMC's docpages: https://docs.openmc.org/en/stable/index.html .. _Shablona: https://github.com/uwescience/shablona .. _eScience Insititute: https://escience.washington.edu diff --git a/doc/releasenotes/index.rst b/doc/releasenotes/index.rst new file mode 100644 index 000000000..6a08ee65a --- /dev/null +++ b/doc/releasenotes/index.rst @@ -0,0 +1,11 @@ +.. _releasenotes: + +============= +Release Notes +============= + +.. toctree:: + :maxdepth: 1 + + v0.4.0 + v0.3.0 diff --git a/doc/releasenotes/template.rst b/doc/releasenotes/template.rst new file mode 100644 index 000000000..5fbd7b05f --- /dev/null +++ b/doc/releasenotes/template.rst @@ -0,0 +1,102 @@ +======================== +Release notes for vx.x.x +======================== + +.. + When documenting a bug fix or feature, please do so in the following format + +.. + - `Fixed typo in depcode.py `_ by @pr_author_username + +.. + Links to packages/issues/bug fixes/contributors/reviewers + + + + +------- +Summary +------- + +.. + Describe generally the features of this release + + + + +------------------ +Dependency Changes +------------------ + +.. + Describe any new/removed/modified package dependencies + + + + +------------ +New Features +------------ + +.. + Describe any new features to the code. + + + + +--------- +Bug Fixes +--------- + +.. + Describe any bug fixes. + + + + +-------------- +Script Changes +-------------- + +.. + Describe any script additions/modifications/removals + + + + +------------------ +Python API Changes +------------------ + +.. + Describe any changes to the API + + + + +------------ +Contributors +------------ +.. + List of people who contributed features and fixes to this release + +The following people contributed code to this release of SaltProc: + +.. + `@gh_username `_ + + + + +--------- +Reviewers +--------- +.. + List of people who reviewed PRs for this release + +The following people reviewed code for this release of SaltProc: + +.. + `@gh_username `_ + + diff --git a/doc/releasenotes/v0.3.0.rst b/doc/releasenotes/v0.3.0.rst new file mode 100644 index 000000000..4e64855c1 --- /dev/null +++ b/doc/releasenotes/v0.3.0.rst @@ -0,0 +1,56 @@ +======================== +Release notes for v0.3.0 +======================== + +This release of SaltProc adds several new features, including a refactor of ``depcode``, updated documentation, and installation guides. Make sure you apply `this bug fix `__ in your Serpent2 code if you haven't already. + +New Features +============ + +- Complete refactor of the code into object-oriented python. +- Adds a Sparging system package -- contained in the ``sparger`` and ``separator`` modules -- that calculates removal efficiencies for various target isotopes (i.e. Xe, Kr, H). +- Adds a script for creating a Serpent2 compatible cross section library +- Refactors the ``depcode`` module by making ``Depcode`` a purley abstract class; add the ``DepcodeSerpent`` class which is an instance of ``Depcode`` + +Bug Fixes +========= + +- `Remove cruft in master `__ +- `Update Geometry file syntax to Serpent 2 standards `__ +- `Update issue and PR templates `__ +- `Fix incorrect variable call in ``app.read_dot`` `__ +- `Fix typos in documentation `__ + +Commit list +=========== + +- Isotope find by @jbae11 in https://github.com/arfc/saltproc/pull/23 +- Saltproc capability addition and UI improvement by @jbae11 in https://github.com/arfc/saltproc/pull/29 +- Completely refactored and changed after latest Teddy's release (0.2.0) by @andrewryh in https://github.com/arfc/saltproc/pull/37 +- Update README.md only to address #41 by @andrewryh in https://github.com/arfc/saltproc/pull/45 +- Bringing SaltProc repository up to date by @andrewryh in https://github.com/arfc/saltproc/pull/47 +- Scripts and input files for sensitivity analysis of msbr design by @mehmeturkmen in https://github.com/arfc/saltproc/pull/48 +- Saltproc multiple run flexibility by @mehmeturkmen in https://github.com/arfc/saltproc/pull/49 +- Adding sparging system to saltproc by @mehmeturkmen in https://github.com/arfc/saltproc/pull/50 +- The updated "overview.rst" file for the latest change in Saltproc by @mehmeturkmen in https://github.com/arfc/saltproc/pull/53 +- Improved separator using Jiaqi's new correlation by @mehmeturkmen in https://github.com/arfc/saltproc/pull/54 +- Create ci.yml by @yardasol in https://github.com/arfc/saltproc/pull/61 +- Call ``name`` instead of ``__string__`` to assign ``mat_name`` by @yardasol in https://github.com/arfc/saltproc/pull/63 +- Add issue + PR templates by @yardasol in https://github.com/arfc/saltproc/pull/66 +- Update README and Contributing by @yardasol in https://github.com/arfc/saltproc/pull/71 +- Refactor depcode by @yardasol in https://github.com/arfc/saltproc/pull/64 +- 2nd attempt: Update issue template formatting. by @yardasol in https://github.com/arfc/saltproc/pull/75 +- Update example and integration test input files to serpent 2 syntax by @yardasol in https://github.com/arfc/saltproc/pull/89 +- Remove cruft files from ``master`` branch by @yardasol in https://github.com/arfc/saltproc/pull/86 +- ``doc`` additions, docstring typo fixes, cross section processing scripts by @yardasol in https://github.com/arfc/saltproc/pull/90 +- Patch #90 (pep8 issues, docstring consistency) by @yardasol in https://github.com/arfc/saltproc/pull/92 + +Contributors +============ + +- @yardasol +- @mehmeturkmen +- @andrewryh +- @jbae11 + +**Full Changelog**: https://github.com/arfc/saltproc/compare/v0.2.0...v0.3.0 diff --git a/doc/releasenotes/v0.4.0.rst b/doc/releasenotes/v0.4.0.rst new file mode 100644 index 000000000..fdc05d1e6 --- /dev/null +++ b/doc/releasenotes/v0.4.0.rst @@ -0,0 +1,178 @@ +======================== +Release notes for v0.4.0 +======================== + +.. + When documenting a bug fix or feature, please do so in the following format + +.. + - `Fixed typo in depcode.py `_ by @pr_author_username + +.. + Links to packages/issues/bug fixes/contributors/reviewers + +.. _jsonschema: https://github.com/Julian/jsonschema +.. _@yardasol: https://github.com/yardasol +.. _@abachma2: https://github.com/abachma2 +.. _@LukeSeifert: https://github.com/LukeSeifert +.. _@munkm: https://github.com/munkm + + +------- +Summary +------- + +.. + Describe generally the features of this release + +This version of SaltProc refactors the code in preparation for supporting OpenMC. + + +------------------ +Dependency Changes +------------------ + +.. + Describe any new/removed/modified package dependencies + +- Saltproc now requires the following packages + + - (new) → `jsonschema`_ + + +------------ +New Features +------------ + +.. + Describe any new features to the code. + +- `Refactor app.py and simulation.py to prepare for OpenMC support `_ by `@yardasol`_ +- `New input file format that is checked against a verifiable JSON Schema `_ by `@yardasol`_ +- `Release notes in the online docs `_ by `@yardasol`_ + + +--------- +Bug Fixes +--------- + +.. + Describe any bug fixes. + +- `Fix typos in process_j312.bash `_ + + +-------------- +Script Changes +-------------- + +.. + Describe any script additions/modifications/removals + +- The following scripts hav been renamed: + + - ``process_j312.sh`` → ``process_j312.bash`` + + +------------------ +Python API Changes +------------------ + +- New tests for previously untested functions in ``simulation.py``: + + - ``test_check_switch_geo_trigger`` + - ``test_store_after_repr`` + - ``test_store_mat_data`` + - ``test_store_run_init_info`` + - ``test_store_run_step_info`` + +- The following class methods have been added/(re)moved: + + - ``App.check_restart()`` → ``Simulation.check_restart()`` + - ``Simulation.switch_to_next_geometry`` → ``DepcodeSerpent.switch_to_next_geometry`` + - ``Simulation.runsim_no_reproc`` → ``test/integration_tests/test_no_reproc_run.py::runsim_no_reproc`` + - ``Simulation.store_run_step_info`` + - ``Simulation.store_run_init_info`` + - (new) → ``Depcode.switch_to_next_geometry`` + - (new) → ``Depcode.read_depcode_info`` + - (new) → ``Depcode.read_repcode_step_param`` + +- Updated input file structure: + + - ``App.depcode_inp`` dictionary + + - (new) → ``App.depcode_inp['codename']`` + - ``App.exec_path`` + - ``App.template_file`` + - ``App.neutron_pop`` → ``App.depcode_inp['npop']`` + - ``App.active_cycles`` + - ``App.inactive_cycles`` + - ``App.geo_file`` → ``App.depcode_inp['geo_file_paths']`` + + - ``App.simulation_inp`` dictionary: + + - (new) → ``App.simulation['sim_name']`` + - ``App.db_file`` → ``App.simulation['db_name']`` + - ``App.restart_flag`` + - ``App.adjust_geo`` + + - ``App.reactor_inp`` dictionary + + - (new) → ``App.reactor_inp['volume']`` + - (new) → ``App.reactor_inp['mass_flowrate']`` + - ``App.power_levels`` + - ``App.depl_hist`` + +- The following class attributes have been added/(re)moved: + + - ``Depcode`` class: + + - ``template_path`` → ``template_inputfile_path`` + - ``input_path`` → ``iter_inputfile`` + - ``geo_file`` → ``geo_files`` + + - ``Simulation`` class: + + - ``h5_file`` → ``db_path`` + - (new) → ``restart_flag`` + - (new) → ``adjust_geo`` + - ``iter_matfile`` → (removed) + +- The signatures for the following class methods have changed to better make use of object data encapsulation: + + - ``Depcode.read_dep_comp`` + - ``Depcode.write_depcode_input`` + - ``Depcode.write_mat_file`` + - ``DepcodeSerpent.read_depcode_template`` + + +------------ +Contributors +------------ + +.. + List of people who contributed features and fixes to this release + +The following people contributed code to this release of SaltProc: + +.. + `@gh_username `_ + +- `@yardasol`_ + + +--------- +Reviewers +--------- + +.. + List of people who reviewed PRs for this release + +The following people reviewed code for this release of SaltProc: + +.. + `@gh_username `_ + +- `@abachma2`_ +- `@LukeSeifert`_ +- `@munkm`_ diff --git a/saltproc/version.py b/saltproc/version.py index ed8f3957a..1c1af713f 100644 --- a/saltproc/version.py +++ b/saltproc/version.py @@ -4,7 +4,7 @@ # Format expected by setup.py and doc/source/conf.py: string of form "X.Y.Z" _version_major = 0 _version_minor = 4 -_version_micro = '0' # use '' for first of series, number for 1 and above +_version_micro = '' # use '' for first of series, number for 1 and above _version_extra = 'dev' # _version_extra = '0' # Uncomment this for full releases