Skip to content

Latest commit

 

History

History
131 lines (87 loc) · 5.24 KB

CONTRIBUTING.md

File metadata and controls

131 lines (87 loc) · 5.24 KB
Raw

Contributing to Geo2DR

Welcome and thank you for considering contributing to Geo2DR open source project!

Reading and following these guidelines will help us make the contribution process easy and effective for everyone involved. It also communicates that you agree to respect the time of the developers managing and developing these open source projects. In return, we will reciprocate that respect by addressing your issue, assessing changes, and helping you finalize your pull requests.

Quicklinks

Code of Conduct

We take our open source community seriously and hold ourselves and other contributors to high standards of communication. By participating and contributing to this project, you agree to uphold our Code of Conduct.

Getting Started

Contributions are made to this repo via Issues and Pull Requests (PRs). A few general guidelines that cover both:

  • Search for existing Issues and PRs before creating your own.
  • We work hard to makes sure issues are handled in a timely manner but, depending on the impact, it could take a while to investigate the root cause. A friendly ping in the comment thread to the submitter or a contributor can help draw attention if your issue is blocking.

Build and install

To develop geometric2dr, first build and install it from source following the steps

  1. Clone a copy of geometric2dr from source:

    git clone https://github.com/paulmorio/geo2dr
cd geo2dr

  2. If you already cloned geometric2dr from source, update it:

    git pull

  3. If needed, install dependencies in your environment:

    pip install -r dev_requirements.txt

    This will install all the required dependencies for the package, the examples, as well as flake8, isort, pytest-cov, and black.

  4. Install geometric2dr in editable mode:

    pip install -e .

    This mode will symlink the Python files from the current local source tree into the Python install. Hence, if you modify a Python file, you do not need to reinstall geo2dr again and again.

  5. Ensure that you have a working geometric2dr installation by running the entire test suite with

    python -m pytest tests

  6. Install pre-commit hooks:

     pre-commit install

Unit Testing

The Geo2DR testing suite is located under tests/. Run the entire test suite with

python -m pytest tests

Continuous Integration

Geo2DR uses TravisCI (to be updated to Github Actions in the near future). The pre-commit hooks will ensure that committed code follows the minimum code quality standard.

Issues

Issues should be used to report problems with the library, request a new feature, or to discuss potential changes before a PR is created.

If you find an Issue that addresses the problem you're having, please add your own reproduction information to the existing issue rather than creating a new one. Adding a reaction can also help be indicating to our maintainers that a particular problem is affecting more than just the reporter.

Pull Requests

PRs to our libraries are always welcome and can be a quick way to get your fix or improvement slated for the next release. In general, PRs should:

  • Be written in a way that is easy to understand and maintain.
  • Have an attached Issue that describes the problem and the PR name should refer to the Issue.
  • The PR author agrees to the Code of Conduct and the LICENSE
  • Only fix/add the functionality in question OR address wide-spread whitespace/style issues, not both.
  • Add unit or integration tests for fixed or changed functionality.
  • Include documentation in the repo or on our docs site.

For changes that address core functionality or would require breaking changes (e.g. a major release), it's best to open an Issue to discuss your proposal first.

In general, we follow the "fork-and-pull" Git workflow

  1. Fork the repository to your own Github account
  2. Clone the project to your machine
  3. Create a branch locally with a succinct but descriptive name
  4. Commit changes to the branch
  5. Following any formatting and testing guidelines specific to this repo
  6. Push changes to your fork
  7. Open a PR in our repository and follow the PR template so that we can efficiently review the changes.

Building Documentation

To build the documentation:

  1. Build and install geometric2dr from source.

  2. Install Sphinx via pip install sphinx sphinx_rtd_theme.

  3. Generate the documentation via:

    cd docs
make html

The documentation is now available to view by opening docs/build/html/index.html.