How to Contribute

We welcome contributions at all levels: bugfixes, code improvements, simplifications, new capabilities, improved documentation, new examples/tutorials, etc.

Use a pull request (PR) toward the hippylib2muq:master branch to propose your contribution. If you are planning significant code changes, or have any questions, you should also open an issue before issuing a PR.

hIPPYlib-MUQ is an interface program between hIPPYlib and MUQ; contributions should be related to the interface; for contributing to each program, please refer to their own repositories (hIPPYlib and MUQ).

hIPPYlib-MUQ is maintained by https://github.com/hippylib, the main developer hub for the hIPPYlib project.

All new contributions must be made under the terms of the GPL3 license.

By submitting a pull request, you are affirming the Developer’s Certificate of Origin at the end of this file.

Quick Summary

  • Please create development branches off hippylib2muq:master.

  • Please follow the developer guidelines, in particular with regards to documentation and code styling.

  • Pull requests should be issued toward hippylib2muq:master. Make sure to check the items off the Pull Request Checklist.

  • After approval, hIPPYlib-MUQ developers merge the PR in hippylib2muq:master.

  • If you are also interested in the whole hIPPYlib project, we encourage you to join the hIPPYlib organization (see here); if you are interested in the whole MUQ project, please take a look at MUQ.

  • Don’t hesitate to contact us if you have any questions.

New Feature Development

  • A new feature should be important enough that at least one person, the proposer, is willing to work on it and be its champion.

  • The proposer creates a branch for the new feature (with suffix -dev), off the master branch, or another existing feature branch, for example:

    # Clone assuming you have setup your ssh keys on GitHub:
git clone git@github.com:hippylib/hippylib2muq.git

# Alternatively, clone using the "https" protocol:
git clone https://github.com/hippylib/hippylib2muq.git

# Create a new feature branch starting from "master":
git checkout master
git pull
git checkout -b feature-dev

# Work on "feature-dev", add local commits
# ...

# (One time only) push the branch to github and setup your local
# branch to track the github branch (for "git pull"):
git push -u origin feature-dev

  • We prefer that you create the new feature branch as a fork. To allow hIPPYlib-MUQ developers to edit the PR, please enable upstream edits.

  • The typical feature branch name is new-feature-dev, e.g. optimal_exp_design-dev. While not frequent in hippylib2muq, other suffixes are possible, e.g. -fix, -doc, etc.

Developer Guidelines

  • Keep the code lean and as simple as possible

    • Well-designed simple code is frequently more general and powerful.

    • Lean code base is easier to understand by new collaborators.

    • New features should be added only if they are necessary or generally useful.

    • Code must be compatible with Python 3.

    • When adding new features add an example in the example or application folder and/or a new notebook in the tutorial folder.

    • The preferred way to export solutions for visualization in paraview is using dl.XDMFFile

    • The preferred way to save samples data is using h5py.

  • Keep the code general and reasonably efficient

    • Main goal is fast prototyping for research.

    • When in doubt, generality wins over efficiency.

    • Respect the needs of different users (current and/or future).

  • Keep things separate and logically organized

    • General usage features go in hippylib2muq (implemented in as much generality as possible), non-general features go into external apps/projects.

    • Inside hippylib2muq, compartmentalize between interface, mcmc, utility, etc.

    • Contributions that are project-specific or have external dependencies are allowed (if they are of broader interest), but should be #ifdef-ed and not change the code by default.

  • Code specifics

    • All significant new classes, methods and functions have sphinx-style documentation in source comments.

    • Code styling should resemble existing code.

    • When manually resolving conflicts during a merge, make sure to mention the conflicted files in the commit message.

Pull Requests

  • When your branch is ready for other developers to review / comment on the code, create a pull request towards hippylib2muq:master.

  • Pull request typically have titles like:

    Description [new-feature-dev]

    for example:

    Bayesian Optimal Design of Experiments [oed-dev]

    Note the branch name suffix (in square brackets).

  • Titles may contain a prefix in square brackets to emphasize the type of PR. Common choices are: [DON'T MERGE], [WIP] and [DISCUSS], for example:

    [DISCUSS] Bayesian Optimal Design of Experiments [oed-dev]

  • Add a description, appropriate labels and assign yourself to the PR. The hIPPYlib team will add reviewers as appropriate.

  • List outstanding TODO items in the description.

Pull Request Checklist

Before a PR can be merged, it should satisfy the following:

  • [ ] Update CHANGELOG:

    • [ ] Is this a new feature users need to be aware of? New or updated application or tutorial?

    • [ ] Does it make sense to create a new section in the CHANGELOG to group with other related features?

  • [ ] New examples/applications/tutorials:

    • [ ] All new examples/applications/tutorials run as expected.

  • [ ] New capability:

    • [ ] All significant new classes, methods and functions have sphinx-style documentation in source comments.

    • [ ] Add new examples/applications/tutorials to highlight the new capability.

    • [ ] For new classes, functions, or modules, edit the corresponding .rst file in the doc folder.

    • [ ] If this is a major new feature, consider mentioning in the short summary inside README (rare).

    • [ ] If this is a C++ extension, the package_data dictionary in setup.py should include new files.

Contact Information

  • Contact the hIPPYlib-MUQ team by posting to the GitHub issue tracker. Please perform a search to make sure your question has not been answered already.

Developer’s Certificate of Origin 1.1

By making a contribution to this project, I certify that:

  1. The contribution was created in whole or in part by me and I have the right to submit it under the open source license indicated in the file; or

  2. The contribution is based upon previous work that, to the best of my knowledge, is covered under an appropriate open source license and I have the right under that license to submit that work with modifications, whether created in whole or in part by me, under the same open source license (unless I am permitted to submit under a different license), as indicated in the file; or

  3. The contribution was provided directly to me by some other person who certified (a), (b) or (c) and I have not modified it.

  4. I understand and agree that this project and the contribution are public and that a record of the contribution (including all personal information I submit with it, including my sign-off) is maintained indefinitely and may be redistributed consistent with this project or the open source license(s) involved.

Acknowledgement: This file is made based on CONTRIBUTING.md of hIPPYlib which used MFEM team contributing guidelines file as template.