Skip to content

Latest commit

 

History

History
193 lines (141 loc) · 8.77 KB

CONTRIBUTING.md

File metadata and controls

193 lines (141 loc) · 8.77 KB

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.

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

(a) 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

(b) 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

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

(d) 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.