Merge pull request #440 from idaholab/py_open_sci

Implementing feedback from PyOpenSci peer reviews.

CODE_OF_CONDUCT.md

@@ -0,0 +1,128 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[email protected].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior,  harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.0, available at
+https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct
+enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at
+https://www.contributor-covenant.org/translations.

CONTRIBUTING.md

@@ -7,8 +7,7 @@ up to speed.
 ## Code of Conduct
 
 Participants in the MontePy project are expected to follow and uphold the [Code
-of Conduct](CODE_OF_CONDUCT.md). Please report any unacceptable behavior to
-[email protected].
+of Conduct](CODE_OF_CONDUCT.md). Please report any unacceptable behavior to [email protected].
 
 ## Resources
 

README.md

@@ -3,14 +3,22 @@
 <img src="https://raw.githubusercontent.com/idaholab/MontePy/develop/graphics/monty.svg" width="180" alt="MontePY: a cute snek on a red over white circle"/>
 
 [![license](https://img.shields.io/github/license/idaholab/MontePy.svg)](https://github.com/idaholab/MontePy/blob/develop/LICENSE)
+[![JOSS article status](https://joss.theoj.org/papers/e5b5dc8cea19605a1507dd4d420d5199/status.svg)](https://joss.theoj.org/papers/e5b5dc8cea19605a1507dd4d420d5199)
 [![Coverage Status](https://coveralls.io/repos/github/idaholab/MontePy/badge.svg?branch=develop)](https://coveralls.io/github/idaholab/MontePy?branch=develop)
 [![PyPI version](https://badge.fury.io/py/montepy.svg)](https://badge.fury.io/py/montepy)
 
 MontePy is a python library to read, edit, and write MCNP input files. 
 
 ## Installing
 
-See the [Installing section in the user guide](https://www.montepy.org/starting.html#installing).
+Simply run:
+
+```
+pip install montepy
+```
+
+For more complicated setups
+see the [Installing section in the user guide](https://www.montepy.org/starting.html#installing).
 
 
 ## User Documentation

doc/source/changelog.rst

@@ -6,7 +6,7 @@ MontePy Changelog
 
 **Features Added**
 
-* ``overwrite`` argument added to `MCNP_Problem.write_to_file` to ensure files are only overwritten if the user really wants to do so (:pull:`443`).
+* ``overwrite`` argument added to ``MCNP_Problem.write_to_file`` to ensure files are only overwritten if the user really wants to do so (:pull:`443`).
 
 **Bug fixes**
 

doc/source/index.rst

@@ -24,9 +24,9 @@ MontePy can be installed with pip:
    :maxdepth: 2
    :caption: Table of Contents:
 
-   api/modules
    users
    dev_tree
+   api/modules
 
 See Also
 ========

doc/source/starting.rst

@@ -7,8 +7,8 @@ The library provides a semantic interface for working with input files, or our p
 It understands that the second entry on a cell card is the material number,
 and will link the cell with its material object.
 
-.. warning::
-    MontePy is built primarily to support MCNP 6.2. Some success maybe achieved with MCNP 6.1, and 5.1.60, 
+.. note::
+    MontePy is built primarily to support MCNP 6.2, and MCNP 6.3. Some success maybe achieved with MCNP 6.1, and 5.1.60, 
     but there may be issues due to new features in MCNP 6.2, not being backwards compatible.
     Use earlier versions of MCNP with MontePy at your own risk.
 
@@ -33,32 +33,39 @@ System Wide (for the current user)
    In this case the easiest way to deal with this is to open a teminal inside of `jupyter lab` and to install the package there.
 
 
-#. Install it from `PyPI <https://pypi.org>`_ by running ``pip install --user montepy``.
+#. Install it from `PyPI <https://pypi.org/project/montepy>`_ by running ``pip install montepy``. 
+   You may need to run ``pip install --user montepy`` if you are not allowed to install the package.
 
 Install specific version for a project
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 The best way maybe to setup a project-specific `conda <https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html>`_, 
 `Mamba <https://mamba.readthedocs.io/en/latest/user_guide/concepts.html>`_, 
 or a `venv <https://docs.python.org/3/library/venv.html>`_ environment.
 The steps for installing inside one of those environments are the same as the previous steps.
+You can specify a specific version from `PyPI`_ be installed using:
+
+``pip install montepy==<version>``
 
-Another option is to clone the repository and to use symbolic-links. In this scenario we'll assume that your local
-repository is located at ``~/dev/montepy``, and your project is located at ``~/foo/bar``. 
 
-#. Move to the repository parent folder: ``cd ~/dev``
-#. Clone this repository: ``git clone https://github.com/idaholab/montepy.git`` 
-#. Enter the repository: ``cd montepy``
-#. Checkout the specific version you want. These are tagged with git tags
+Best Practices
+--------------
+
+Before we begin, here are some guidelines to keep in mind while scripting your work with MCNP models.
 
-    #. You can list all tags with ``git tag``
+#. *Always* version control your input files (not output files) with `git <https://git-scm.com/>`_ or another tool.
+   If you are working with very large input models, like `the ITER model <https://doi.org/10.1038/s41560-020-00753-x>`_ you may want to consider `git-lfs <https://git-lfs.com/>`_.
 
-    #. You can then checkout that tag: ``git checkout <tag>``
+   #. Do learn some `git best practices <https://sethrobertson.github.io/GitBestPractices/>`_. "Update" is not a useful commit message.
 
-#. Install the dependent requirements: ``pip install -r requirements/common.txt``
-#. Move to your project folder: ``cd ~/foo/bar``
-#. Create a symbolic link in the project folder to the repository: ``ln -s ~/dev/montepy/montepy montepy``
+#. *Always* have backups. Don't be that person that loses the last months of work when your laptop falls in a pond. 
+   Make sure there's a cloud backup (could be OneDrive, GitHub, etc.). 
+   Just make sure you comply with any applicable corporate policies. 
 
-Now when you run a python script in that folder (*and only in that folder*) ``import montepy`` will use the specific version you want. 
+#. Don't overwrite your original file. Generally your script should open file "A", modify it, and then save it to file "B".
+   This way, when there is a bug in your script, you can debug it and rerun it because "A" still exists.
+   Later, if you need to make changes you can modify your script and rerun it. 
+   This is especially true if your script ever becomes qualified under an `ASME NQA-1 <https://en.wikipedia.org/wiki/ASME_NQA>`_ compliant Software Quality Assurance program,
+   which requires that the inputs and outputs of software be preserved.
 
 Reading a File
 --------------
@@ -84,9 +91,12 @@ By default if the file exists, it will not be overwritten and an error will be r
 This can be changed by ``overwrite=True``.
 
 .. warning::
-   Be careful with overwriting the original file (and ``overwrite=True`` in general) when writing a modified file out.
-   This will wipe out the original version, and if you have no version control,
-   may lead to losing information.
+   Overwriting the original file (with ``overwrite=True``) when writing a modified file out is discouraged.
+   This is because if your script using MontePy is buggy you have no real way to debug,
+   and recover from the issue if your original file has been been modified.
+   Instead of constantly having to override the same file you can add a timestamp to the output file,
+   or create an always unique file name with the `UUID <https://docs.python.org/3/library/uuid.html>`_ library.
+
 
 If no changes are made to the problem in MontePy the entire file will be just parroted out as it was in the original file.
 However any objects (e.g., two cells) that were changed (i.e., mutated) may have their formatting changed slightly.