Skip to content

Latest commit

 

History

History
103 lines (79 loc) · 4.66 KB

CONTRIBUTING.md

File metadata and controls

103 lines (79 loc) · 4.66 KB
Raw

Contributing to LNN

Thank you for considering a contribution to Logical Neural Networks, with your assistance we can help grow LNNs as the industry's tool of choice for a true Neuro = Symbolic platform.

We commit to growing LNNs functionality, but we'd also love to see your name expanding into x, adding to growing our list of contributors:

Contributions = Predicate("Contribution")
Growth = Propostion("LNNs Growth", world=World.TRUE)

Implies(Contributions(x), Growth)

Software Setup

  • Due to the complex inference pattern of LNNs upward and downward reasoning strategy, Pycharm is our recommended IDE of choice for development and debugging.
  1. Make sure that the python version you are using corresponds with the setup file, using a fresh conda environment is recommended: 
    conda create -n lnn-contrib python=3.9 -y
conda activate lnn-contrib
  2. Clone the master branch to keep up to date with the latest supported features: 
    git clone https://github.com/IBM/LNN
  3. Install the LNN module as editable 
    cd LNN
pip install -e .

ℹ️ Alternatively to install steps 2+3 above in one step:

pip install -e git+https://github.com/IBM/LNN#egg=lnn
  • Install Black as an external tool/keyboard shortcut to keep to our code style - this automates our pep8 compliance so that you can code without the styling overhead
  • Install and run pytest to ensure that the build is working correctly: 
    pip install pytest
pytest

You are now ready to contribute changes to the codebase

Developing in LNN

Propose a New Issue

  1. You want to propose a new feature and implement it.
    1. Post about your intended feature in an issue, and we shall discuss the design and implementation.
    2. Add labels to the issue, this should include 3 mandatory flags:
      1. A blue thread tag that you are working on
      2. A tag from: bug, invalid, enhancement or question tag
      3. A yellow tag from: reasoning, learning, gm or test
    3. Once we agree that the plan looks good, go ahead and implement it.

  • You may also want to implement a feature or bug-fix for an outstanding issue:

    • Pick an issue
    • Comment that you will be working on this issue.
    • Add yourself to the assignee list

    If you need more context on a particular issue, please ask and we shall guide.

Branching

  • LNN branches should follow git flow style branching

git flow

To create a new feature branch:

git checkout -b feature/my_branch

Please be mindful of existing branches when creating a new branch.

Pull Requests

  1. Use Black formatting to ensure that code contributions abide by our code style

  2. Commits should contain one of the following tags before the commit message: ADD, FIX, MAINT

  3. Run pytest locally to ensure all changes pass

    NB: All code contributions corresponding to enhancement issues should have additional tests accompanying the code changes, located in the tests/ folder.

  4. Propose your code changes as a Pull Request DRAFT that merge into the develop branch.

  5. A passed draft can be changed to a formal Pull Request.

  6. Add a reviewer to your code so that they can get notified of the proposal.

Documentation

LNN documentation can be generated by running generate_docs.sh in docsrc folder.

Handling Circular Imports

A key component in the LNN code base is the Formula abstract class. Formula is a class that refers to itself and the classes that inherit from it. As such, this can lead to circular imports. To overcome circular imports we use dictionaries that are keyed with the names of the subclasses and the values are the subclasses themselves. These dictionaries are populated in the __init__.py of the logic module. Thus, when one needs to work with a subclass, the subclass can be accessed by passing in the name of that subclass to the dictionary. Note that not all classes that inherit from Formula are added to these dictionaries. Please refer to __init__.py if you need to add an existing class or new class to one of the dictionaries.