Skip to content

Latest commit

 

History

History
147 lines (90 loc) · 4.45 KB

CONTRIBUTING.rst

File metadata and controls

147 lines (90 loc) · 4.45 KB
Raw

Contributor's Guide

Contributions are always welcome and greatly appreciated!

Code contributions

We love pull requests from everyone! Here's a quick guide to improve the code:

  1. Fork the repository and clone the fork.
  2. Create a virtual environment using your tool of choice (e.g. virtualenv, conda, etc).
  3. Install development dependencies:
pip install -r requirements-dev.txt
  1. From the compas_fab directory, run the docker containers:
docker-compose -f "tests/integration_setup/docker-compose.yml" up -d --build
  1. Make sure all tests pass:
invoke test --doctest --codeblock
  1. Start making your changes to the main branch (or branch off of it).
  2. Make sure all tests still pass:
invoke test --doctest --codeblock
  1. From the compas_fab directory, stop the docker containers:
docker-compose -f "tests/integration_setup/docker-compose.yml"" down
  1. Check there are no linter errors:
invoke lint
  1. Add yourself to AUTHORS.rst.
  2. Commit your changes and push your branch to GitHub.
  3. Create a pull request through the GitHub website.

During development, use pyinvoke tasks on the command prompt to ease recurring operations:

  • invoke clean: Clean all generated artifacts.
  • invoke check: Run various code and documentation style checks.
  • invoke docs: Generate documentation.
  • invoke lint: Run code linter for coding style checks.
  • invoke test: Run all tests and checks in one swift command.
  • invoke: Show available tasks.

Documentation improvements

We could always use more documentation, whether as part of the introduction/examples/usage documentation or API documentation in docstrings.

Documentation is written in reStructuredText and use Sphinx to generate the HTML output.

The project uses Numpy style docstrings, see Sphinx extension Napoleon's documentation for examples.

Once you made the documentation changes locally, run the documentation generation:

invoke docs

Bug reports

When reporting a bug please include:

  • Operating system name and version.
  • Python version.
  • Any details about your local setup that might be helpful in troubleshooting.
  • Detailed steps to reproduce the bug.

Feature requests and feedback

The best way to send feedback is to file an issue on Github. If you are proposing a feature:

  • Explain in detail how it would work.
  • Keep the scope as narrow as possible, to make it easier to implement.

Grasshopper components

Grasshopper user objects need to be built using COMPAS Github Action componentizer.

  1. Apply your changes to the component source code (src/compas_fab/ghpython/components).

  2. Rebuild them:

    invoke build-ghuser-components <path_to_ghio.dll>

  3. Install them on Rhino/Grasshopper as usual:

    python -m compas_rhino.install

The install step does not copy them, but creates a symlink to the location in which they are built, so after the first installation, it is usually not required to reinstall them, only rebuild them (unless a new component is added).

Note

This step requires IronPython 2.7 to be available on the system, ie. ipy should be callable from the command line. The path to the GH_IO.dll is platform-specific, on Mac it is under the GrasshopperPlugin.rhp of the Rhino app and on Windows is in the Grasshopper folder within the Rhino folder in ProgramFiles.

A Note on Architecture for Backend Clients

To maintain consistency from one backend client to another and to promote modularity, we make use of several interfaces. Please reference :ref:`Note on Architecture <architecture>` for more details on how to add or amend a backend client.

Design documents

.. toctree::
    :maxdepth: 1

    architecture