How to Contribute to McFACTS

This guide will describe the steps and requirements to contribute your awesome additions to McFACTS.

Stay in Touch

First, opt-in to everything McFACTS by using this Google Form to join our mailing list.

Report Bugs or Feature Requests

Use our GitHub Issue Tracker to report any bugs you encounter or think of any cool features you think would benefit McFACTS.

Contributing Code

We’re happy to consider pull requests to improve our documentation and code base.

Documentation

Take a look around. You can find documentation for our code and modules at our Read the Docs.

Input and outputs are documented in IOdocumentation.txt.

Want to build or browse the docs locally? Run the following:

# Switch to the mcfacts-dev environment and install required packages to build the docs
$ conda activate mcfacts-dev
$ conda install sphinx sphinx_rtd_theme sphinx-autoapi sphinx-automodapi

# Switch to the docs directory
$ cd docs

# Clean up any previous generated docs
$ make clean

# Generate the html version of the docs in ./docs/build/html
$ make html

Note

If you create a new documentation file, it must be added to the list in docs/source/index.rst.

McFACTS Code

Follow the process for installing the code in our README.

See the Style Guide for writing code that conforms with our documentation generator.

Commit Messages

For full details see our Commit Guide.

Here is a quick reference for creating semantic commit messages that enable us to easily:

  1. automatically generate our changelog

  2. review the code’s history

All commits should follow this general format:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

<description>: is present tense and gramatically structured to complete the sentence, “If applied, this commit will _____.”

Generating Pull Requests

Pull requests should comply with these requirements:

  1. Direct pull requests at the mcfacts/main-dev branch.

  2. Include all information outlined in the Pull Request Template (automatically populates the description field when initiating a pull request).

  3. Categorize your pull request using one (or more!) option from this list of labels.

Extending McFACTS with other languages

Python can be slow…

   ____      ___
 /_*_*_*\  |  o |
|_*_*_*_*|/ ___\|
|_________/
|_|_| |_|_|

You may know ways to speed up McFACTS by writing interfaces to compiled languages to handle computationally intensive tasks. This sounds awesome! But, please ask the dev team first so you don’t waste your time on something we may not implement.

To ensure McFACTS remains useable, stable, and maintainable for future users and our core dev team, we require the following conditions be met.

  1. Any code written in a language which extends Python (C, Fortran, Rust, etc…) must have a working unit test which checks for accuracy.

  2. As a result, there must be a pure Python version of the function that exists somewhere to do the same math, that we can check our results against.

  3. The pure Python version of such a function should be maintained so that when new physics is brought into the extension, not only the extension is modified, but the Python used to test against the extension as well.

  4. Any pull request introducing or modifying an extension to Python in another language must pass the test-build test.

    make test-build

  5. Any pull request introducing or modifying an extension to Python in another language must be reviewed by somebody who understands the language.

Additionally, several filetypes (E.g. .dat) are excluded in the .gitignore file, and therefore may be missed with a git status or git add --all command. They scan still be committed to the repository if they are added manually with

git add -f [PATH/TO/FILE.dat]

Data Files

When adding a data file to the source of McFACTS, you must take these steps:

  1. Add the data file to McFACTS requires putting it in the relevant src/mcfacts subdirectory.

  2. Add the data file to MANIFEST.in.

  3. Add the data file to setup.py.

  4. Test that McFACTS runs and the file is accessible by running make test-build

Keep in mind that data files distributed alongside McFACTS should be less than a Megabyte. GitHub and Pypi offer free services. Large data files slow down these services and create bulk which is hard to reduce in the history of a repository.