Skip to content

Latest commit

 

History

History
130 lines (105 loc) · 5.32 KB

CONTRIBUTING.md

File metadata and controls

130 lines (105 loc) · 5.32 KB
Copyright 2024 National Technology & Engineering Solutions of Sandia,
LLC (NTESS). Under the terms of Contract DE-NA0003525 with NTESS, the
U.S. Government retains certain rights in this software.

Python Tensor Toolbox Contributor Guide

Issues

If you are looking to get started or want to propose a change please start by checking current or filing a new issue.

Working on PYTTB locally

  1. Clone your fork and enter the directory

    git clone [email protected]:<your username>/pyttb.git
cd pyttb
    1. Setup your desired python environment as appropriate

  2. Install dependencies

    Most changes only require dev options

    pip install -e ".[dev]"

    But if you are making larger interface changes or updating tutorials/documentation you can also add the required packages for documentation.

    pip install -e ".[dev,doc]"

  3. Checkout a branch and make your changes

    git checkout -b my-new-feature-branch

  4. Formatters and linting (These are checked in the full test suite as well)

    1. Run autoformatters and linting from root of project (they will change your code) 
      ruff check . --fix
ruff format
      1. Ruff's --fix won't necessarily address everything and may point out issues that need manual attention
      2. We optionally support pre-commit hooks for this
        1. Alternatively, you can run pre-commit run --all-files from the command line if you don't want to install the hooks.
    2. Check typing 
      mypy pyttb/
      1. Not included in our pre-commit hooks because of slow runtime.
    3. Check spelling 
      codespell
      1. This is also included in the optional pre-commit hooks.

  5. Run tests (at desired fidelity)

    1. Just doctests (enabled by default) 
      pytest .
    2. Functional tests 
      pytest tests
    3. With coverage 
      pytest tests --cov=pyttb --cov-report=term-missing

  6. (Optionally) Building documentation and tutorials

    1. From project root
    sphinx-build ./docs/source ./docs/build
    1. Clear notebook outputs if run locally see nbstripout in our pre-commit configuration

Adding tutorials

  1. Follow general setup from above

    1. Checkout a branch to make your changes
    2. Install from source with dev and doc dependencies
    3. Verify you can build the existing docs with sphinx

  2. Create a new Jupyter notebook in ./docs/source/tutorial

    1. Our current convention is to prefix the filename with the type of tutorial and all lower case

  3. Add a reference to your notebook in ./docs/source/tutorials.rst

  4. Rebuild the docs, review locally, and iterate on changes until ready for review

Tutorial References

Generally, inspecting existing documentation or tutorials should provide a reasonable starting point for capabilities, but the following links may be useful if that's not sufficient.

  1. We use sphinx to automatically build our docs and may be useful for .rst issues

  2. We use myst-nb to render our notebooks to documentation

GitHub Workflow

Proposing Changes

If you want to propose a change to Python Tensor Toolbox, follow these steps:

  1. Create an Issue

    • Use the Issues tab of the Python Tensor Toolbox GitHub repository and click on the "New issue" button.

  2. Fork the Repository and Create a New Branch

    • Navigate to the main page of the Python Tensor Toolbox GitHub repository and click on the "Fork" button to create a copy of the repository under your own account.
    • Clone the forked repository to your local machine.
    • In your local repository, create a new branch for your proposed changes.

  3. Update the Code

    • Make the necessary updates in your local environment.
    • After making your changes, stage and commit them with an informative message.

  4. Push your Changes and Create a Pull Request

    • Push your changes to the new branch in your fork of the repository.
    • Navigate to the main page of the Python Tensor Toolbox repository and click on the "New pull request" button.
    • In the "base repository" dropdown, select the original Python Tensor Toolbox repository. In the "base" dropdown, select the branch where you want your changes to be merged.
    • In the "head repository" dropdown, select your forked repository. In the "compare" dropdown, select the branch with your changes.
    • Write a title and description for your pull request.

  5. Review Process

    • After creating a pull request, wait for the Github CI tests to pass.
    • If any test fails, review your code, make necessary changes, and push your code again to the same branch in your forked repository.
    • If there are any comments or requested changes from the Python Tensor Toolbox team, address them and push any additional changes to the same branch.
    • Once your changes are approved, a repository admin will merge your pull request.