Contributing Code

First, thank you for your interests in improving LamAna. At the moment, you can contribute to the LamAna community as an Author or Developer in several ways.

As an Author

to the Models Library

So you have worked on your custom model and you would like to share it with others...

You can sumbit your custom model as an extension to the current models library as a pull request on GitHub. As an extension, other users can access your model with ease. With further review and community acceptance, favorable models will be accepted into the core LamAna models library. Please do the following:

  1. create Python files subclassed from theories.Model
  2. write tests
  3. document your code
  4. cite academic references
  5. include supporting validation or FEA data (preferred)

The LamAna Project welcomes open contributions to the official models library. It is envisioned that a stable source of reliable laminate anaylsis models will be useful to other users, similar to the way R package libraries are maintained.

As a Developer

to LPEPs

If you are not interested in writing code, but would like to propose an idea for enchancing LamAna, you can submit an LPEP for review.

  1. Please draft your proposals in a similar format to existing LPEPs as jupyter notebooks
  2. Submit a pull request on GitHub.

The LPEP submission and content guidelines closely follow PEP 0001.

to Project Code

If you would like to improve the latest development code, please do the following:

  1. git clone the develop branch
  2. use gitflow to make feature branches
  3. since GitHub squashes local commits, add detailed commit history to the feature branch merge commits
  4. write tests for your enhancement
  5. modify the code with insightful docstrings
  6. successfully run tests
  7. write documentation in a jupyter notebook
  8. submit your test, code and documentation as a pull requests on GitHub.

The latter steps pertain to adding or enchancing Feature modules and improving core modules. For starters, you can look to the demonstrations or gallery as motivation for improving LamAna’s functionality, clarity or optimization.

Thanks for your contributions. You are helping to improve the LamAna community!

In [ ]:

# TODO: add gitflow, workflow diagram

Resources

If you are new to developing, here are some resources to get started on this project:

  • git: default version control
  • GitHub: git host opensource projects
  • gitflow-avh: a git extension used to ease development workflow
  • atom: an great, open source text editor [using linter, flake8, minimap, pygments, colorpicker]

The following packages are available in conda or pip:

The following are Sphinx extensions helpful in documenting code:

  • autodoc: auto generate api docs
  • autosummary: make a custom API reference, summary table
  • nbsphinx: auto generate rst files from jupyter notebook files
  • numpydoc: auto format docs using numpy-style docstrings
  • napoleon: numpy and google-style doctrings
  • viewcode: link api references and see implementation of the code directly in source.

The following are useful web-based tools:

  • Travis: test builds on linux/Mac systems and dependency versions
  • readthedocs: automate doc builds (in a travis-like way)
  • TestPyPI: Test code before officially hosting to PyPI
  • PyPI: host Python projects